Quickstart: Create a Sub-Account

Learn the basics of sub-accounts within Circle’s Accounts API.

The Accounts API empowers you to seamlessly create and host digital wallets for your customers, and manage the transfers of funds across accounts within the Circle platform. Sub-accounts are the building blocks within the Accounts infrastructure where the digital funds reside and can be moved between.

1. Get an API key

The Accounts API uses API keys as the mechanism to authenticate client requests. The API key must be set in the Authorization header of the request sent from your backend server. The format of the header is Bearer secret-key-value.To obtain an API key for the sandbox environment, simply create an account and generate a new key in settings - it only takes a few seconds:

Once you have generated your API key, record it in a secure place.

2. Create a new wallet

For the purpose of this guide, we'll create a brand new sub-account wallet. You can create new hosted wallets using the create wallet endpoint. Use the command below (create your own idempotency key).


Replace ${YOUR\_API\_KEY} with your API key.

curl -H 'Content-type: application/json'
 -H "Authorization: Bearer ${YOUR\_API\_KEY}"
 -X POST https\://api-sandbox.circle.com/v1/wallets
 --data '{"idempotencyKey": "4ddef365-f2fc-4a56-95f5-a214c84ba8f4"}'You should receive a response like the below\.Create Wallet Response{  "data":{    "walletId":"1000005062",    "entityId":"7cbdedb1-d526-46b4-af12-4162a002eb9c",    "type":"end\_user\_wallet"  }}**

3. Get a wallet

Now that you’ve created a sub-account wallet, we will use the walletId from the response above to retrieve details. This is an important request for checking balance and description details for a given wallet at any time after creation.


curl --request GET
    --url https\://api-sandbox.circle.com/v1/wallets/1016889587\     --header 'accept: application/json'
    --header 'authorization: Bearer ${YOUR\_API\_KEY}'You should receive a response like the below\.GET a Wallet Response{  "data":{    "walletId":"1000005062",    "entityId":"7cbdedb1-d526-46b4-af12-4162a002eb9c",    "type":"end\_user\_wallet"  }}**

3. List all wallets

In addition to requesting a specific wallet, you have the ability to retrieve a list of all sub-account wallets that have been created. You can make a general request to list all wallets or you can specify parameters in your GET request such as from and to which will limit the response to wallets created within the defined dates set.


curl --request GET
    --url https\://api-sandbox.circle.com/v1/wallets
    --header 'accept: application/json'
    --header 'authorization: Bearer ${YOUR\_API\_KEY}'You should receive a response like the one below\.GET Wallets Response{  "data": \[    {      "walletId": "1016889587",      "entityId": "b3e34c09-69c9-4181-a564-46be0a89084a",      "type": "end\_user\_wallet",      "description": "Jamie’s Wallet",      "balances": \[]    },    {      "walletId": "1016889390",      "entityId": "b3e34c09-69c9-4181-a564-46be0a89084a",      "type": "end\_user\_wallet",      "description": "Main Wallet",      "balances": \[]    },    {      "walletId": "1016885777",      "entityId": "b3e34c09-69c9-4181-a564-46be0a89084a",      "type": "end\_user\_wallet",      "description": "Treasury Wallet",      "balances": \[]    },      ]}]}**

4. Create an internal transfer

Now that you have at least one sub-account within your Circle Mint infrastructure, you can perform an internal (off-chain) transfer.


curl --request POST
    --url https\://api-sandbox.circle.com/v1/transfers
    --header 'accept: application/json'
    --header 'authorization: Bearer ${YOUR\_API\_KEY}'{  "source": {    "type": "wallet",    "id": "1016889390"  },  "destination": {    "type": "wallet",\
    "id": "1016885777"  },"amount": {    "currency": "USD",    "amount": "3.14"  }}'You should receive a response like the one below.{"id":"0107eea3-d661-45d7-8e69-c662b5ec8bb1","source":{"type":"wallet","id":"1016889390"}"destination":{"type":"wallet","id":"1016885777"}"amount":{"amount":"3.14","currency":"USD"}"status":"pending","createDate":"2023-12-11T22:08:23.752Z"}

🎉 Congratulations! You have successfully created a sub-account and initiated an internal transfer within your Circle Mint account.