Transfers Quickstart

This guide creates transfers to a crypto address, an email recipient, and a payment method in Sandbox, then shows how to validate, poll status, handle webhooks, and list transfers. The Sandbox does not connect to any blockchain network or settle funds on real fiat rails. Base URL: https://sandbox.cdp.coinbase.com

Prerequisites

Before you begin, you’ll need:

CDP CLI

Install the CDP CLI (requires Node.js 22+):

npm install -g @coinbase/cdp-cli

Configure a Sandbox environment using your CDP Secret API Key JSON file from the CDP Portal:

cdp env sandbox --key-file ./cdp-api-key.json --url https://sandbox.cdp.coinbase.com

Keep the API key secret. Never commit it to source control.

TypeScript SDK

Install the SDK (requires Node.js 22+):

npm install @coinbase/cdp-sdk

Export your API key credentials. CdpClient reads them from the environment automatically:

export CDP_API_KEY_ID="YOUR_API_KEY_ID"
export CDP_API_KEY_SECRET="YOUR_API_KEY_SECRET"

Initialize the client pointed at Sandbox:

main.ts

import { CdpClient } from "@coinbase/cdp-sdk";
import { randomUUID } from "node:crypto";

const cdp = new CdpClient({
  basePath: "https://sandbox.cdp.coinbase.com/platform",
});

Keep API keys secret. Never commit them to source control.

A funded Sandbox account

See the Custodial Accounts Quickstart for setting up a Sandbox account with funds.Set the account ID:

export ACCOUNT_ID="account_db458f63-..."

Sandbox transfers do not move real funds. Crypto targets are placeholder addresses, email targets are mock recipients, and payment method targets simulate fiat rails. Do not use real recipient details when testing in Sandbox.

1. Create a transfer to a crypto address

Send USDC from the funded account to an external on-chain address. In Sandbox, use these reserved addresses to test specific outcomes:

Reserved address	Outcome
`0x1111111111111111111111111111111111111111`	Success
`0x2222222222222222222222222222222222222222`	Invalid target
`0x3333333333333333333333333333333333333333`	Invalid address
`0x4444444444444444444444444444444444444444`	Unsupported network

Send to the success address:

CDP CLI
TypeScript SDK

cdp api -X POST /platform/v2/transfers -e sandbox \
  source.accountId=$ACCOUNT_ID \
  source.asset=usdc \
  target.network=base \
  target.address=0x1111111111111111111111111111111111111111 \
  target.asset=usdc \
  amount=5.00 \
  asset=usdc \
  'execute:=true'

main.ts

const transfer = await cdp.transfers.createTransfer({
  idempotencyKey: randomUUID(),
  source: { accountId: "YOUR_ACCOUNT_ID", asset: "usdc" },
  target: {
    address: "0x1111111111111111111111111111111111111111",
    network: "base",
    asset: "usdc",
  },
  amount: "5.00",
  asset: "usdc",
  execute: true,
});

console.log(JSON.stringify(transfer, null, 2));

Example response

{
  "transferId": "transfer_8b707d29-4690-4948-b645-de1cd1f5fd05",
  "status": "completed",
  "source": {
    "accountId": "account_db458f63-418a-4a91-a045-fab93ac35c3f",
    "asset": "usdc"
  },
  "target": {
    "network": "base",
    "address": "0x1111111111111111111111111111111111111111",
    "asset": "usdc"
  },
  "sourceAmount": "5.00",
  "sourceAsset": "usdc",
  "targetAmount": "5.00",
  "targetAsset": "usdc",
  "createdAt": "2026-02-11T23:19:24.086Z",
  "updatedAt": "2026-02-11T23:19:24.183Z"
}

Reserved address failure responses

Use the same create-transfer payload as the success example and replace only target.address to test deterministic Sandbox failures:

Invalid target
Invalid address
Unsupported network

Address: 0x2222222222222222222222222222222222222222Expected response: HTTP 400

{
  "errorType": "invalid_request",
  "errorMessage": "'target' is invalid: must match one of [Account, Payment Method, Onchain Address, Email Instrument]. Account requires 'accountId'; Payment Method requires 'paymentMethodId'; Onchain Address requires 'network'; Email Instrument requires 'email'"
}

Address: 0x3333333333333333333333333333333333333333Expected response: HTTP 400

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid onchain address for network base."
}

Address: 0x4444444444444444444444444444444444444444Expected response: HTTP 400

{
  "errorType": "invalid_request",
  "errorMessage": "base is not a supported network."
}

Save the transfer ID for later steps:

export TRANSFER_ID="transfer_8b707d29-4690-4948-b645-de1cd1f5fd05"

2. Create a transfer to an email

Send USDC to a Coinbase user by email. In Sandbox, use these reserved test emails to avoid privacy issues with real addresses:

Test email	Outcome
`testuser1@domain.com`	Success
`testuser2@domain.com`	Success
`sandboxinvalidtarget@domain.com`	Invalid email
`sandboxexecutionfails@domain.com`	Validation passes, execution fails (synchronous `422`)
`sandboxasyncfailure@domain.com`	Execution accepted (`IN_PROGRESS`), then transitions to `FAILED` async

Send to the success email:

CDP CLI
TypeScript SDK

cdp api -X POST /platform/v2/transfers -e sandbox \
  source.accountId=$ACCOUNT_ID \
  source.asset=usdc \
  target.email=testuser1@domain.com \
  target.asset=usdc \
  amount=5.00 \
  asset=usdc \
  'execute:=true'

main.ts

const transfer = await cdp.transfers.createTransfer({
  idempotencyKey: randomUUID(),
  source: { accountId: "YOUR_ACCOUNT_ID", asset: "usdc" },
  target: { email: "testuser1@domain.com", asset: "usdc" },
  amount: "5.00",
  asset: "usdc",
  execute: true,
});

console.log(`${transfer.transferId}: ${transfer.status}`);

Any email not listed above returns a 4xx error. This prevents Sandbox from validating real email addresses.

Reserved email failure responses

Use the reserved email addresses to exercise validation, synchronous execution, and asynchronous failure paths.

Invalid email target
Execution failure
Async failure

Use sandboxinvalidtarget@domain.com with execute: true.Expected response: HTTP 400

{
  "correlationId": "90d67ad3-d067-41d8-816f-10f3a0144502",
  "errorLink": "https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request",
  "errorMessage": "Target email is invalid.",
  "errorType": "invalid_request"
}

Use sandboxexecutionfails@domain.com to test the case where validation succeeds but execution fails.

Request	Expected result
`validateOnly: true`	HTTP `200` with status `quoted`
`execute: true`	HTTP `422`

Expected execute response:

{
  "correlationId": "90d67ad3-d067-41d8-816f-10f3a0144502",
  "errorMessage": "Sandbox: simulated execution failure.",
  "errorType": "invalid_request"
}

Use sandboxasyncfailure@domain.com with execute: true to test async processing failures. The API initially returns HTTP 200 with status processing, then the transfer transitions to failed after about 500 ms.Expected initial response:

{
  "transferId": "transfer_abc123...",
  "status": "processing",
  "target": {
    "asset": "usdc",
    "email": "sandboxasyncfailure@domain.com"
  }
}

Webhook sequence:

payments.transfers.processing, transfer accepted and debit taken
payments.transfers.failed, async processing failed

3. Create a fiat withdrawal to a payment method

Withdraw USD from the account to a bank-rail payment method (Fedwire, SWIFT, or SEPA). The rail is determined by the payment method itself. Sandbox auto-provisions mock payment methods on every entity. List them and pick one to use:

cdp api /platform/v2/payment-methods -e sandbox

export PAYMENT_METHOD_ID="paymentMethod_8e03978e-..."

Send the withdrawal:

CDP CLI
TypeScript SDK

cdp api -X POST /platform/v2/transfers -e sandbox \
  source.accountId=$ACCOUNT_ID \
  source.asset=usd \
  target.paymentMethodId=$PAYMENT_METHOD_ID \
  target.asset=usd \
  amount=100.00 \
  asset=usd \
  'execute:=true'

main.ts

const transfer = await cdp.transfers.createTransfer({
  idempotencyKey: randomUUID(),
  source: { accountId: "YOUR_ACCOUNT_ID", asset: "usd" },
  target: { paymentMethodId: "YOUR_PAYMENT_METHOD_ID", asset: "usd" },
  amount: "100.00",
  asset: "usd",
  execute: true,
});

console.log(`${transfer.transferId}: ${transfer.status}`);

4. Validate before executing

Use validateOnly: true to verify recipient details before committing a transfer. This is useful for preflight checks on user-entered addresses or emails:

CDP CLI
TypeScript SDK

cdp api -X POST /platform/v2/transfers -e sandbox \
  source.accountId=$ACCOUNT_ID \
  source.asset=usdc \
  target.network=base \
  target.address=0x1111111111111111111111111111111111111111 \
  target.asset=usdc \
  amount=5.00 \
  asset=usdc \
  'validateOnly:=true' \
  'execute:=false'

main.ts

await cdp.transfers.createTransfer({
  idempotencyKey: randomUUID(),
  source: { accountId: "YOUR_ACCOUNT_ID", asset: "usdc" },
  target: {
    address: "0x1111111111111111111111111111111111111111",
    network: "base",
    asset: "usdc",
  },
  amount: "5.00",
  asset: "usdc",
  validateOnly: true,
  execute: false,
});
console.log("Transfer validation successful");

A 200 response means the transfer would succeed. A 4xx response contains an errorType explaining why validation failed.

validateOnly and execute are mutually exclusive. Do not set both to true.

5. Check transfer status

Poll the transfer to see its current status:

CDP CLI
TypeScript SDK

cdp api /platform/v2/transfers/$TRANSFER_ID -e sandbox --jq=.status

main.ts

const t = await cdp.transfers.getTransferById({
  transferId: "YOUR_TRANSFER_ID",
});
console.log(t.status);

6. Handle webhooks

In production, subscribe to payments.transfers.* events to receive real-time status updates rather than polling. See Webhooks for setup. Events fired for a successful transfer:

payments.transfers.processing, transfer is executing
payments.transfers.completed, transfer succeeded

Events fired for a failed transfer:

payments.transfers.processing, transfer is executing
payments.transfers.failed, transfer failed; inspect failureReason

7. List transfers

View all transfers for your entity:

CDP CLI
TypeScript SDK

cdp api /platform/v2/transfers -e sandbox

main.ts

const { transfers } = await cdp.transfers.listTransfers();

for (const t of transfers) {
  console.log(`${t.transferId}: ${t.status}`);
}

Move to production

To run this flow on real rails, switch from the Sandbox base URL to the production base URL and use a production API key. Production transfers move real funds: crypto targets settle on-chain, email targets credit real Coinbase users, and payment method targets execute on Fedwire, SWIFT, or SEPA.

Transfers overview

Transfer types, fee quotes, travel rule, and lifecycle

Deposit Destinations

Receive inbound crypto into a custodial account

Webhooks

Subscribe to real-time transfer status events

REST API reference

Create, execute, list, and get transfers

GET STARTED

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

CUSTOMERS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

Prerequisites

1. Create a transfer to a crypto address

Reserved address failure responses

2. Create a transfer to an email

Reserved email failure responses

3. Create a fiat withdrawal to a payment method

4. Validate before executing

5. Check transfer status

6. Handle webhooks

7. List transfers

Move to production

What to read next

Transfers overview

Deposit Destinations

Webhooks

REST API reference

​Prerequisites

​1. Create a transfer to a crypto address

​Reserved address failure responses

​2. Create a transfer to an email

​Reserved email failure responses

​3. Create a fiat withdrawal to a payment method

​4. Validate before executing

​5. Check transfer status

​6. Handle webhooks

​7. List transfers

​Move to production

​What to read next

Transfers overview

Deposit Destinations

Webhooks

REST API reference

Prerequisites

1. Create a transfer to a crypto address

Reserved address failure responses

2. Create a transfer to an email

Reserved email failure responses

3. Create a fiat withdrawal to a payment method

4. Validate before executing

5. Check transfer status

6. Handle webhooks

7. List transfers

Move to production

What to read next