Settle customer stablecoins as USD

Custodial Wallets require a business account. This recipe assumes your platform is already onboarded with Custodial Wallets enabled. If you’re interested or want to check whether this fits your use case, get in touch and our team will follow up.

Use case: Your customers want to settle corporate balances in stablecoins, but your entity does not want to hold stablecoins on the balance sheet. What you’ll build: Incoming customer USDC is automatically converted to USD and collected in your treasury account, with no stablecoin held on your balance sheet. These steps run in Sandbox, Coinbase’s test environment. To go live, point at production (https://api.cdp.coinbase.com/platform for the SDK, or cdp env production for the CLI) and use a production API key.

Flow of funds

Prerequisites

Your entity is onboarded (KYB’d) with Custodial Wallets enabled. See the Custodial Wallets overview.
Your customer is onboarded and KYC’d, with custody and transfer capabilities for crypto, fiat, and stablecoin. New to onboarding? See the Customers / KYC quickstart.
The CDP CLI or TypeScript SDK installed and pointed at Sandbox. Both require Node.js 22 or later.

Account structure

Role	Account	Purpose
Your platform (entity, KYB’d)	Treasury account (entity-owned)	Collects the converted USD
Your customer (onboarded, KYC’d)	Customer-owned account	Receives USDC and converts it to USD

Install and configure

CDP CLI
TypeScript SDK

npm install -g @coinbase/cdp-cli
cdp env sandbox --key-file ~/Downloads/cdp_api_key.json

npm install @coinbase/cdp-sdk
export CDP_API_KEY_ID="YOUR_API_KEY_ID"
export CDP_API_KEY_SECRET="YOUR_API_KEY_SECRET"

main.ts

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

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

const CUSTOMER_ID = "customer_..."; // your onboarded customer's ID

The CDP SDK is TypeScript-only. For other languages, use the CLI or call the REST API directly. CDP_API_KEY_ID and CDP_API_KEY_SECRET are the id and privateKey from your downloaded key file. Each write passes an idempotencyKey (a random UUID) so a retried request returns the same result instead of creating a duplicate account or transfer.

Pick one path, the CDP CLI or the TypeScript SDK, and follow that tab in every step. Each CLI command runs on its own. The SDK snippets build up a single main.ts file, so the complete runnable script is at the end under Run the SDK flow as scripts.

Copying these commands: anything shown as a placeholder — values ending in ... (like customer_...) or wrapped in <ANGLE_BRACKETS> — must be replaced with your real value before running. Use each code block’s copy button; if you paste through a rich-text editor (Google Docs, Notes), straight quotes " can turn into curly " and the shell will hang on a dquote> prompt.

1. Create your treasury account

Your entity-owned account that collects the USD. Omitting an owner makes the account entity-owned.

CDP CLI
TypeScript SDK

TREASURY_ACCOUNT_ID=$(cdp accounts create name="Treasury account" -e sandbox --jq=.accountId)
echo "TREASURY_ACCOUNT_ID=$TREASURY_ACCOUNT_ID"

Confirm it is entity-owned. The owner should start with entity_:

cdp accounts get $TREASURY_ACCOUNT_ID -e sandbox --jq=.owner

If the owner comes back as customer_... instead, the CLI reused a previous owner from its saved history. Run cdp history clear, then recreate the treasury with a different name and check the owner again.

main.ts

const treasury = await cdp.accounts.createAccount({
  idempotencyKey: randomUUID(),
  name: "Treasury account",
});

Account names must be unique within your entity. A duplicate name returns 409 already_exists.

2. Create the customer’s account

You already have your customer’s ID from onboarding them (the customerId the Customers API returned). Pass it as the owner. Customer-owned accounts also require the end-user’s IP on compliance.requesterIpAddress.

The owner field on createAccount, and compliance on createDepositDestination/createTransfer, are honored by the API but are not yet in the published @coinbase/cdp-sdk types, so strict TypeScript rejects them (TS2353). Until the SDK types are updated, cast these requests with as any (shown in the SDK tabs below). This does not affect the CLI.

How do I get a customer ID?

A customer’s ID is returned when you onboard them through the Customers API: the create-customer call returns a customerId, which you store in your own system. In production your app already has it, so the CUSTOMER_ID below is set by hand only for testing. New to onboarding, or need a test customer in Sandbox (using the magic SSN 000-00-0000)? See the Customers / KYC quickstart.

CDP CLI
TypeScript SDK

export CUSTOMER_ID=customer_...   # your onboarded customer's ID

CUSTOMER_ACCOUNT_ID=$(cdp accounts create \
  owner=$CUSTOMER_ID name="Customer account" \
  compliance.requesterIpAddress=8.8.8.8 \
  -e sandbox --jq=.accountId)
echo "CUSTOMER_ACCOUNT_ID=$CUSTOMER_ACCOUNT_ID"

main.ts

const customerAccount = await cdp.accounts.createAccount({
  idempotencyKey: randomUUID(),
  owner: CUSTOMER_ID,
  name: "Customer account",
  compliance: { requesterIpAddress: "8.8.8.8" },
} as any); // owner + compliance work at runtime but aren't in the SDK types yet

3. Create a liquidation deposit address

Create a crypto deposit destination on the customer’s account, with target.accountId set to that same account and target.asset = usd. Any USDC sent to it converts to USD and lands in the customer’s account.

CDP CLI
TypeScript SDK

DEPOSIT_ADDRESS=$(cdp deposit-destinations create \
  accountId=$CUSTOMER_ACCOUNT_ID \
  type=crypto \
  crypto.network=base \
  target.accountId=$CUSTOMER_ACCOUNT_ID \
  target.asset=usd \
  compliance.requesterIpAddress=8.8.8.8 \
  metadata.reference=77b50ed5-7e8b-41a5-a6ac-ff3cc5a08981 \
  -e sandbox --jq=.crypto.address)
echo "DEPOSIT_ADDRESS=$DEPOSIT_ADDRESS"

main.ts

const destination = await cdp.depositDestinations.createDepositDestination({
  idempotencyKey: randomUUID(),
  type: "crypto",
  accountId: customerAccount.accountId,
  crypto: { network: "base" },
  target: { accountId: customerAccount.accountId, asset: "usd" },
  compliance: { requesterIpAddress: "8.8.8.8" },
  metadata: { reference: randomUUID() },
} as any); // compliance works at runtime but isn't in the SDK types yet
console.log("Deposit address:", destination.crypto?.address);

target.accountId must equal accountId: the converted USD lands in the same account, which is why Step 6 moves it to your treasury. metadata.reference must be a UUID or integer string. Leave target off and deposited USDC stays USDC; the target is what converts it to cash.

4. Customer deposits USDC

No API call here, this step is the customer’s action. Share the deposit address with them; they send USDC to it, and it converts to USD in their account. In production the customer sends USDC on-chain from their own wallet, and your app reacts to the deposit webhook. In Sandbox there is no blockchain, so simulate the deposit in the Portal:

Open the customer account

In Sandbox mode in the CDP Portal, open Accounts and select the customer account.

Open Deposit addresses

Open the Deposit addresses tab and find the address matching your DEPOSIT_ADDRESS.

Simulate the deposit

Click Deposit, enter a USDC amount, and click Deposit now.

CDP Portal deposit modal on the customer account's Deposit addresses tab.

5. Confirm the customer’s USD balance

The customer deposited USDC, but the balance shows USD. That is the liquidation address doing its job.

CDP CLI
TypeScript SDK

cdp accounts balances $CUSTOMER_ACCOUNT_ID -e sandbox

main.ts

const { balances } = await cdp.accounts.listBalances({
  accountId: customerAccount.accountId,
});
console.log(balances);

CDP Portal showing the customer account balance as USD after the USDC deposit converted.

Example response

{
  "balances": [
    {
      "amount": { "USD": { "available": "100", "total": "100" } },
      "asset": { "symbol": "USD", "name": "United States Dollar", "type": "fiat", "decimals": 2 }
    },
    {
      "amount": { "USDC": { "available": "0", "total": "0" } },
      "asset": { "symbol": "USDC", "name": "USDC", "type": "crypto", "decimals": 6 }
    }
  ]
}

The USDC line reads 0 because it was converted to USD.

6. Move the USD to your treasury

Transfer the USD from the customer’s account into your treasury. Because the customer’s account is the source, include compliance.requesterIpAddress. This example transfers $50 of the $100 in the customer’s account. Transfer any amount up to what’s available.

CDP CLI
TypeScript SDK

cdp transfers create -e sandbox \
  source.accountId=$CUSTOMER_ACCOUNT_ID source.asset=usd \
  target.accountId=$TREASURY_ACCOUNT_ID target.asset=usd \
  amount=50.00 asset=usd \
  'execute:=true' \
  compliance.requesterIpAddress=8.8.8.8

main.ts

const transfer = await cdp.transfers.createTransfer({
  idempotencyKey: randomUUID(),
  source: { accountId: customerAccount.accountId, asset: "usd" },
  target: { accountId: treasury.accountId, asset: "usd" },
  amount: "50.00",
  asset: "usd",
  execute: true,
  compliance: { requesterIpAddress: "8.8.8.8" },
} as any); // compliance works at runtime but isn't in the SDK types yet
console.log("Transfer:", transfer.status);

Example response

{
  "transferId": "transfer_...",
  "status": "completed",
  "source": { "accountId": "...", "asset": "usd" },
  "sourceAmount": "50",
  "sourceAsset": "usd",
  "target": { "accountId": "...", "asset": "usd" },
  "targetAmount": "50",
  "targetAsset": "usd",
  "createdAt": "...",
  "executedAt": "...",
  "completedAt": "...",
  "updatedAt": "..."
}

The USD is now collected in your treasury, with no stablecoin held on your balance sheet. Wiring the treasury balance out to a bank (via payment methods) is covered separately.

CDP Portal showing the entity-owned treasury account holding the transferred USD.

Run the SDK flow as scripts

The SDK snippets above build on one client and belong in a single file. Because the customer’s deposit (Step 4) happens in the middle, run it as two scripts: set up, do the deposit, then finish. Save each as a .ts file and run it with npx tsx <file>.ts (Node 22 or later; tsx runs TypeScript directly, no build step).Part 1 — set up (Steps 1 to 3). Prints the account IDs and the deposit address.

main.ts

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

const cdp = new CdpClient({ basePath: "https://sandbox.cdp.coinbase.com/platform" });
const CUSTOMER_ID = "customer_..."; // your onboarded customer's ID

async function main() {
  const treasury = await cdp.accounts.createAccount({
    idempotencyKey: randomUUID(),
    name: "Treasury account",
  });
  console.log("TREASURY_ACCOUNT_ID =", treasury.accountId);

  const customerAccount = await cdp.accounts.createAccount({
    idempotencyKey: randomUUID(),
    owner: CUSTOMER_ID,
    name: "Customer account",
    compliance: { requesterIpAddress: "8.8.8.8" },
  } as any); // owner + compliance work at runtime but aren't in the SDK types yet
  console.log("CUSTOMER_ACCOUNT_ID =", customerAccount.accountId);

  const destination = await cdp.depositDestinations.createDepositDestination({
    idempotencyKey: randomUUID(),
    type: "crypto",
    accountId: customerAccount.accountId,
    crypto: { network: "base" },
    target: { accountId: customerAccount.accountId, asset: "usd" },
    compliance: { requesterIpAddress: "8.8.8.8" },
    metadata: { reference: randomUUID() },
  } as any); // compliance works at runtime but isn't in the SDK types yet
  console.log("DEPOSIT_ADDRESS =", destination.crypto?.address);
}

main().catch(console.error);

Part 2 — after the deposit (Steps 5 to 6). Paste the two account IDs Part 1 printed.

main.ts

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

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

const CUSTOMER_ACCOUNT_ID = "account_..."; // from Part 1
const TREASURY_ACCOUNT_ID = "account_...";  // from Part 1

async function main() {
  const { balances } = await cdp.accounts.listBalances({
    accountId: CUSTOMER_ACCOUNT_ID,
  });
  console.log(balances);

  const transfer = await cdp.transfers.createTransfer({
    idempotencyKey: randomUUID(),
    source: { accountId: CUSTOMER_ACCOUNT_ID, asset: "usd" },
    target: { accountId: TREASURY_ACCOUNT_ID, asset: "usd" },
    amount: "50.00",
    asset: "usd",
    execute: true,
    compliance: { requesterIpAddress: "8.8.8.8" },
  } as any); // compliance works at runtime but isn't in the SDK types yet
  console.log("Transfer:", transfer.status);
}

main().catch(console.error);

Good to know

Liquidation credits the same account the deposit address belongs to. That is why the USD lands in the customer’s account first, and Step 6 moves it to your treasury. A single deposit address cannot sweep directly into a different account.
Reconciliation: attach metadata (a reference or customer ID) to transfers, and query history with cdp transfers list or the Transfers API.

Transfer returns “Invalid source and target pair”? Your treasury is probably customer-owned instead of entity-owned, so the transfer is really between two accounts owned by the same customer. Check the owner with cdp accounts get $TREASURY_ACCOUNT_ID -e sandbox --jq=.owner (it should start with entity_). If it shows customer_, run cdp history clear, recreate the treasury, and confirm the owner is entity_ before retrying.

Customers / KYC

Onboard the customers whose funds this flow moves

Transfers

All transfer types, rails, and lifecycle

Crypto Deposit Destinations

Liquidation addresses and inbound deposits

Webhooks

React to deposits and transfer status in production

Integration guides

Recipes

Flow of funds

Prerequisites

Account structure

Install and configure

1. Create your treasury account

2. Create the customer’s account

3. Create a liquidation deposit address

4. Customer deposits USDC

5. Confirm the customer’s USD balance

6. Move the USD to your treasury

Good to know

What to read next

Customers / KYC

Transfers

Crypto Deposit Destinations

Webhooks

​Flow of funds

​Prerequisites

​Account structure

​Install and configure

​1. Create your treasury account

​2. Create the customer’s account

​3. Create a liquidation deposit address

​4. Customer deposits USDC

​5. Confirm the customer’s USD balance

​6. Move the USD to your treasury

​Good to know

​What to read next

Customers / KYC

Transfers

Crypto Deposit Destinations

Webhooks

Flow of funds

Prerequisites

Account structure

Install and configure

1. Create your treasury account

2. Create the customer’s account

3. Create a liquidation deposit address

4. Customer deposits USDC

5. Confirm the customer’s USD balance

6. Move the USD to your treasury

Good to know

What to read next