Execute transfer - Coinbase Developer Documentation

Authorizations

Authorization

string

header

required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Headers

X-Idempotency-Key

string

An optional string request header for making requests safely retryable. When included, duplicate requests with the same key will return identical responses. Refer to our Idempotency docs for more information on using idempotency keys.

Required string length: 1 - 128

Path Parameters

transferId

string

required

The ID of the transfer.

Pattern: ^transfer_[a-f0-9\-]{36}$

Response

Successfully committed a transfer.

A Transfer represents all the information needed to execute a transfer and tracks the lifecycle of a transfer from initiation through completion or failure.

source

Account · object

required

The source of the transfer.

Account
Payment Method
Onchain Address
Originating Bank Account (US)

Show child attributes

Example:

{
  "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "asset": "usd"
}

target

Account · object

required

The target of the transfer.

Account
Payment Method
Onchain Address
Email Instrument

Show child attributes

Example:

{
  "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "asset": "usd"
}

transferId

string

The ID of the transfer. Required when validateOnly is false.

Example:

"transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114"

status

enum<string>

The current status of the transfer, indicating what action you need to take next. Required when validateOnly is false.

Available options:

quoted,

processing,

completed,

failed

Example:

"quoted"

sourceAmount

string

The amount of the source asset that will be transferred out, as a decimal string in standard unit denomination.

Example:

"103.50"

sourceAsset

string

The asset symbol of the source amount.

Required string length: 1 - 42

Example:

"usd"

targetAmount

string

The amount of the target asset received, as a decimal string in standard unit denomination. May be omitted in the quoted state if the value cannot be guaranteed; see estimate.targetAmount for the expected value. Populated with the actual executed amount once the transfer completes.

Example:

"100.00"

targetAsset

string

The asset symbol of the target amount.

Required string length: 1 - 42

Example:

"usdc"

exchangeRate

object

Exchange rate information for currency conversion. The rate indicates how much of the target asset is equivalent to one unit of the source asset. May be omitted in the quoted state if the rate cannot be guaranteed; see estimate.exchangeRate for the expected rate. Populated with the actual executed rate once the transfer completes.

Show child attributes

Example:

{
  "sourceAsset": "usd",
  "targetAsset": "usdc",
  "rate": "1"
}

fees

object[]

The fees associated with this transfer. Different transfer types have different fee structures. May be omitted in the quoted state if the fees cannot be guaranteed; see estimate.fees for the expected fees. Populated with the actual fees once the transfer completes.

Show child attributes

Example:

[
  {
    "type": "bank",
    "amount": "20",
    "asset": "usd"
  },
  {
    "type": "conversion",
    "amount": "1.00",
    "asset": "usdc"
  },
  {
    "type": "network",
    "amount": "0.01",
    "asset": "usdc"
  }
]

estimate

object

Captures estimated values for transfers where amounts can't be guaranteed (e.g., USDC -> EURC).

The values in estimate are not modified after a transfer is executed. They are preserved as an immutable record of the original pre-execution snapshot.

The actual executed values are populated in the transfer resource post-execution.

Show child attributes

Example:

{
  "exchangeRate": {
    "sourceAsset": "usdc",
    "targetAsset": "eur",
    "rate": "0.85"
  },
  "targetAmount": "85.00",
  "targetAsset": "eur",
  "fees": [
    {
      "type": "conversion",
      "amount": "0.01",
      "asset": "usdc"
    }
  ],
  "estimatedAt": "2023-10-08T14:30:00Z"
}

completedAt

string<date-time>

The date and time the transfer was completed.

Example:

"2025-01-01T00:05:00Z"

failureReason

string

The reason for failure, if the transfer failed. Only present when status is failed.

Example:

"Insufficient balance to complete this transfer."

expiresAt

string<date-time>

The date and time when this transfer will expire if not executed. Only present for quoted status. A new transfer must be created to obtain an updated quote after expiration. Required when validateOnly is false.

Example:

"2025-01-01T00:15:00Z"

executedAt

string<date-time>

The date and time the transfer was executed and moved to processing. Only present when status has progressed beyond quoted.

Example:

"2025-01-01T00:01:30Z"

createdAt

string<date-time>

The date and time the transfer was created. Required when validateOnly is false.

Example:

"2025-01-01T00:00:00Z"

updatedAt

string<date-time>

The date and time the transfer was last updated. Required when validateOnly is false.

Example:

"2025-01-01T00:00:00Z"

metadata

object

Optional metadata as key-value pairs. Use this to store additional structured information on a resource, such as customer IDs, order references, or any application-specific data. Up to 10 key/value pairs may be provided. Keys and values are both strings. Keys must be ≤ 40 characters; values must be ≤ 500 characters.

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

details

object

Additional details about the transfer. For example, if the transfer was sent to a deposit destination, the information about that destination will be included in this field.

Show child attributes

Example:

{
  "depositDestination": {
    "id": "depositDestination_af2937b0-9846-4fe7-bfe9-ccc22d935114"
  },
  "onchainTransactions": [
    {
      "transactionHash": "0x363cd3b3d4f49497cf5076150cd709307b90e9fc897fdd623546ea7b9313cecb",
      "network": "base"
    }
  ]
}