Swap USDC Across Blockchains | Circle Wallets API (2024)

Circle APIs enable you to easily transfer USDC funds from one blockchain to another. Circle uses a "private bridge" approach to act 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, so you don’t need to manually interact with both blockchains as usual.

In this example, we'll transfer USDC funds from the Ethereum blockchain to the Algorand blockchain. However, it makes no difference which supported chains you decide to use or in which order.

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

If you don't yet have an API key in the sandbox environment, take a few moments to create a sandbox account. (Learn more about Circle’s sandbox and APIs here.

• You can transfer USDC from an external wallet on any of the supported chains into a Circle wallet you control.

Start by transferring USDC from an external Ethereum wallet.

First, use the command below to create a new wallet to receive the external funds via the create wallet endpoint. Be sure to create your own idempotency key.

# Replace ${YOUR_API_KEY} with your API keycurl -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"}'

The response should look like this:

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

Create a Deposit Address

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

To create a new Ethereum deposit address, use the generate new address endpoint. To ensure the API generates a USDC deposit address for the Ethereum blockchain, specify the origincurrency (USD) and chain (ETH) attributes. Change the chain attribute to create deposit addresses on other supported 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 stepcurl -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"}'

The response should look like this:

{ "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.

Circle's sandbox environment is connected to the Ethereum Sepolia testing network, so you can send USDC from a Sepolia wallet into your Circle hosted wallet.

❗️

Use supported chains and currencies only

Transferring unsupported currencies using the Accounts API may result in a permanent loss of funds. You can verify the token contract details for supported currencies here.

Now transfer the funds from the Ethereum blockchain. Circle's sandbox environment is connected to the Ethereum Sepolia testing network, so you can send USDC from a Sepolia wallet into your Circle hosted wallet.

• Visit USDC on Testing Networks to learn more about support on other blockchains.

If you need USDC to send, you can obtain some USDC on the Sepolia network for testing by using a USDC faucet. Go to faucet.circle.com and make sure you choose the Sepolia button. Paste the deposit (wallet) address you created above and hit Submit.

• Be very careful not to miss any characters in the deposit address.

Monitor the transfer on the blockchain by using the Sepolia Etherscan link provided by the faucet.

Alternately, you can obtain USDC by funding a test wallet with a payment and then transferring USDC out of that wallet.

Use the retrieve transfers endpoint (as in the command below) to find transfers that are routed to to the wallet you created earlier.

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

The response should look like this:

{ "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 Sepolia.

At first, the status is shown as running because the transaction has been recently initiated. In a few minutes, once the required 30 block confirmations have been completed, the status changes to complete. At that point Circle credits the receiving wallet with the value of the transfer.

At first, the status is shown as running because the transaction has been recently initiated. In a few minutes, once the required 30 block confirmations have been completed, thestatus changes to complete. At that point Circle credits the receiving wallet with the value of the transfer.

• Refer to our confirmations guide to learn about block confirmation requirements for different chains.

You have successfully received USDC from the Ethereum blockchain using the Circle Wallets API.

After the receiving portion of the swap settles, you can initiate the second portion: sending USDC funds to an address on a different blockchain using the Create a transfer endpoint.

• Make sure you 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

Download the Algorand Wallet. Under Settings > Node Settings, select TestNet. From the main wallet screen, note your account address.

Your Algorand TestNet wallet address should look like this: BL27TI3CYMFX5URLYNBJJZGV4ABRYJJHBMLRR5OYSVPUVDIUAF66IR4COA.

🚧

Opt-in to Accept the USDC Asset

Due to Algorand Standard Assets spam protection, you must opt in to accept new assets such as USDC. To do so, select Add New Asset, then search for "USDC" (the USDC asset ID on Algorand TestNet is 10458941`).

📘

ALGO Dispenser (Faucet)

To complete the opt-in, you must pay for a transaction. Obtain TestNet ALGO tokens on from the TestNet ALGO Dispenser (Faucet).

To send funds to the external Algorand wallet, use the create wallet transfer endpoint. Specify the currency and chain attributes that match the destination blockchain. 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 idcurl -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 you create a transfer on chains like Stellar that support destination tags or memos, you can use the optionaladdressTag parameter to make sure your send is received correctly.

📘

Flow Vaults

Prior to sending USDC to a wallet on the Flow network, make sure the wallet address is set up to receive a USDC transfer. In most cases, this involves selecting an option in the wallet’s UI to “add USDC.” See Flow documentation for details.

The response should look like this:

{ "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" }}

Use the get transfer endpoint to retrieve details about the status of the transaction. You can use it as shown in the command below.

# Replace ${YOUR_API_KEY} with your API key# Replace ${TRANSFER_ID} with the id of the transfer you created earliercurl -H "Authorization: Bearer ${YOUR_API_KEY}" \ -X GET https://api-sandbox.circle.com/v1/transfers/${TRANSFER_ID}

The response should look like this:

{ "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 confirm in under 5 seconds, so your transferstatus should quickly change to complete. See Blockchain Confirmations to find transaction times for all chains.

After experimenting with our APIs, you’ll want to start building test integrations in sandbox prior to moving into production. Start by applying for a applying for a Circle Mint account. We'll be happy to walk you through the next steps.