Transfers

Create transfer

Changed on

Create a new transfer to move funds from a source to a target. All transfers first transition to quoted. If execute: false, the transfer stays quoted until you call /v2/transfers/{transferId}/execute. If execute: true, quoted status emits momentarily before the transfer moves to processing, where execution proceeds. Subscribe to the transfers webhook to follow progress in real time instead of polling.

post/v2/transfers

Request

  • Base URL: https://api.cdp.coinbase.com/platform
  • URL: https://api.cdp.coinbase.com/platform/v2/transfers
  • Auth: HTTP bearer

Headers

X-Idempotency-Keystring

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.

Request body

amountstring required

A positive decimal string without scientific notation or whitespace.

assetstring required

The symbol of the asset (e.g., eth, usd, usdc, usdt).

amountType'target' | 'source'

Specifies whether the given amount is to be received by the target or taken from the source.

  • target: The transfer target receives the exact value specified in amount. Fees are added to the amount taken from the transfer source.
  • source: The transfer target receives the value specified in amount, minus any fees.
validateOnlyboolean

If true, validates the transfer without initiating it. If the request is valid, a 2xx will be returned. If the request is invalid, a 4xx error will be returned. The response will include an errorType, for e.g. invalid_target if the specified target cannot receive funds.

executeboolean required

Whether to immediately execute the transfer. If false, the transfer will be created in quoted status and must be executed manually via the /execute endpoint.

metadataMetadata

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.

Example request

{
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "target": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "amount": "100.00",
  "asset": "usd",
  "amountType": "source",
  "execute": true,
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  },
  "travelRule": {
    "isSelf": false,
    "isIntermediary": true,
    "attestVerifiedWalletOwnership": true,
    "originator": {
      "name": "John Doe",
      "address": {
        "line1": "123 Main St",
        "line2": "Unit 201",
        "city": "San Francisco",
        "state": "California",
        "postCode": "94105",
        "countryCode": "US"
      },
      "financialInstitution": "PayPal, Inc.",
      "virtualAssetServiceProvider": {
        "identifier": "5493001KJTIIGC8Y1R17",
        "name": "Fidelity Digital Asset Services, LLC",
        "address": {
          "line1": "123 Market St",
          "line2": "Suite 400",
          "city": "San Francisco",
          "state": "California",
          "postCode": "94105",
          "countryCode": "US"
        }
      },
      "personalId": "123-45-6789",
      "dateOfBirth": {
        "day": "15",
        "month": "08",
        "year": "1990"
      }
    },
    "beneficiary": {
      "name": "Jane Smith",
      "address": {
        "line1": "456 Oak Ave",
        "city": "Paris",
        "postCode": "75001",
        "countryCode": "FR"
      },
      "walletType": "custodial"
    }
  }
}

Response

Successfully created transfer.

transferIdstring

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

status'quoted' | 'processing' | 'completed' | 'failed'

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

sourceAmountstring

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

sourceAssetstring

The symbol of the asset (e.g., eth, usd, usdc, usdt).

targetAmountstring

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.

targetAssetstring

The symbol of the asset (e.g., eth, usd, usdc, usdt).

completedAtstring date-time

The date and time the transfer was completed.

failureReasonstring

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

expiresAtstring 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.

executedAtstring date-time

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

createdAtstring date-time

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

updatedAtstring date-time

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

metadataMetadata

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.

Example response

{
  "transferId": "transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "status": "completed",
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usd"
  },
  "target": {
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "network": "base",
    "asset": "usdc"
  },
  "sourceAmount": "103.50",
  "sourceAsset": "usd",
  "targetAmount": "100.00",
  "targetAsset": "usdc",
  "completedAt": "2025-01-01T00:05:00Z",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:05:00Z"
}

Changes

  • 156440e9f8dfRevision changes
    • warning

      added the new incompatible_event_types enum value to the response property for the response status

    • warning

      added the new incompatible_event_types enum value to the response property for the response status

    • warning

      added the new incompatible_event_types enum value to the response property for the response status

    • warning

      added the new invalid_webhook_headers enum value to the response property for the response status

    • warning

      added the new invalid_webhook_headers enum value to the response property for the response status

    • warning

      added the new invalid_webhook_headers enum value to the response property for the response status

    • warning

      added the new invalid_webhook_url enum value to the response property for the response status

    • warning

      added the new invalid_webhook_url enum value to the response property for the response status

    • warning

      added the new invalid_webhook_url enum value to the response property for the response status

    • warning

      added the new mandate_action_pending enum value to the response property for the response status

    • warning

      added the new mandate_action_pending enum value to the response property for the response status

    • warning

      added the new mandate_action_pending enum value to the response property for the response status

    • warning

      added the new mandate_canceled enum value to the response property for the response status

    • warning

      added the new mandate_canceled enum value to the response property for the response status

    • warning

      added the new mandate_canceled enum value to the response property for the response status

    • warning

      added the new mandate_expired enum value to the response property for the response status

    • warning

      added the new mandate_expired enum value to the response property for the response status

    • warning

      added the new mandate_expired enum value to the response property for the response status

    • warning

      added the new mandate_invalid_status enum value to the response property for the response status

    • warning

      added the new mandate_invalid_status enum value to the response property for the response status

    • warning

      added the new mandate_invalid_status enum value to the response property for the response status

    • warning

      added the new mandate_policy_violation enum value to the response property for the response status

    • warning

      added the new mandate_policy_violation enum value to the response property for the response status

    • warning

      added the new mandate_policy_violation enum value to the response property for the response status

    • warning

      added the new mandate_revoked enum value to the response property for the response status

    • warning

      added the new mandate_revoked enum value to the response property for the response status

    • warning

      added the new mandate_revoked enum value to the response property for the response status

    • warning

      added the new subscription_limit_exceeded enum value to the response property for the response status

    • warning

      added the new subscription_limit_exceeded enum value to the response property for the response status

    • warning

      added the new subscription_limit_exceeded enum value to the response property for the response status

  • 229ed860a74bRevision changes
    • warning

      added the new mfa_challenge_not_found enum value to the response property for the response status

    • warning

      added the new mfa_challenge_not_found enum value to the response property for the response status

    • warning

      added the new mfa_challenge_not_found enum value to the response property for the response status

    • warning

      added the new operation_in_progress enum value to the response property for the response status

    • warning

      added the new operation_in_progress enum value to the response property for the response status

    • warning

      added the new operation_in_progress enum value to the response property for the response status