The following sections will step through funding the master wallet with USDC, EURC, BTC and ETH.

Funding USDC Balance

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/businessAccount/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 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 depends on the chain you've chosen, but will look similar to the following:

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

2. Send USDC funds from an external wallet

The sandbox environment is connected to the testing networks of the blockchains where USDC is supported. So you can send USDC from any of the supported blockchain test network wallets in order to fund your Circle hosted wallet. For information see our guide on USDC on testing networks.

For testing with Ethereum or Algorand, if you have USDC on an external Sepolia or Algorand TestNet wallet, simply send some amount to the address you generated above. If you don't have any USDC for testing, you can get some by using a USDC faucet. Go to faucet.circle.com and make sure you choose either ETH or ALGO. 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/AlgoExplorer link provided by the faucet.

❗️

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 the required confirmations (a few minutes in the case of Ethereum, a few seconds in the case of most other chains), 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/businessAccount/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": []
  }
}

Funding EURC balance

At the moment, to fund your wallets for testing EURC you need to receive an external EURC transfer.

Fund your wallet with an external EURC transfer

At this time, there isn't a faucet that mints EURC. To acquire EURC on a Testnet you will need to go to a decentralized exchange (DEX) on the applicable TestNet and swap a token for EURC.

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": "EUR", "chain": "ETH"}'

The response depends on the chain you've chosen, but will look similar to the following:

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

2. Send EURC funds from an external wallet

The sandbox environment is connected to the testing networks of the blockchains where EURC is supported. So you can send EURC from any of the supported blockchain test network wallets in order to fund your Circle hosted wallet.

❗️

Lost Funds

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

3. Confirm your master wallet balance

After the required confirmations (a few minutes in the case of Ethereum, a few seconds in the case of most other chains), 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/businessAccount/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": "EUR"
      }
    ],
    "unsettled": []
  }
}

Funding BTC and ETH Balances

To fund BTC and ETH balances in Sandbox, you can similarly use a Bitcoin testnet faucet or an Ethereum Sepolia faucet.