We refreshed our doc site!
Bookmarked links may have changed
Read release notesLearn 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.
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.
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).
Request
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" }}**
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.
Request
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" }}**
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.
Request
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": \[] }, ]}]}**
Now that you have at least one sub-account within your Circle Mint infrastructure, you can perform an internal (off-chain) transfer.
Request
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.