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.

Deposit fiat (onramp) from an external bank account to mint USDC or EURC in your Circle Mint balance. The /wires endpoint supports multiple payment rails, including standard wires (FedWire and SWIFT), real-time interbank rails (RTP, SPEI, SEPA, and CHATS) where available, and book transfers when you bank with one of Circle’s settlement partners.
This guide focuses on standard wire deposits. The same endpoint handles other rails — Circle routes the deposit based on your linked bank and region. Rail-specific parameters and additional endpoints (such as CUBIX and PIX for local currencies) are out of scope here.

​
Prerequisites

Before you begin: Use the create a wire bank account endpoint to register your external bank account with Circle Mint. 
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/banks/wires \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey":"ba943ff1-ca16-49b2-ba55-1057e70ca5c7","accountNumber":"12340010","routingNumber":"121000248","billingDetails":{"name":"Satoshi Nakamoto","city":"Boston","country":"US","line1":"100 Money Street","district":"MA","postalCode":"01234"},"bankAddress":{"bankName":"SAN FRANCISCO","city":"SAN FRANCISCO","country":"US","line1":"100 Money Street","district":"CA"}}'
Expected response: 
{
  "data": {
    "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
    "status": "pending",
    "description": "WELLS FARGO BANK, NA ****0010",
    "trackingRef": "CIR2GKYL4B",
    "virtualAccountEnabled": true,
    "billingDetails": {
      "name": "Satoshi Nakamoto",
      "line1": "100 Money Street",
      "city": "Boston",
      "postalCode": "01234",
      "district": "MA",
      "country": "US"
    },
    "bankAddress": {
      "bankName": "WELLS FARGO BANK, NA",
      "line1": "100 Money Street",
      "city": "SAN FRANCISCO",
      "district": "CA",
      "country": "US"
    },
    "createDate": "2023-11-04T20:02:21.062Z",
    "updateDate": "2023-11-04T20:02:21.062Z"
  }
}
Record the id and trackingRef values from the response. You use both in the following steps.

​
Step 2. Retrieve wire instructions

Use the get wire instructions endpoint to fetch the beneficiary details your bank needs to send the wire. 
curl https://api-sandbox.circle.com/v1/businessAccount/banks/wires/${BANK_ACCOUNT_ID}/instructions \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
Expected response: 
{
  "data": {
    "trackingRef": "CIR22FEP33",
    "beneficiary": {
      "name": "CIRCLE INTERNET FINANCIAL INC",
      "address1": "1 MAIN STREET",
      "address2": "SUITE 1"
    },
    "virtualAccountEnabled": true,
    "beneficiaryBank": {
      "name": "CRYPTO BANK",
      "address": "1 MONEY STREET",
      "city": "NEW YORK",
      "postalCode": "1001",
      "country": "US",
      "swiftCode": "CRYPTO99",
      "routingNumber": "999999999",
      "accountNumber": "123815146304",
      "currency": "USD"
    }
  }
}
The response includes:
  • Beneficiary details — the name and address of the recipient (Circle).
  • Routing information — the bank name, SWIFT code, and routing number for the beneficiary bank.
  • Virtual Account Number — the beneficiaryBank.accountNumber field, unique to your linked bank account.
  • Tracking reference — the trackingRef value to include in the wire memo.

​
Virtual account numbers

Not all Circle settlement banks support Virtual Account Numbers. When virtualAccountEnabled is true in the wire instructions response, the linked bank account has a unique VAN in the beneficiaryBank.accountNumber field. When the sender includes the VAN as the account number on their wire, the tracking reference in the wire memo becomes optional. When virtualAccountEnabled is false, the sender must include the trackingRef in the wire memo so Circle can match the deposit to your account. Benefits of using a VAN (where supported):
  • Eliminates the need for senders to include tracking references in payment instructions.
  • Reduces wire returns caused by missing or incorrect tracking references.
  • Supports all wire types: domestic, international, and SWIFT.

​
Step 3. Send the wire deposit

In production, initiate the wire transfer from your bank using the instructions returned in Step 2. Confirm that the wire details — beneficiary name, account number, and routing number — match exactly. Mismatched details can result in wire returns or processing delays of several business days. Domestic wire deposits received before the daily cutoff typically settle on the same business day. International wires may take longer depending on intermediary banks.

​
Simulate a deposit in sandbox

In the sandbox environment, use the mock wire payment endpoint to simulate a wire deposit without sending real funds. Provide the trackingRef from Step 2 and the beneficiaryBank.accountNumber (the VAN) from the wire instructions response. 
curl -X POST https://api-sandbox.circle.com/v1/mocks/payments/wire \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"amount":{"amount":"50.00","currency":"USD"},"trackingRef":"CIR22FEP33","beneficiaryBank":{"accountNumber":"123815146304"}}'
Expected response: 
{
  "data": {
    "trackingRef": "CIR22FEP33",
    "amount": {
      "amount": "50.00",
      "currency": "USD"
    },
    "beneficiaryBank": {
      "accountNumber": "123815146304"
    },
    "status": "pending"
  }
}
The mock wire endpoint is available in sandbox only. Mock wire deposits process in batches and may take up to 15 minutes to complete.

​
Step 4. Verify the deposit

Use the list deposits endpoint to confirm the incoming fiat deposit has settled. 
curl https://api-sandbox.circle.com/v1/businessAccount/deposits \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
Expected response: 
{
  "data": [
    {
      "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
      "sourceWalletId": "1000066041",
      "destination": {
        "type": "wallet",
        "id": "1000066041"
      },
      "amount": {
        "amount": "50.00",
        "currency": "USD"
      },
      "status": "complete",
      "createDate": "2024-01-01T12:00:00.000Z"
    }
  ]
}

​
See also