DEV Community

Cover image for How to Use the Circle API: USDC Payments, Wallets, and Payouts
Hassann
Hassann

Posted on • Originally published at apidog.com

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

Circle issues USDC, the second-largest stablecoin by market cap, and provides APIs to move dollars on-chain without building custody, compliance, or banking infrastructure from scratch. If you want to settle marketplace payouts in minutes, accept card deposits and withdraw as USDC, or move stablecoins across multiple blockchains in one call, Circle API is the fastest way. Official docs: developers.circle.com. Read the USDC primer before implementation.

Try Apidog today

This guide covers: account setup, sandbox vs. production, Bearer token authentication, payments and payouts, Circle Wallets (Web3 Services), Cross-Chain Transfer Protocol (CCTP), entity secret ciphertext for Developer-Controlled Wallets, webhooks, idempotency, and KYB compliance. Includes curl and Node.js examples for immediate use. For API comparisons, see our best fiat on-ramp off-ramp API guide.

💡 Tip: Use an API client that supports both REST and Web3. Apidog handles Circle’s Bearer auth, environment switching, and webhook replay in a unified workspace, letting you test sandbox and production without rewriting collections.

TL;DR

  • Circle API: Offers Circle Payments (cards, ACH, wires), Circle Mint (institutional USDC issuance), Circle Wallets / W3S (programmable wallets), and CCTP (native cross-chain USDC burn-and-mint).
  • Auth: Use Bearer tokens. Sandbox keys: TEST_API_KEY:, Production: LIVE_API_KEY:.
  • Developer-Controlled Wallets: All write ops require a per-request entity secret ciphertext (RSA-encrypted).
  • CCTP: Natively moves USDC across Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana, and more.
  • KYB: Required for production, not for sandbox.
  • Idempotency & Webhooks: Use idempotency keys for all mutations. Verify webhooks with the public key from /notifications/publicKey/get.

What is the Circle API?

Circle is a regulated payments company issuing USDC and operating the rails to keep it USD-pegged. The API exposes four main services:

  • Circle Payments API: Accepts cards, ACH, SEPA, wires, settles as USDC in your merchant wallet.
  • Circle Payouts API: Sends wires or ACH from your USDC balance to any onboarded beneficiary bank.
  • Circle Wallets (W3S): Spins up custodial or developer-controlled wallets across chains, handles signing and gas.
  • CCTP: Burns USDC on a source chain, mints it natively on a destination chain (no wrapped tokens).

For API alternatives, see our best crypto wallet API and how to use Alchemy API.

Authentication and Setup

  1. Create an account: console.circle.com.

    • Environments: Sandbox (free, self-serve), Production (requires KYB).
    • KYB: Needs business docs, owner info, funding account.

  2. Generate an API Key (Developers → API Keys):

    • Format:
      • Sandbox: TEST_API_KEY:<id>:<secret>
      • Production: LIVE_API_KEY:<id>:<secret>
    • Use as 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
  1. Developer-Controlled Wallets (W3S):
    • Require an entity secret (32-byte hex, registered in dashboard).
    • Every write request must have a fresh entitySecretCiphertext (RSA-encrypted entity secret).
    • Node SDK auto-generates ciphertext; rotate per request. 
   npm install @circle-fin/developer-controlled-wallets
Enter fullscreen mode Exit fullscreen mode

Core Endpoints

Create a Wallet Set and Wallet

Wallets in W3S belong to a wallet set (HD seed group). Create a wallet set, then spawn wallets inside.

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);
Enter fullscreen mode Exit fullscreen mode

Each wallet returns id, address, and blockchain. Fund wallets with testnet USDC from the Circle faucet for testing.

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" } },
});
Enter fullscreen mode Exit fullscreen mode

Result includes a transaction id you can 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": "..." }
  }'
Enter fullscreen mode Exit fullscreen mode
  • Card data must be PGP-encrypted with Circle’s public key (/v1/encryption/public).
  • Response includes a payment id that transitions: 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" }
  }'
Enter fullscreen mode Exit fullscreen mode

Move USDC Cross-Chain with CCTP

CCTP is a smart contract protocol, not REST:

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

Result: Native USDC on the destination chain, no wrapped tokens, no bridge risk.

Webhooks and Idempotency

  • Subscribe webhooks via /v1/notifications/subscriptions (events: payments, payouts, transfers, chargebacks).
  • Webhooks are signed (ECDSA); verify X-Circle-Signature using the public key from /v1/notifications/publicKey/get.
  • All mutating endpoints require an Idempotency-Key header (UUID v4 recommended). Retrying with the same key returns the original response, preventing double-sends.

Common Errors and Rate Limits

  • 401 Unauthorized: Invalid/missing Bearer token or wrong environment.
  • 400 invalid_entity_secret_ciphertext: Ciphertext reused or encrypted with stale public key. Regenerate and retry.
  • 429 Too Many Requests: Sandbox ~10 req/sec/endpoint. Production: higher, scales with volume. Use exponential backoff.
  • insufficient_funds: Source wallet/card lacks funds or AVS/CVV check failed.

For card infrastructure, see our best card issuing API roundup.

Circle API Pricing

  • Sandbox: Free.
  • Production:
    • Circle Mint: Free for qualified institutions.
    • Circle Payments: Percentage + fixed fee per card transaction (typically 2.9% + $0.30, negotiable).
    • Payouts: Few dollars per US wire.
    • W3S Wallets: Priced per-wallet and per-transaction (contact sales).
    • CCTP: Free; pay gas on source/destination chains.

Testing the Circle API with Apidog

Circle's API covers REST, signed webhooks, and on-chain contracts—one Postman collection rarely covers it all. Apidog imports Circle’s OpenAPI spec, manages separate sandbox/production Bearer tokens, and lets you script full flows (card payment → payout → webhook verification).

  • Download Apidog and load the Circle spec.
  • Use the mock server for webhook simulation; switch to live endpoints when ready.
  • Shared workspaces keep secrets safe and collections versioned with code.

FAQ

Do I need KYB to test the Circle API?

No. Sandbox is open to all with an email. KYB is only required for real money in production. Sandbox has USDC faucets for every supported chain.

What is the difference between Circle Mint and Circle Wallets?

Circle Mint is for institutional on-ramp: wire USD in, get USDC (and vice versa). Circle Wallets/W3S is for custody/transactions for end users. Most consumer apps use Wallets; treasury/enterprise use Mint. See how to use MoonPay API for a retail alternative.

How does CCTP avoid bridge risk?

Native USDC is burned on the source chain, minted on the destination chain via Circle’s signed attestation—no pooled liquidity or third-party bridge risk. You trust Circle’s attestation, not a validator set.

Can I use Circle Wallets without holding keys?

Yes. User-Controlled Wallets (W3S) use MPC and PIN-based auth—users sign with SDK, you never see private keys. Developer-Controlled Wallets put signing on your backend via the entity secret.

Does Circle support Solana and non-EVM chains?

Yes. W3S covers Solana, Aptos, NEAR, and multiple EVM L2s. CCTP v2 (2024) expanded Solana support for native USDC bridging.

How do I rotate the entity secret safely?

Rotate via the dashboard. Register a new secret, run both old/new ciphertexts in parallel for a smooth cutover. The SDK will use whatever is in your environment variable—rolling deploys handle this cleanly.

Top comments (0)