How to Use the Circle API: USDC Payments, Wallets, and Payouts

Circle issues USDC, the second-largest stablecoin by market cap, and exposes a stack of APIs that let you move dollars on-chain without building custody, compliance, or banking infrastructure from scratch. If you have ever wanted to settle a marketplace payout in minutes, let a user deposit via card and withdraw as USDC, or move stablecoins across eight blockchains with a single call, the Circle API is the shortest path there. Official docs live at developers.circle.com, and the USDC primer at circle.com/en/usdc is worth a read before you touch the keys.

This guide walks through the full developer surface: account creation, sandbox vs production, Bearer token authentication, payments and payouts endpoints, Circle Wallets (Web3 Services), the Cross-Chain Transfer Protocol (CCTP), entity secret ciphertext for Developer-Controlled Wallets, webhooks, idempotency, and KYB compliance. Expect curl and Node snippets you can paste into your terminal. Related reading: our guide on the best fiat on-ramp off-ramp API compares Circle against its closest competitors.

TL;DR

• The Circle API is a family of services: Circle Payments (cards, ACH, wires), Circle Mint (institutional USDC issuance), Circle Wallets / W3S (programmable wallets), and CCTP (native cross-chain USDC burn-and-mint).
• Authenticate with a Bearer token; sandbox keys start with TEST_API_KEY: and production keys with LIVE_API_KEY:.
• Developer-Controlled Wallets require an entity secret ciphertext (RSA-encrypted, regenerated per request) for all write operations.
• CCTP moves native USDC across Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana, and more via an attested burn-mint.
• KYB approval is required for production. Sandbox is open to any developer.
• Use idempotency keys on every mutating request and verify webhook signatures with the public key from /notifications/publicKey/get.

What is the Circle API?

Circle is a regulated payments company that issues USDC and operates the rails that keep it pegged to the US dollar. The Circle API exposes four product lines you can mix and match:

• Circle Payments API accepts cards, ACH, SEPA, and wires, then settles the result as USDC in your merchant wallet.
• Circle Payouts API sends wires or ACH from your USDC balance to any bank account you have onboarded as a beneficiary.
• Circle Wallets (W3S) spins up custodial or developer-controlled wallets on multiple chains, signs transactions, and handles gas.
• CCTP burns USDC on a source chain and mints equivalent USDC on a destination chain, so you get native assets, not a bridged wrapper.

If you are comparing Circle to general-purpose Web3 infrastructure, read our breakdown of the best crypto wallet API and the how to use Alchemy API guide to see where each tool fits.

Authentication and setup

Create an account at console.circle.com. The console gives you two environments: sandbox and production. Sandbox is free and self-serve; production requires Know Your Business (KYB) approval, which takes a few business days and needs incorporation documents, beneficial owner info, and a funding account.

Generate an API key under Developers → API Keys. The key format is TEST_API_KEY:<id>:<secret> in sandbox or LIVE_API_KEY:<id>:<secret> in production. Pass it as a Bearer token:

curl https://api-sandbox.circle.com/v1/ping \
  -H "Authorization: Bearer TEST_API_KEY:abc123:xyz789"

Base URLs:

• Sandbox: https://api-sandbox.circle.com
• Production: https://api.circle.com

For Developer-Controlled Wallets in W3S, you also need an entity secret: a 32-byte hex string you generate once and register via the dashboard. Every write call must include a fresh entitySecretCiphertext, which is the entity secret encrypted with Circle’s RSA public key. The Node SDK regenerates it automatically; if you roll your own, rotate the ciphertext on every request because Circle rejects reused values.

Install the Node SDK:

npm install @circle-fin/developer-controlled-wallets

Core endpoints

Create a wallet set and wallet

Wallets in W3S live inside a wallet set (a group sharing one HD seed). Create the set first, then spawn wallets inside it.

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET,
});

const walletSet = await client.createWalletSet({ name: "payout-set-prod" });

const wallets = await client.createWallets({
  walletSetId: walletSet.data.walletSet.id,
  blockchains: ["ETH-SEPOLIA", "MATIC-AMOY"],
  count: 2,
});

console.log(wallets.data.wallets);

Each wallet returns an id, an address, and the blockchain it lives on. Fund it with testnet USDC from the Circle faucet to keep going.

Transfer USDC from a developer-controlled wallet

const transfer = await client.createTransaction({
  walletId: wallets.data.wallets[0].id,
  tokenId: "5797fbd6-3795-519d-84ca-ec4c5f80c3b1", // USDC on ETH-SEPOLIA
  destinationAddress: "0xRecipient...",
  amount: ["10.00"],
  fee: { type: "level", config: { feeLevel: "MEDIUM" } },
});

The response returns a transaction id you poll via GET /v1/w3s/transactions/{id} or listen for via webhook.

Accept a card payment and settle as USDC

curl -X POST https://api-sandbox.circle.com/v1/payments \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "source": { "id": "card_4f1c...", "type": "card" },
    "amount": { "amount": "50.00", "currency": "USD" },
    "verification": "cvv",
    "description": "Order 1093",
    "encryptedData": "<PGP-encrypted card data>",
    "metadata": { "email": "buyer@example.com", "sessionId": "..." }
  }'

Card data must be PGP-encrypted with Circle’s public key (pull it from /v1/encryption/public). The response returns a payment id that moves through pending → confirmed → paid.

Send a payout via wire or ACH

curl -X POST https://api-sandbox.circle.com/v1/payouts \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destination": { "type": "wire", "id": "beneficiary_abc" },
    "amount": { "amount": "500.00", "currency": "USD" },
    "metadata": { "beneficiaryEmail": "vendor@example.com" }
  }'

Move USDC cross-chain with CCTP

CCTP is a smart-contract protocol, not a REST endpoint, so you combine an on-chain burn with Circle’s attestation service:

1. Call depositForBurn on the TokenMessenger contract on the source chain.
2. Poll https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} until status: "complete" and you receive an attestation hex blob.
3. Call receiveMessage on the MessageTransmitter contract on the destination chain with the message bytes and attestation.

You end up with native USDC on the destination chain, minted from thin air against a verifiable burn. No wrapped tokens, no bridge liquidity risk.

Webhooks and idempotency

Circle POSTs events (payments, payouts, transfers, chargebacks) to any HTTPS endpoint you subscribe via /v1/notifications/subscriptions. Every webhook is signed with an ECDSA key; fetch the public key from /v1/notifications/publicKey/get and verify the X-Circle-Signature header before trusting the payload.

Every mutating endpoint requires an Idempotency-Key header (a UUID v4 is standard). Retrying a request with the same key returns the original response instead of creating a duplicate payment. This matters: cards and wires do not forgive double-sends.

Common errors and rate limits

• 401 Unauthorized: Bearer token missing, malformed, or wrong environment.
• 400 invalid_entity_secret_ciphertext: you reused a ciphertext or encrypted against a stale public key. Regenerate and retry.
• 429 Too Many Requests: sandbox is capped around 10 requests per second per endpoint; production limits scale with volume. Back off exponentially.
• insufficient_funds: the source wallet does not have enough USDC, or the source card failed the AVS/CVV check.

For a broader view of card infrastructure, our best card issuing API roundup covers issuers that pair well with Circle payouts.

Circle API pricing

Sandbox is free. In production, Circle Mint charges nothing to mint or redeem USDC for approved institutional customers with qualifying volume. Circle Payments takes a percentage plus fixed fee per card transaction (typically 2.9% + 30 cents, negotiated at scale). Payouts to US wires run a few dollars per transaction. W3S wallets are priced per-wallet and per-transaction; contact sales for a production quote. CCTP itself is free; you pay source and destination chain gas.

Testing the Circle API with Apidog

Circle’s surface spans REST, signed webhooks, and on-chain contracts, so a single Postman collection rarely captures the full flow. Apidog imports Circle’s OpenAPI spec directly, stores sandbox and production Bearer tokens as separate environments, and lets you write a test script that chains a card payment, a payout, and a webhook verification into one run.

Download Apidog and load the Circle spec from their developer portal. Use the mock server to simulate webhook deliveries while you build the verification handler, then swap to a real endpoint once you are ready. For teams, the shared workspace keeps your entity secret out of chat and versions your collection alongside your backend code.

FAQ

Do I need KYB to test the Circle API?No. Sandbox accounts are open to anyone with an email address. You only need KYB to move real dollars in production. The sandbox ships with faucets for USDC on every supported chain.

What is the difference between Circle Mint and Circle Wallets?Circle Mint is the institutional on-ramp: you wire USD in, you get USDC out (and vice versa). Circle Wallets / W3S is custody and transaction infrastructure for your end users. Most consumer apps use Wallets on top; treasury apps use Mint directly. Our how to use MoonPay API guide covers a retail-only alternative if you do not need Mint-level issuance.

How does CCTP avoid bridge risk?Native USDC is burned on the source chain and freshly minted on the destination chain against a signed attestation from Circle. There is no locked liquidity pool that a bridge exploit can drain. You still trust Circle’s attestation service, but you are not trusting a third-party bridge validator set.

Can I use Circle Wallets without holding keys?Yes. User-Controlled Wallets in W3S use MPC and PIN-based authentication, so end users authorize transactions via Circle’s SDK and you never touch a private key. Developer-Controlled Wallets put signing authority on your backend via the entity secret.

Does Circle support Solana and non-EVM chains?Yes. W3S covers Solana, Aptos, NEAR, and several EVM L2s. CCTP v2 expanded Solana support in 2024, so native USDC now moves freely between Solana and the EVM ecosystem.

How do I rotate the entity secret safely?Circle supports entity secret rotation via the dashboard. Generate a new secret, register it, and run both old and new ciphertexts in parallel for a short cutover window. The SDK reads whichever secret is in your environment variable, so a rolling deploy handles it cleanly.