How-to: Create a custodial account

A custodial account holds an end customer’s funds in Circle’s custody. Circle creates the first custodial account for an end customer when it approves their Know Your Business (KYB). Create more from your backend when an end customer needs them, for example to keep funds for different purposes apart. For background, see Custodial accounts.

Prerequisites

Before you begin, ensure that you’ve:

Obtained an API key for Digital Asset Accounts from your Circle representative.
Onboarded the end customer and waited until KYB is approved. See Onboard customers. Keep their clientEntityId.
Installed cURL on your development machine.

Create the account

Send a create request from your backend with the end customer’s clientEntityId. Generate the idempotency key first, so that you can reuse it if you retry:

IDEMPOTENCY_KEY=$(uuidgen)

curl --request POST \
  --url https://api-sandbox.circle.com/v1/accounts \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotencyKey": "'"$IDEMPOTENCY_KEY"'",
    "clientEntityId": "{clientEntityId}",
    "type": "third_party",
    "purpose": "custody",
    "description": "{description}"
  }'

type and purpose: must be third_party and custody for an end customer’s account.
description: required, up to 255 characters. A label for the account, which you can show to the end customer. It must be unique, ignoring case, among the active accounts of all your end customers. A duplicate returns 409.
idempotencyKey: a UUID v4. Store it before you send the request, and reuse it if you retry.

The response returns the new account:

{
  "data": {
    "accountId": "1000662322",
    "entityId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd",
    "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890",
    "custodyType": "omnibus",
    "type": "third_party",
    "purpose": "custody",
    "status": "active",
    "description": "Operating account",
    "balances": []
  }
}

Save the accountId. custodyType is omnibus for a custodial account. Circle creates a custodial account with status active, so it can receive funds right away. For every field, see Create an account.

Mint

Match

StableFX

Digital Asset Accounts

End User Onboarding

How-to: Create a custodial account

Prerequisites

Create the account

See also

​Prerequisites

​Create the account

​See also

Prerequisites

Create the account

See also