Circle APIs Documentation

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

Swap USDC Across Blockchains

USDC is a fully collateralized US Dollar stablecoin that is supported across multiple chains.

With Circle APIs, developers can seamlessly swap USDC from one chain to another:

From

To

Ethereum USDC

Solana USDC, Algorand USDC, Stellar USDC

Solana USDC

Ethereum USDC, Algorand USDC, Stellar USDC

Algorand USDC

Ethereum USDC, Solana USDC, Stellar USDC

Stellar USDC

Ethereum USDC, Solana USDC, Algorand USDC

In this guide we will walk you through an example where USDC funds are transferred from the Ethereum blockchain over to the Algorand blockchain. However, it makes no difference which chains you decide to use or in which order.

📘

Swapping USDC Across Blockchains

Circle's solution is a "private bridge" approach, where Circle is involved as a counter-party to the swap operation. This means that funds being swapped are temporarily kept in Circle's custody. This process is fully automated and involves no human intervention.

1. Get an API key

If you haven't already, get started with Circle's APIs and have your sandbox API key ready.


Get an API key

2. Receive USDC from the Ethereum blockchain

You can transfer USDC from an external wallet on any of the supported chains into a Circle wallet you control. For the purpose of this guide we will begin by transferring USDC from an external Ethereum wallet.

Create a Wallet

First, create a new wallet to receive the external funds. You can create new hosted wallets using the create wallet endpoint. Use the command below (remember to 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",
    "balances":[]
  }
}

Create a Deposit Address

Wallets themselves are not tied to specific blockchains. Instead, you can generate deposit addresses for wallets, allowing you to receive transfers from different chains.

To continue with our example and create a new Ethereum deposit address, use the generate new address endpoint. You have to properly specify the currency (USD) and chain (ETH) attributes to ensure the API generates a USDC deposit address for the Ethereum blockchain. You can similarly use SOL, ALGO, and XLM to create deposit addresses on other chains.

Create a deposit address for your wallet using the command below.

# 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 will receive a response like the below.

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

📘

addressTag for Stellar

For blockchains that support destination tags or memos, you'll see an additional addressTag attribute returned with the deposit address. When present, this value is required when depositing USDC.

Transfer USDC

❗️

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

Next, it's time to transfer the funds from the Ethereum blockchain. Circle's sandbox environment is connected to the Ethereum Ropsten testing network, so you can send USDC from a Ropsten wallet into your Circle hosted wallet. Visit USDC on Testing Networks to learn more about support on Solana, Algorand, and Stellar.

If you need USDC to send in, you can obtain some USDC on Ropsten for testing by using a USDC faucet. Go to usdcfaucet.com and make sure you choose the Ropsten button. Paste the deposit address you created 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 Ropsten Etherscan link provided by the faucet, which should look like the below:

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

The USDC faucet currently has Algorand support as well. To obtain USDC on the Solana and Stellar test networks, you'll want to first fund a test wallet with a payment and then transfer USDC out.

3. 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":"9f6362f4-a3d2-396e-a1eb-b628ec3a29b2",
      "source":{
        "type":"blockchain",
        "chain":"ETH"
      },
      "destination":{
        "type":"wallet",
        "id":"1000005062",
        "address":"0x618b24211048c6ec8b29e8129c2bbc5cf80c9f0b"
      },
      "amount":{
        "amount":"1.00",
        "currency":"USD"
      },
      "transactionHash":"0xbd3085c3faed933f4093a7b93419ca934fa09d62fe62115d4b3f38a4a94e3a89",
      "status":"running",
      "createDate":"2020-09-21T18:50:06.202Z"
    }
  ]
}

You can look up the transactionHash on Etherscan's tracker on Ropsten.

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 30 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. Refer to our confirmations guide to learn about block confirmation requirements for different chains.

At this point you have successfully received USDC from the Ethereum blockchain using the Circle Wallets API.

4. Send USDC to the Algorand blockchain

Once the receiving leg of the swap operation settles, you can initiate the second leg which is sending the USDC funds to an address on a different blockchain using the Create a transfer endpoint.

To continue with our example, you'll need to have an Algorand blockchain address to send to as the destination. Circle's sandbox environment is connected to the Algorand TestNet, so the destination blockchain address has to be a valid Algorand TestNet address.

📘

Algorand Wallet TestNet Account

You can download the Algorand Wallet, switch to TestNet under "Settings" > "Node Settings", and then obtain your account address from the main wallet screen.

Your Algorand TestNet wallet address should look similar to: BL27TI3CYMFX5URLYNBJJZGV4ABRYJJHBMLRR5OYSVPUVDIUAF66IR4COA.

🚧

Opt-in to Accept the USDC Asset

Algorand Standard Assets include a feature called "spam protection" that prevents unknown assets which may have tax, legal, or reputational risk from being sent to users without their explicit approval. In effect users must opt-in to accept new assets such as USDC. You can opt-in by selecting the "Add New Asset" option, and then searching for "USDC" (the USDC asset ID on Algorand TestNet is [10458941](https://developers.circle.com/docs/usdc-on-testnet#usdc-on-algorand-testnet)).

📘

ALGO Dispenser (Faucet)

In order to opt-in on the USDC asset (or any Algorand asset for that matter), you need to pay for a transaction. You can obtain some TestNet ALGO tokens on the TestNet ALGO Dispenser (Faucet).

To send funds to the external Algorand wallet, you will use the create wallet transfer endpoint. Make sure to specify the correct pair of currency and chain attributes that suit the destination blockchain. You can create a USDC transfer to an Algorand blockchain 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": "fbba9d81-72f1-4bf8-97c8-99f1f28995e2", "source": {"type": "wallet", "id": "${YOUR_WALLET_ID}"}, "destination": {"type": "blockchain", "address": "BL27TI3CYMFX5URLYNBJJZGV4ABRYJJHBMLRR5OYSVPUVDIUAF66IR4COA", "chain": "ALGO"}, "amount": {"amount": "1.00", "currency": "USD"}}'

📘

addressTag for Stellar

When creating a transfer, there is an optional addressTag parameter that can be provided. For chains like Stellar that support destination tags or memos, you can use this field to make sure your send is received correctly.

You should receive a response like the below.

{
  "data":{
    "id":"9dd86dfe-72e8-4182-9573-04196cc7d6cb",
    "source":{
      "type":"wallet",
      "id":"1000005062"
    },
    "destination":{
      "type":"blockchain",
      "address":"BL27TI3CYMFX5URLYNBJJZGV4ABRYJJHBMLRR5OYSVPUVDIUAF66IR4COA",
      "chain":"ALGO"
    },
    "amount":{
      "amount":"1.00",
      "currency":"USD"
    },
    "status":"pending",
    "createDate":"2020-09-21T20:31:39.507Z"
  }
}

5. Check the Status of the Transfer

Again, 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":"9dd86dfe-72e8-4182-9573-04196cc7d6cb",
    "source":{
      "type":"wallet",
      "id":"1000005062"
    },
    "destination":{
      "type":"blockchain",
      "address":"BL27TI3CYMFX5URLYNBJJZGV4ABRYJJHBMLRR5OYSVPUVDIUAF66IR4COA",
      "chain":"ALGO"
    },
    "amount":{
      "amount":"1.00",
      "currency":"USD"
    },
    "transactionHash":"PS74XNN7GHNQTVEV52ZMYHR3CWTKLJUFZ5U3DD43P5WO6GO5VDLQ",
    "status":"complete",
    "createDate":"2020-09-23T21:35:03.563Z"
  }
}

Algorand transactions are fast and confirm in less than 5 seconds, so it shouldn't be long before your transfer has status of complete. Solana (~400ms) and Stellar (~5s) transactions are similarly fast as well!

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 about a month ago


Swap USDC Across Blockchains


Suggested Edits are limited on API Reference Pages

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