Circle APIs Documentation

Learn how to integrate with Circle APIs to accept traditional and stablecoin payments, embed digital wallets into your product or service, or power your internet marketplace.

Fund Test Wallets

There are two main ways of funding your wallets for testing. The first one is to use the Circle Payments API to accept a payment - the settlement of such payment will then fund your master wallet. The second one is to receive an external USDC transfer - we suggest using a faucet if you don't have any USDC for testing.

Option 1: Fund your wallet by accepting a payment

If you are also using the Circle Payments API then the easiest way to fund a wallet for testing is to accept a test card payment.

1. Accept a test card payment

Follow the payments quickstart guide to accept a card payment.

2. Wait 5-10 minutes for settlement

On the sandbox environment it takes 5-10 minutes for a payment to settle. You can check on the status of your payment by using the retrieve payment endpoint. Run the following command for that.

# Replace ${YOUR_API_KEY} with your API key
# Replace ${PAYMENT_ID} with your payment id
curl -H 'Accept: application/json' \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X GET --url https://api-sandbox.circle.com/v1/payments/${PAYMENT_ID}

You will notice that the payment has settled once its status changes from confirmed to paid.

3. Confirm your master wallet balance

Once the processed payment settles in the sandbox environment, it will credit your master wallet. You can confirm your master wallet balance by using the balances endpoint in the following way.

# Replace ${YOUR_API_KEY} with your API key
curl -H 'Accept: application/json' \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X GET --url https://api-sandbox.circle.com/v1/balances

You should receive a response like below, and at this point you will be able to use your funds for Wallets API testing.

{
  "data":[
    {
      "available":[
        {
          "amount":"98.95",
          "currency":"USD"
        }
      ],
      "unsettled":[
      ]
    }
  ]
}

Option 2: Fund your wallet with an external USDC transfer

If you are not using the Circle Payments API then perhaps the easiest way to fund a wallet for testing is to receive USDC from an external blockchain wallet, such as a faucet.

1. Generate a blockchain address for your master wallet

In order to receive funds from an external blockchain wallet, first you need to create a deposit address associated to your master wallet. Use the configuration endpoint to obtain your master wallet id.

You can do so with the following command (you should generate your own idempotency key).

# Replace ${YOUR_API_KEY} with your API key
# Replace ${MASTER_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 --url https://api-sandbox.circle.com/v1/wallets/${MASTER_WALLET_ID}/addresses \
  --data '{"idempotencyKey": "2678c583-20d1-405d-b185-047f8d01fe6c", "currency": "USD", "chain": "ETH"}'

The response you will obtain should look like the below.

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

2. Send USDC funds from an external wallet

The sandbox environment is connected to the Ethereum Ropsten testing network, so you can send USDC from a Ropsten wallet in order to fund your Circle hosted wallet.

If you have USDC on an external Ropsten wallet, simply send some amount to the address you generated above. If you don't have any 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.

❗️

Lost Funds

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

3. Confirm your master wallet balance

After 30 confirmations (just a few minutes), your transfer should settle on the sandbox environment and the amount sent should be credited to your wallet. You can confirm your master wallet balance by using the balances endpoint in the following way.

# Replace ${YOUR_API_KEY} with your API key
curl -H 'Accept: application/json' \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X GET --url https://api-sandbox.circle.com/v1/balances

You should receive a response like below, and at this point you will be able to use your funds for Wallets API testing.

{
  "data":[
    {
      "available":[
        {
          "amount":"1.00",
          "currency":"USD"
        }
      ],
      "unsettled":[
      ]
    }
  ]
}

Updated 2 months ago



Fund Test Wallets


Suggested Edits are limited on API Reference Pages

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