Skip to main content

Wallet API: Transactions

Deprecating Select Parameters on February 7

On 7 February 2024, select parameters for SIWC v2 List Transactions and Show Transaction APIs will be deprecated, and some will be added and updated.

On 31 March 2024, deprecated parameters will be removed entirely for these endpoints.

To view the new schema after Feb 7, pass new_version_opt_in=true in the request url.

DEPRECATING

ADDING

UPDATING

Table of Endpoints

NameMethodEndpointScope
Send MoneyPOST/v2/accounts/:account_id/transactionswallet:transactions:send
Transfer MoneyPOST/v2/accounts/:account_id/transactionswallet:transactions:transfer
List TransactionsGET/v2/accounts/:account_id/transactionswallet:transactions:read
Show TransactionGET/v2/accounts/:account_id/transactions/:transaction_idwallet:transactions:read

Overview

The Transaction resource represents an event on the account. An amount can be positive (credit) or negative (debit). Transactions with counterparties have either a to or from field.

caution

As transactions represent multiple objects, resources with new type or status values may be added over time. See more about enumerable values.

Transaction Types

caution

The send type is no longer the default type and is now restricted to sending transactions only.

A new type, tx, is now the default and uncategorized. We are working on reducing transactions belonging to tx and implementing dedicated types as much as possible.

Transaction types currently available:

NewTransaction TypeDescription
advanced_trade_fillFills for an advanced trade order
buyBuy a digital asset
xclawbackRecover money already disbursed
xderivatives_settlementDaily settlement between spot and futures accounts for US futures product
xearn_payoutPayout for user earn on Coinbase
fiat_depositDeposit funds into a fiat account from a financial institution
fiat_withdrawalWithdraw funds from a fiat account
xincentives_shared_clawbackClawback incentive payout from customer account
xintx_depositDeposit crypto to customer international account
xintx_withdrawalWithdraw crypto from customer international account
receiveReceive a digital asset
requestRequest a digital asset from a user or email
sellSell a digital asset
sendSend a supported digital asset to a corresponding address or email.

Note: Previously functioned as a default catch-all type. Now it is restricted to send transactions only.
xstaking_transferFunds from primary account moved to staked account
xsubscription_rebateTransaction for Coinbase subscription rebate
xsubscriptionTransaction for Coinbase subscription
tradeExchange one cryptocurrency for another cryptocurrency or fiat currency
transferTransfer funds between two of your own accounts
xtxDefault transaction type, uncategorized.

Note: Previously defined as the send type.
xunstaking_transferFunds from staked funds moved to primary account
xunsupported_asset_recoveryRecover unsupported ERC-20s deposited to Coinbase on ethereum mainnet
xunwrap_assetUnwrap wrapped assets, e.g. cbETH, to wrappable assets, e.g. staked ETH
vault_withdrawalWithdraw funds from a vault account
xwrap_assetWrap wrappable assets, e.g. staked ETH, to wrapped assets, e.g. cbETH

Transaction Statuses

Transaction statuses vary based on the type of the transaction. As both types and statuses can change over time, we recommend that you use details field for constructing human readable descriptions of transactions. Currently available statuses are:

Transaction StatusDescription
canceledTransaction was canceled
completedCompleted transactions (e.g., a send or a buy)
expiredConditional transaction expired due to external factors
failedFailed transactions (e.g., failed buy)
pendingPending transactions (e.g., a send or a buy)
waiting_for_clearingVault withdrawal is waiting to be cleared
waiting_for_signatureVault withdrawal is waiting for approval

Parameters

deprecating multiple params for list/show

On 7 Feb 2024, multiple parameters will be deprecated for List Transactions and Show Transaction.

ParameterTypeRequiredDescription
idstringRequiredTransaction ID
typestring, enumRequiredTransaction type
statusstring, enumRequiredStatus
amountmoney hashRequiredAmount of any supported digital asset. Value is negative to indicate the debiting of funds for the following transaction type cases:
  • advanced_trade_fill, sell
  • pro_deposit
native_amountmoney hashRequiredAmount in user's native currency. Value is negative to indicate the debiting of funds for the following transaction type cases:
  • advanced_trade_fill, sell
  • pro_deposit
descriptionstringRequiredUser defined description
created_attimestampRequired
updated_attimestampRequiredDeprecated for List/Show Tx on 7 Feb
resource, constant transactionstringRequired
resource_pathstringRequired
instant_exchangebooleanRequiredDeprecated for List/Show Tx on 7 Feb
advanced_trade_fillhashRequiredOnly provided if the transaction type is advanced_trade_fill. Contains information about the fill posted.
detailshashRequiredDeprecated for List/Show Tx on 7 Feb
Detailed information about the transaction
networkhashOptionalInfo about crypto networks including on-chain transaction hashes. Only available for certain types of transactions.
tohashOptionalReceiving party of a debit transaction. Usually another resource but can be another type like email. Only available for certain types of transactions.
fromhashOptionalOriginating party of a credit transaction. Usually another resource, but can be another type like Bitcoin network. Only available for certain types of transactions.
addresshashOptionalDeprecated for List/Show Tx on 7 Feb
Associated crytpo address for received payment
applicationhashOptionalDeprecated for List/Show Tx on 7 Feb
Associated OAuth2 application
cancelablebooleanOptionalNew for List/Show Tx on 7 Feb
Allowed to cancel transaction; ONLY provided when transaction is a SEND
idemstringOptionalNew for List/Show Tx on 7 Feb
Idempotency key of transaction; ONLY provided when transaction is a SEND
buyhashOptionalNew for List/Show Tx on 7 Feb
Only provided if transaction type is a buy
sellhashOptionalNew for List/Show Tx on 7 Feb
Only provided if transaction type is a sell
tradehashOptionalNew for List/Show Tx on 7 Feb
Only provided if transaction type is a trade

Advanced Trade Fill

ParameterTypeDescription
fill_pricestringPrice this fill was posted at
product_idstring
order_idstringThe UUID of the order this fill belongs to
commissionCommission on the entire order. This commission is not per fill. Always represented in quote currency.
order_sidestring, enumSide the order was placed on. Possible values: BUY, SELL

Details

deprecating details for list/show

On 7 Feb 2024, the details object will be deprecated for List Transactions and Show Transaction.

ParameterTypeDescription
titlestringDescription of transaction with currency. Example: "Received Bitcoin"
subsidebar_labelstring or null
headerstringAmount received, in amount and equivalent native amount. Example: "Received 0.005378 BTC ($49.92)"
healthstringHealth of transaction. Example: "Positive"

Network

deprecating status_description for list/show

On 7 Feb 2024, status_description will be deprecated for List Transactions and Show Transaction.

ParameterTypeDescription
statusstring, enumPossible values:
  • off_blockchain
  • confirmed
  • pending
  • unconfirmed
status_descriptionstring or nullDeprecated for List/Show Tx on 7 Feb
Description of status
hashstringNew for List/Show Tx on 7 Feb
Hash for onchain transactions; ONLY provided when transaction is a SEND
transaction_feehashNew for List/Show Tx on 7 Feb
Transaction fee; ONLY provided when transaction is a SEND
network_namestringNew for List/Show Tx on 7 Feb
Name of transaction network; ONLY provided when transaction is a SEND

From

deprecating currency for list/show

On 7 Feb 2024, currency will be deprecated for List Transactions and Show Transaction.

ParameterTypeDescription
idstringUpdated for List/Show Tx on 7 Feb
UUID (and after Feb 7, account) of user who the transaction is from
resourcestring or nullUpdated for List/Show Tx on 7 Feb
user (and after Feb 7, account)
resource_pathstringUpdated for List/Show Tx on 7 Feb
  • If resource is user, this path is in the form of v2/users/{userUUID}
  • (after Feb 7) If resource is account, the path is in the form of /v2/accounts/{accountUUID}>
currencystringDeprecated for List/Show Tx on 7 Feb
Currency user sent

Resource Examples

Transaction Resource (Send)

{
"id": "57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
"type": "send",
"status": "completed",
"amount": {
"amount": "-0.00100000",
"currency": "BTC"
},
"native_amount": {
"amount": "-0.01",
"currency": "USD"
},
"description": null,
"created_at": "2015-03-11T13:13:35-07:00",
"updated_at": "2015-03-26T15:55:43-07:00",
"resource": "transaction",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
"network": {
"status": "off_blockchain",
"name": "bitcoin"
},
"to": {
"id": "a6b4c2df-a62c-5d68-822a-dd4e2102e703",
"resource": "user",
"resource_path": "/v2/users/a6b4c2df-a62c-5d68-822a-dd4e2102e703"
},
"details": {
"title": "Sent bitcoin",
"subtitle": "to User 2"
}
}

Transaction Resource (Buy)

{
"id": "8250fe29-f5ef-5fc5-8302-0fbacf6be51e",
"type": "buy",
"status": "pending",
"amount": {
"amount": "1.00000000",
"currency": "BTC"
},
"native_amount": {
"amount": "10.00",
"currency": "USD"
},
"description": null,
"created_at": "2015-03-26T13:42:00-07:00",
"updated_at": "2015-03-26T15:55:45-07:00",
"resource": "transaction",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/8250fe29-f5ef-5fc5-8302-0fbacf6be51e",
"details": {
"title": "Bought bitcoin",
"subtitle": "using Capital One Bank"
}
}

Send Money

Send funds to a network address for any Coinbase supported asset, or email address of the recipient. No transaction fees are required for off-blockchain cryptocurrency transactions.

tip

Coinbase recommends that you always supply a unique idem field for each transaction.

danger

The Send money API is asynchronous, which means that Coinbase may delay or cancel the send when necessary. Coinbase recommends that you poll the status field for the completed state with the Show a Transaction API. You can also see if a transaction is pending in the Send Money API response.

When used with OAuth2 authentication, this endpoint requires two factor authentication.

HTTP Request

POST https://api.coinbase.com/v2/accounts/:account_id/transactions

Scopes

  • wallet:transactions:send

Arguments

ParameterTypeRequiredDescription
type, constant sendstringRequiredType send is required when sending money
tostringRequiredA blockchain address, or an email of the recipient
amountstringRequiredAmount to be sent
currencystringRequiredCurrency of the amount
descriptionstringOptionalNotes to be included in the email to the recipient
skip_notificationsbooleanOptionalDon't send notification emails for small amounts (e.g., tips)
idemstringOptional[Recommended] A token to ensure idempotence. If a previous transaction with the same idem parameter exists for this sender, that previous transaction is returned and a new one is not created. Max length is 100 characters.
to_financial_institutionbooleanOptionalIf true, send to another financial institution or exchange. Required if this send is to an address and is valued at over USD$3000.
financial_institution_websitestringOptionalThe website of the financial institution or exchange. Required if to_financial_institution is true.
destination_tagstringOptionalFor select currencies, destination_tag or memo indicates the beneficiary or destination of a payment for select currencies. Example: { "type" : "send", "to": "address", "destination_tag" : "memo", "amount": "", "currency": "" }

Examples

Request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions /
-X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
-d '{
"type": "send",
"to": "1AUJ8z5RuHRTqD1eikyfUUetzGmdWLGkpT",
"amount": "0.1",
"currency": "BTC",
"idem": "9316dd16-0c05"
}'

Response (201)

{
"data": {
"id": "3c04e35e-8e5a-5ff1-9155-00675db4ac02",
"type": "send",
"status": "pending",
"amount": {
"amount": "-0.10000000",
"currency": "BTC"
},
"native_amount": {
"amount": "-1.00",
"currency": "USD"
},
"description": null,
"created_at": "2015-01-31T20:49:02Z",
"updated_at": "2015-03-31T17:25:29-07:00",
"resource": "transaction",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/3c04e35e-8e5a-5ff1-9155-00675db4ac02",
"network": {
"status": "unconfirmed",
"hash": "463397c87beddd9a61ade61359a13adc9efea26062191fe07147037bce7f33ed",
"name": "bitcoin"
},
"to": {
"resource": "bitcoin_address",
"address": "1AUJ8z5RuHRTqD1eikyfUUetzGmdWLGkpT"
},
"details": {
"title": "Send bitcoin",
"subtitle": "to User 2"
}
}
}

Transfer Money (between accounts)

Transfer any Coinbase supported digital asset between two of a single user's accounts. Accounts must support the same currency for transfers to be successful. The following transfers are allowed:

  • wallet to wallet
  • wallet to vault

HTTP Request

POST https://api.coinbase.com/v2/accounts/:account_id/transactions

Scopes

  • wallet:transactions:transfer

Arguments

ParameterTypeRequiredDescription
type, constant transferstringRequiredType transfer is required
tostringRequiredID of the receiving account
amountstringRequiredAmount to be transferred
currencystringRequiredCurrency for the amount
descriptionstringOptionalNotes to be included in the transfer

Examples

Request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions /
-X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
-d '{
"type": "transfer",
"to": "58542935-67b5-56e1-a3f9-42686e07fa40",
"amount": "1"
}'

Response (201)

{
"data": {
"id": "2e9f48cd-0b05-5f7c-9056-17a8acb408ad",
"type": "request",
"status": "pending",
"amount": {
"amount": "1.00000000",
"currency": "BTC"
},
"native_amount": {
"amount": "10.00",
"currency": "USD"
},
"description": null,
"created_at": "2015-04-01T10:37:11-07:00",
"updated_at": "2015-04-01T10:37:11-07:00",
"resource": "transaction",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/2e9f48cd-0b05-5f7c-9056-17a8acb408ad",
"to": {
"resource": "email",
"email": "email@example.com"
},
"details": {
"title": "Requested bitcoin",
"subtitle": "from email@example.com"
}
},
}

List Transactions

deprecating parameters

See the announcement for parameters being deprecated on 7 Feb 2024, and removed on 31 March 2024.

Lists the transactions of an account by account ID.

HTTP Request

GET https://api.coinbase.com/v2/accounts/:account_id/transactions

Scopes

  • wallet:transactions:read

Examples

Request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions /
-H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

Response (200)

{
"pagination": {
"ending_before": null,
"starting_after": null,
"limit": 25,
"order": "desc",
"previous_uri": null,
"next_uri": null
},
"data": [
{
"id": "4117f7d6-5694-5b36-bc8f-847509850ea4",
"type": "buy",
"status": "pending",
"amount": {
"amount": "486.34313725",
"currency": "BTC"
},
"native_amount": {
"amount": "4863.43",
"currency": "USD"
},
"description": null,
"created_at": "2015-03-26T23:44:08-07:00",
"updated_at": "2015-03-26T23:44:08-07:00",
"resource": "transaction",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/4117f7d6-5694-5b36-bc8f-847509850ea4",
"details": {
"title": "Bought bitcoin",
"subtitle": "using Capital One Bank"
}
},
{
"id": "005e55d1-f23a-5d1e-80a4-72943682c055",
"type": "request",
"status": "pending",
"amount": {
"amount": "0.10000000",
"currency": "BTC"
},
"native_amount": {
"amount": "1.00",
"currency": "USD"
},
"description": "",
"created_at": "2015-03-24T18:32:35-07:00",
"updated_at": "2015-01-31T20:49:02Z",
"resource": "transaction",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/005e55d1-f23a-5d1e-80a4-72943682c055",
"to": {
"resource": "email",
"email": "rb@coinbase.com"
},
"details": {
"title": "Requested bitcoin",
"subtitle": "from rb@coinbase.com"
}
},
{
"id": "ff01bbc6-c4ad-59e1-9601-e87b5b709458",
"type": "transfer",
"status": "completed",
"amount": {
"amount": "-5.00000000",
"currency": "BTC"
},
"native_amount": {
"amount": "-50.00",
"currency": "USD"
},
"description": "",
"created_at": "2015-03-12T15:51:38-07:00",
"updated_at": "2015-01-31T20:49:02Z",
"resource": "transaction",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/ff01bbc6-c4ad-59e1-9601-e87b5b709458",
"to": {
"id": "58542935-67b5-56e1-a3f9-42686e07fa40",
"resource": "account",
"resource_path": "/v2/accounts/58542935-67b5-56e1-a3f9-42686e07fa40"
},
"details": {
"title": "Transfered bitcoin",
"subtitle": "to Secondary Account"
}
},
{
"id": "57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
"type": "send",
"status": "completed",
"amount": {
"amount": "-0.00100000",
"currency": "BTC"
},
"native_amount": {
"amount": "-0.01",
"currency": "USD"
},
"description": null,
"created_at": "2015-03-11T13:13:35-07:00",
"updated_at": "2015-03-26T15:55:43-07:00",
"resource": "transaction",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
"network": {
"status": "off_blockchain",
"name": "bitcoin"
},
"to": {
"id": "a6b4c2df-a62c-5d68-822a-dd4e2102e703",
"resource": "user",
"resource_path": "/v2/users/a6b4c2df-a62c-5d68-822a-dd4e2102e703"
},
"details": {
"title": "Send bitcoin",
"subtitle": "to User 2"
}
}
]
}

Show Transaction

deprecating parameters

See the announcement for parameters being deprecated on 7 Feb 2024, and removed on 31 March 2024.

Get a single transaction for an account.

HTTP Request

GET https://api.coinbase.com/v2/accounts/:account_id/transactions/:transaction_id

Scopes

  • wallet:transactions:read

Examples

Request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/57ffb4ae-0c59-5430-bcd3-3f98f797a66c /
-H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

Response (200)

{
"data": {
"id": "57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
"type": "send",
"status": "completed",
"amount": {
"amount": "-0.00100000",
"currency": "BTC"
},
"native_amount": {
"amount": "-0.01",
"currency": "USD"
},
"description": null,
"created_at": "2015-03-11T13:13:35-07:00",
"updated_at": "2015-03-26T15:55:43-07:00",
"resource": "transaction",
"resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
"network": {
"status": "off_blockchain",
"name": "bitcoin"
},
"to": {
"id": "a6b4c2df-a62c-5d68-822a-dd4e2102e703",
"resource": "user",
"resource_path": "/v2/users/a6b4c2df-a62c-5d68-822a-dd4e2102e703"
},
"details": {
"title": "Send bitcoin",
"subtitle": "to User 2"
}
}
}

Was this helpful?