Circle APIs Documentation

Learn how to integrate with Circle APIs to accept traditional and USDC payments, automate payouts, embed multi-asset accounts into your product or service, or power your internet marketplace.

✨ Receive External Funds

Receiving funds from external blockchain addresses into your wallets hosted on Circle is one of the most basic primitives of the 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. Create a New Wallet

For the purpose of this guide, we'll create a brand new wallet to receive the external funds. 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.

{
  "data":{
    "walletId":"1000005062",
    "entityId":"7cbdedb1-d526-46b4-af12-4162a002eb9c",
    "type":"end_user_wallet"
  }
}

3. Create a Deposit Address

Now it's time to create a new blockchain deposit address and associate it with the newly created wallet. You can create a new deposit address using the generate new address endpoint.

Since the Accounts API supports multiple chains and currencies, you have to specify the currency and chain you want to utilize. You can generate an Ethereum address to receive USDC using the command below (generate your own idempotency key).

# Replace ${YOUR_API_KEY} with your API key
# Replace ${WALLET_ID} with the wallet id from the previous step
curl -H 'Accept: application/json' \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X POST --url https://api-sandbox.circle.com/v1/wallets/${WALLET_ID}/addresses \
  --data '{"idempotencyKey": "ed9a7b3b-b45f-4262-a8aa-8dfee5a4f31b", "currency": "USD", "chain": "ETH"}'

You could similarly create an Algorand deposit address by setting chain to ALGO.

You will receive a response like the below.

{
  "data":{
    "address":"0x618b24211048c6ec8b29e8129c2bbc5cf80c9f0b",
    "currency":"USD",
    "chain":"ETH"
  }
}

📘

When creating a Stellar deposit address, note that the response will include a secondary blockchain address identifier, addressTag. This addressTag value must likewise be included when performing transfers to the deposit address, otherwise the fund will not go through.

4. Receive the Funds

The sandbox environment is connected to the testing networks of the blockchains where USDC is supported. For BTC and ETH, we use testnet and Ropsten, respectively.

For Ethereum, you can send USDC from a Ropsten wallet in order to fund your Circle hosted wallet. You can obtain some USDC on Ropsten for testing, you can get some by using a USDC faucet. Go to usdcfaucet.com and make sure you choose the Ropsten button. Paste the address you generated above (be very careful to not miss any characters) and hit Submit. You will be able to monitor the transfer on the blockchain by using the Etherscan link provided by the faucet, which should look like the below:

https://ropsten.etherscan.io/tx/0xdff7b1a6f62183b5...1aaf2fbb74bbdba6.

We will soon provide easy ways to receive USDC from the Algorand TestNet, Solana Testnet, and Stellar Testnet for the purpose of testing.

❗️

Do NOT send real USDC to addresses generated in the sandbox environment as your funds might be permanently lost.

5. Check the Status of the Transfer

You can use the retrieve transfers endpoint to find transfers that are destined to the wallet you created earlier. You can use it as in the command below.

# Replace ${YOUR_API_KEY} with your API key
# Replace ${WALLET_ID} with the wallet id from the previous step
curl -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X GET https://api-sandbox.circle.com/v1/transfers?destinationWalletId=${WALLET_ID}

You will receive a response like below.

{
  "data":[
    {
      "id":"8239d630-f4fc-3da1-a4fc-e641186eee79",
      "source":{
        "type":"blockchain",
        "address":null,
        "chain":"ETH"
      },
      "destination":{
        "type":"wallet",
        "id":"1000005062",
        "address":"0x618b24211048c6ec8b29e8129c2bbc5cf80c9f0b"
      },
      "amount":{
        "amount":"1.00",
        "currency":"USD"
      },
      "transactionHash":"0x3ca73e108173b2270f81c09e23dfb518d5e175c0e674df5d2ac9a0743765f5ac",
      "status":"running",
      "createDate":"2020-04-21T11:58:48.505Z"
    }
  ]
}

You can look up the transactionHash on Etherscan's tracker on Ropsten, on Algorand's TestNet Blockchain Explorer, on Solana's Testnet Blockchain Explorer, or on Stellar's Testnet Blockchain Explorer, depending on which chain you used. For BTC, you can use a Bitcoin testnet explorer.

As you can see on the response above, the status shows up initially as running because the transaction has been recently initiated. After waiting a few minutes for it to reach the required block confirmations, the status will change to complete. Once it does so (and only once it does so), Circle will credit the receiving wallet with the value of the transfer.

🎉 Congratulations! You have successfully received USDC using Circle's Accounts API.

Make sure you check our quickstart guide on sending funds externally.

6. 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 5 days ago



✨ Receive External Funds


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.