How-to: Wire deposits and withdrawals

Link your end customers’ bank accounts to their Digital Asset Accounts so they can move money between traditional banking and stablecoins. Wire deposits convert fiat into stablecoins. Wire withdrawals redeem stablecoin balances and send funds to the linked bank account.

Prerequisites

Before you begin:

Obtain an API key for Digital Asset Accounts from Circle.
Have an onboarded and active account with an accountId.
Install cURL on your development machine.

The Digital Asset Accounts API base URL is https://api-sandbox.circle.com for sandbox and https://api.circle.com for production. Set your API key in the Authorization header using the format Bearer YOUR_API_KEY. See Sandbox environment and Going to production for environment details.

Steps

Step 1. Link a bank account

Link your end customer’s bank account by providing the bank details and billing information.

curl --request POST \
  --url https://api-sandbox.circle.com/v1/banks/wires \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "${ACCOUNT_ID}",
  "idempotencyKey": "${RANDOM_UUID}",
  "accountNumber": "123456789",
  "routingNumber": "021000021",
  "billingDetails": {
    "name": "Acme Corp",
    "line1": "100 Money Street",
    "city": "Boston",
    "district": "MA",
    "postalCode": "01234",
    "country": "US"
  },
  "bankAddress": {
    "bankName": "Chase Bank",
    "city": "New York",
    "country": "US",
    "line1": "270 Park Avenue",
    "district": "NY"
  }
}
'

Response

{
  "data": {
    "id": "b8a025e7-d5e5-4e5a-8e35-2f3a7d1c9b4a",
    "status": "complete",
    "description": "CHASE BANK ****6789",
    "trackingRef": "CIR3XXXYYY",
    "virtualAccountEnabled": false,
    "fingerprint": "abc123def456",
    "billingDetails": {
      "name": "Acme Corp",
      "line1": "100 Money Street",
      "city": "Boston",
      "postalCode": "01234",
      "district": "MA",
      "country": "US"
    },
    "bankAddress": {
      "bankName": "Chase Bank",
      "city": "New York",
      "country": "US"
    },
    "createDate": "2026-03-15T10:00:00Z",
    "updateDate": "2026-03-15T10:00:00Z"
  }
}

Step 2. Get wire instructions

Retrieve the wire instructions for the linked bank account. Share these with your end customer so they can send a wire deposit from their bank.

curl --request GET \
  --url 'https://api-sandbox.circle.com/v1/banks/wires/${WIRE_ID}/instructions?accountId=${ACCOUNT_ID}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'

Response

{
  "data": {
    "trackingRef": "CIR3XXXYYY",
    "beneficiary": {
      "name": "Circle Internet Financial Inc",
      "address1": "99 High Street",
      "address2": "Boston, MA 02110"
    },
    "virtualAccountEnabled": false,
    "beneficiaryBank": {
      "name": "Silicon Valley Bank",
      "routingNumber": "121140399",
      "accountNumber": "1234567890",
      "currency": "USD",
      "country": "US"
    }
  }
}

The trackingRef is a unique reference code that identifies the wire deposit. Your customer must include it in their wire transfer so Circle can match the payment to the correct account.

Your end customer must include the trackingRef when sending the wire transfer. Without this reference, the deposit cannot be matched to the correct account.

Step 3. Deposit fiat (sandbox simulation)

In the sandbox environment, simulate a wire deposit using the mock payments endpoint. In production, your end customer sends a real wire transfer using the instructions from the previous step.

curl --request POST \
  --url https://api-sandbox.circle.com/v1/mocks/payments/wire \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "trackingRef": "${TRACKING_REF}",
  "amount": {
    "amount": "10000.00",
    "currency": "USD"
  },
  "beneficiaryBank": {
    "accountNumber": "1234567890",
    "routingNumber": "121140399"
  }
}
'

Response

{
  "data": {
    "trackingRef": "CIR3XXXYYY",
    "beneficiaryBank": {
      "routingNumber": "121140399",
      "accountNumber": "1234567890"
    },
    "amount": {
      "amount": "10000.00",
      "currency": "USD"
    },
    "status": "pending"
  }
}

Step 4. Check the balance

Confirm that the deposit has been credited to the account.

curl --request GET \
  --url https://api-sandbox.circle.com/v1/accounts/balances/${ACCOUNT_ID} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'

Response

{
  "data": {
    "available": [
      {
        "amount": "10000.00",
        "currency": "USD"
      }
    ],
    "unsettled": []
  }
}

Step 5. Withdraw to a bank account

To withdraw stablecoins as fiat, create a withdrawal that specifies the amount, the destination wire account, and the source account.

curl --request POST \
  --url https://api-sandbox.circle.com/v1/accounts/withdrawals \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "${RANDOM_UUID}",
  "destination": {
    "type": "wire",
    "id": "${WIRE_ID}"
  },
  "amount": {
    "amount": "5000.00",
    "currency": "USD"
  },
  "source": {
    "type": "account",
    "id": "${ACCOUNT_ID}"
  }
}
'

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sourceAccountId": "1017381855",
    "destination": {
      "type": "wire",
      "id": "b8a025e7-d5e5-4e5a-8e35-2f3a7d1c9b4a"
    },
    "amount": {
      "amount": "5000.00",
      "currency": "USD"
    },
    "toAmount": {
      "amount": "5000.00",
      "currency": "USD"
    },
    "status": "pending",
    "createDate": "2026-03-15T14:00:00Z",
    "updateDate": "2026-03-15T14:00:00Z"
  }
}

The withdrawal processes asynchronously. Monitor the status by polling the withdrawals endpoint or by setting up webhook notifications. If the source account has insufficient funds, the API returns an error:

{
  "code": 2,
  "message": "Insufficient funds. The source account does not have enough balance to complete this withdrawal."
}

Verify the account balance before initiating a withdrawal.

List and retrieve wire accounts

You can query linked wire accounts at any time. List all wire accounts for an account

curl --request GET \
  --url 'https://api-sandbox.circle.com/v1/banks/wires?accountId=${ACCOUNT_ID}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'

Get a specific wire account

curl --request GET \
  --url https://api-sandbox.circle.com/v1/banks/wires/${WIRE_ID} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'

Mint

StableFX

Digital Asset Accounts

End User Onboarding

How-to: Wire deposits and withdrawals

Prerequisites

Steps

Step 1. Link a bank account

Step 2. Get wire instructions

Step 3. Deposit fiat (sandbox simulation)

Step 4. Check the balance

Step 5. Withdraw to a bank account

List and retrieve wire accounts

​Prerequisites

​Steps

​Step 1. Link a bank account

​Step 2. Get wire instructions

​Step 3. Deposit fiat (sandbox simulation)

​Step 4. Check the balance

​Step 5. Withdraw to a bank account

​List and retrieve wire accounts

Prerequisites

Steps

Step 1. Link a bank account

Step 2. Get wire instructions

Step 3. Deposit fiat (sandbox simulation)

Step 4. Check the balance

Step 5. Withdraw to a bank account

List and retrieve wire accounts