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.

Walk through a basic integration flow: confirm your account, get wire instructions, simulate a deposit, and verify the balance.
The Digital Asset Accounts API base URL is https://api-sandbox.circle.com for sandbox and https://api.circle.com for production. Set your API key in the Authorization header using the format Bearer YOUR_API_KEY. See Sandbox environment and Going to production for environment details.

​
Prerequisites

Before you begin this quickstart, ensure you’ve:
  • Obtained an API key for Digital Asset Accounts from your Circle representative.
  • Obtained an onboarded and active account with an accountId. Accounts are created after a business entity passes KYB verification through the Partner Onboarding API. In sandbox, accounts are pre-provisioned for testing.
  • (Recommended) Configured a webhook subscription for tracking asynchronous events.

​
Step 1: Check your account balance

Confirm the account exists and check the starting balance: 
curl --request GET \
  --url https://api-sandbox.circle.com/v1/accounts/balances/ACCOUNT_ID \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
Replace ACCOUNT_ID with your account ID and YOUR_API_KEY with your Bearer token. 
{
  "data": {
    "available": [
      {
        "amount": "0.00",
        "currency": "USD"
      }
    ],
    "unsettled": []
  }
}

​
Step 2: Get wire instructions

Before you can deposit funds, retrieve the wire instructions for your account. Wire instructions are the bank routing details your customer uses to send a wire transfer. You need a linked wire account. See Wire deposits and withdrawals for the full setup process. 
curl --request GET \
  --url 'https://api-sandbox.circle.com/v1/accounts/banks/wires/WIRE_ID/instructions?accountId=ACCOUNT_ID' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
The response includes a trackingRef that must be included in the wire transfer: 
{
  "data": {
    "trackingRef": "CIR3XXXYYY",
    "beneficiary": {
      "name": "Circle Internet Financial Inc",
      "address1": "99 High Street",
      "address2": "Boston, MA 02110"
    },
    "beneficiaryBank": {
      "name": "Silicon Valley Bank",
      "routingNumber": "121140399",
      "accountNumber": "1234567890",
      "currency": "USD",
      "country": "US"
    }
  }
}

​
Step 3: Simulate a wire deposit

In sandbox, simulate a wire deposit using the mock payments endpoint. In production, your customer sends a real wire transfer using the instructions from step 2. 
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": "CIR3XXXYYY",
    "amount": {
      "amount": "10000.00",
      "currency": "USD"
    },
    "beneficiaryBank": {
      "accountNumber": "1234567890",
      "routingNumber": "121140399"
    }
  }'
The deposit starts in pending status (see Transaction states) and settles instantly in sandbox: 
{
  "data": {
    "trackingRef": "CIR3XXXYYY",
    "amount": {
      "amount": "10000.00",
      "currency": "USD"
    },
    "status": "pending"
  }
}

​
Step 4: Verify the balance

After the deposit settles, check that the funds appear in your account: 
curl --request GET \
  --url https://api-sandbox.circle.com/v1/accounts/balances/ACCOUNT_ID \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
The balance now reflects the deposited amount: 
{
  "data": {
    "available": [
      {
        "amount": "10000.00",
        "currency": "USD"
      }
    ],
    "unsettled": []
  }
}
You now have a funded account in sandbox. See Account structure to understand how programs, accounts, and sub-accounts relate.