✨ Send Account Funds Externally
Sending funds from your Circle Account to external blockchain wallets is one of the most basic primitives of the APIs. This quickstart walks through sending USDC USD
externally, the same steps would be taken when sending EUROC EUR
too.
1. Get an API key
Circle's APIs use 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. Fund Your Account
If you haven't already, make sure you fund your account for testing.
3. Send Funds
To send account funds externally, you will need a blockchain address to send to (destination
).
The sandbox environment is connected to the Ethereum Goerli testing network, so the destination blockchain address has to be a valid Goerli address.
USDC is connected to testing networks on other blockchains as well. This guide focuses on Ethereum but works similarly for other blockchains. For information on other testing networks see Test USDC
For the purpose of this guide, we can simply transfer funds to the deposit address of the USDC faucet service on Goerli. That address is 0x493A9869E3B5f846f72267ab19B76e9bf99d51b1
.
You can transfer any amount you want, provided your account has sufficient balance to cover the transfer.
To send funds externally, you will use the create account transfer endpoint.
Since Circle's APIs are designed for multiple future chains and currencies, you have to specify the currency
and chain
you want to utilize. You can create a transfer by using the command below.
# Replace ${YOUR_API_KEY} with your API key
curl -H 'Accept: application/json' \
-H 'Content-type: application/json' \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-X POST https://api-sandbox.circle.com/v1/businessAccount/transfers \
--data '{"idempotencyKey": "4ca72ac7-5217-49bb-bbe6-e8dcb4c53c25", "destination": {"type": "blockchain", "address": "0x493A9869E3B5f846f72267ab19B76e9bf99d51b1", "chain": "ETH"}, "amount": {"amount": "0.10", "currency": "USD"}}'
You should receive a response like the below.
{
"data":{
"id":"a45e27c1-5191-4202-9fcd-ac120da6a522",
"source":{
"type":"wallet",
"id":"1000005019"
},
"destination":{
"type":"blockchain",
"address":"0x493A9869E3B5f846f72267ab19B76e9bf99d51b1",
"chain":"ETH"
},
"amount":{
"amount":"0.10",
"currency":"USD"
},
"transactionHash":"0xae7ec88780eb946528a3e443373de4c5f82d5311cef0788c72b835b52048b8b3",
"status":"complete",
"createDate":"2020-04-21T09:38:31.300Z"
}
}
4. Check the Status of the Transfer
You can use the get transfer endpoint to retrieve details about the status of the transaction. You can use it as in the command below.
# Replace ${YOUR_API_KEY} with your API key
# Replace ${TRANSFER_ID} with the id of the transfer you created earlier
curl -H "Authorization: Bearer ${YOUR_API_KEY}" \
-X GET https://api-sandbox.circle.com/v1/businessAccount/transfers/${TRANSFER_ID}
You will receive a response like below.
{
"data":{
"id":"a45e27c1-5191-4202-9fcd-ac120da6a522",
"source":{
"type":"wallet",
"id":"1000005019"
},
"destination":{
"type":"blockchain",
"address":"0x493A9869E3B5f846f72267ab19B76e9bf99d51b1",
"chain":"ETH"
},
"amount":{
"amount":"0.10",
"currency":"USD"
},
"transactionHash":"0xae7ec88780eb946528a3e443373de4c5f82d5311cef0788c72b835b52048b8b3",
"status":"complete",
"createDate":"2020-04-21T09:38:31.300Z"
}
}
The very first state transition for a transfer sets the status
to created
and the transactionHash
to null
- at that point Circle has just started processing the on-chain send. A few seconds later, Circle will broadcast the transfer and so its status
changes to running
while also displaying the transactionHash
that can be used to track such transfer on chain (you can look it up on Etherscan's tracker on Goerli).
At this point you can consider the transaction complete because it has been successfully broadcasted to the network. Circle's systems will continue to track the transfer for 30 confirmations and its status
will at that point change to complete
. Except for a few specialized applications you do not have to worry about waiting for the complete
state - that's important when receiving external transfers. You can read more about block confirmations here.
🎉 Congratulations! You have successfully sent cryptocurrency using Circle's APIs.
5. Ready for the next step?
If you are in advanced stages of experimenting with our APIs and want to plan moving to production, please start by applying for a Circle Account and subsequently reach out to sales. We'll be happy to walk you through to the next steps.
We can't wait to see what you are going to build!
Updated 6 months ago