Send Account Funds Externally

Sending funds from your Circle hosted wallets to external blockchain wallets is one of the most basic primitives of the Circle Accounts API.

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.


Get an API key

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

2. Fund Your Wallet

If you haven't already, make sure you fund your wallet for testing.

3. Send Funds

To send funds externally, you need to start by choosing the hosted wallet you will send from (source) and the blockchain address to send to (destination).

You can use your master wallet as the source wallet. If you haven't noted your master wallet id yet, use this guide to obtain it.

📘

USDC, EURC, BTC, and ETH on Testing Networks

The sandbox environment is connected to the USDC testing networks and [EURC testing]networks](doc:eurc-on-testnet) of the blockchains where supported.

For BTC and ETH, we use testnet and Goerli, respectively.

The destination blockchain address you use has to be a valid address on the desired testing network. Refer to Supported Chains and Currencies to see each chains test network that we use.

For the purpose of this guide, we will transfer funds to the deposit address of the USDC faucet service on Ethereum Goerli. That address is 0x493A9869E3B5f846f72267ab19B76e9bf99d51b1.

🚧

You can transfer any amount you want, provided your source wallet has sufficient balance.

To send funds externally, you will use the create transfer endpoint.

Since the Accounts API supports multiple chains and currencies, you have to specify the currency and chain you want to utilize. You can create a USDC transfer to an Ethereum address by using the command below.

# Replace ${YOUR_API_KEY} with your API key
# Replace ${YOUR_WALLET_ID} with your master wallet id
curl -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X POST https://api-sandbox.circle.com/v1/transfers \
  --data '{"idempotencyKey": "4ca72ac7-5217-49bb-bbe6-e8dcb4c53c25", "source": {"type": "wallet", "id": "${YOUR_WALLET_ID}"}, "destination": {"type": "blockchain", "address": "0x493A9869E3B5f846f72267ab19B76e9bf99d51b1", "chain": "ETH"}, "amount": {"amount": "0.10", "currency": "USD"}}'

Similarly, you can create a USDC transfer to an Algorand address by using the command below.

# Replace ${YOUR_API_KEY} with your API key
# Replace ${YOUR_WALLET_ID} with your master wallet id
curl -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X POST https://api-sandbox.circle.com/v1/transfers \
  --data '{"idempotencyKey": "4ca72ac7-5217-49bb-bbe6-e8dcb4c53c25", "source": {"type": "wallet", "id": "${YOUR_WALLET_ID}"}, "destination": {"type": "blockchain", "address": "BL27TI3CYMFX5URLYNBJJZGV4ABRYJJHBMLRR5OYSVPUVDIUAF66IR4COA", "chain": "ALGO"}, "amount": {"amount": "0.10", "currency": "USD"}}'

In either case, you should receive a response like the below.

{
  "data":{
    "id":"a45e27c1-5191-4202-9fcd-ac120da6a522",
    "source":{
      "type":"wallet",
      "id":"0000000001"
    },
    "destination":{
      "type":"blockchain",
      "address":"0x493A9869E3B5f846f72267ab19B76e9bf99d51b1",
      "chain":"ETH"
    },
    "amount":{
      "amount":"0.10",
      "currency":"USD"
    },
    "status":"pending",
    "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/transfers/${TRANSFER_ID}

You will receive a response like below.

{
  "data":{
    "id":"a45e27c1-5191-4202-9fcd-ac120da6a522",
    "source":{
      "type":"wallet",
      "id":"0000000001"
    },
    "destination":{
      "type":"blockchain",
      "address":"0x493A9869E3B5f846f72267ab19B76e9bf99d51b1",
      "chain":"ETH"
    },
    "amount":{
      "amount":"0.10",
      "currency":"USD"
    },
    "transactionHash":"0xae7ec88780eb946528a3e443373de4c5f82d5311cef0788c72b835b52048b8b3",
    "status":"running",
    "createDate":"2020-04-21T09:38:31.300Z"
  }
}

The very first state transition for a transfer sets the status to pending and the transactionHash to null - at that point Circle has just started processing the on-chain send.

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 the appropriate number of 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 the Circle Accounts API.

Make sure you check our quickstart guide on receiving external funds.

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 Mint 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!