Quickstart: Swapping USDC Across Blockchains

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.

1. Get a sandbox API key

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.

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.

Start by transferring USDC from an external Ethereum wallet.

Create a Wallet

First, use the command below to create a new wallet to receive the external funds via the create a wallet API endpoint. Be sure 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"}'

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 create a blockchain address API 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 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"}'

The response should look like this:

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

Transfer 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.

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.

3. Check the Status of the Transfer

Use the list all transfers API 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 step
curl -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.

4. Send USDC to the Algorand blockchain

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 API 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.

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

To send funds to the external Algorand wallet, use the create a transfer API 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 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"}}'

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

5. Check the Status of the Transfer

Use the get a transfer API 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 earlier
curl -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.

6. Ready for the next step?

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.