Sandbox environment

Use Circle’s sandbox environment for safe development and testing of your Digital Asset Accounts integration

The Digital Asset Accounts sandbox environment lets you safely test your integration without generating real financial transactions or interacting with live blockchains. The sandbox APIs match those in production, making it easy to transition when you are ready to go live.

Request sandbox access

Digital Asset Accounts sandbox access is not automatically provisioned. After signing up for a Circle sandbox account, contact your Circle representative to request Digital Asset Accounts access. Circle must enable this access on your account before you can use the End User Onboarding and Digital Asset Accounts APIs. Until access is granted, calls to these endpoints return errors.

API environments and hosts

Use these hosts to access the Digital Asset Accounts API in sandbox and production environments.

Environment	API host
Sandbox	https://api-sandbox.circle.com
Production	https://api.circle.com

Authentication

All API requests require authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

To verify that your API key is correctly set up, you can make a test request to any read endpoint, such as listing accounts:

curl --request GET \
  --url https://api-sandbox.circle.com/v1/accounts \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'

If your API key is valid, you receive a successful response. If the key is invalid, you receive a 401 Unauthorized error.

Keep your API keys safe. Never share your API key or record it in a publicly accessible medium such as client-side code or public repositories.

Sandbox capabilities

The sandbox supports all Digital Asset Accounts API operations:

Feature	Sandbox behavior
Account creation	Accounts are created and KYB is auto-approved
Wire deposits	Simulated wire deposits that credit instantly
Wire withdrawals	Simulated withdrawals that complete without real fiat movement
Crypto deposits	Simulated blockchain deposits
Crypto transfers	Simulated outbound transfers that complete without real blockchain transactions
Internal transfers	Processed identically to production
Webhooks	Notifications are sent to subscriber endpoints

Onboard an end customer

To test deposits, withdrawals, or transfers against an end customer account, you must first onboard a business client through the End User Onboarding API.

See Onboard customers for a step-by-step walkthrough.

Simulating wire deposits

After onboarding a client and retrieving their account, you can simulate wire deposits without sending real bank transfers. Create a wire account, retrieve the wire instructions, then use the mock deposit endpoint to trigger a simulated deposit:

curl --request POST \
  --url https://api-sandbox.circle.com/v1/mocks/payments/wire \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "trackingRef": "${TRACKING_REF}",
  "amount": {
    "amount": "10000.00",
    "currency": "USD"
  },
  "beneficiaryBank": {
    "accountNumber": "1234567890",
    "routingNumber": "121140399"
  }
}
'

Use the trackingRef and beneficiaryBank details from the wire instructions endpoint. The mock deposit is processed immediately and the balance is credited to the account.

Simulating crypto deposits

There is no mock endpoint for crypto deposits. Instead, the sandbox auto-confirms deposits to generated addresses. After creating a deposit address using the /v1/accounts/addresses/deposit endpoint, any test transactions sent to that address are automatically detected and credited. For details on how deposit transaction states progress, see the transaction states reference.

Differences between sandbox and production

Be aware of the following differences when testing in sandbox:

• KYB verification: Account KYB is automatically approved in sandbox. In production, KYB verification takes time and may result in rejection.
• Wire processing: Wire deposits and withdrawals settle instantly in sandbox. In production, wire transfers take 1-2 business days.
• Blockchain confirmations: Crypto deposits are confirmed instantly in sandbox. In production, confirmation times depend on the blockchain.
• Transaction limits: Sandbox limits differ from production limits. Test your limit-handling logic, but verify against production limits before launch.

Moving to production

When you are ready to go live, see Going to production.