Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.circle.com/llms.txt

Use this file to discover all available pages before exploring further.

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 Partner 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.
EnvironmentAPI host
Sandboxhttps://api-sandbox.circle.com
Productionhttps://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:
FeatureSandbox behavior
Account creationAccounts are created and KYB is auto-approved
Wire depositsSimulated wire deposits that credit instantly
Wire withdrawalsSimulated withdrawals that complete without real fiat movement
Crypto depositsSimulated blockchain deposits
Crypto transfersSimulated outbound transfers that complete without real blockchain transactions
Internal transfersProcessed identically to production
WebhooksNotifications 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 Partner 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.