Blog

Comment utiliser l'API Circle : Paiements USDC, Wallets et Versements

Ashley Innocent

Ashley Innocent

23 April 2026

Comment utiliser l'API Circle : Paiements USDC, Wallets et Versements

Apidog pour les entreprises

Déploiement sur site

SSO & RBAC

Conforme SOC 2

Explorer Apidog Enterprise

Circle émet l'USDC, le deuxième plus grand stablecoin par capitalisation boursière, et expose une série d'API qui vous permettent de déplacer des dollars on-chain sans avoir à construire de A à Z une infrastructure de garde, de conformité ou bancaire. Si vous avez déjà souhaité régler un paiement de marketplace en quelques minutes, permettre à un utilisateur de déposer par carte et de retirer en USDC, ou de déplacer des stablecoins sur huit blockchains avec un seul appel, l'API Circle est le chemin le plus court. La documentation officielle se trouve sur developers.circle.com, et le guide d'introduction à l'USDC sur circle.com/en/usdc vaut la peine d'être lu avant de commencer à coder.

Ce guide explore l'ensemble de la surface développeur : création de compte, sandbox vs production, authentification par token Bearer, endpoints de paiements et de virements, Circle Wallets (Services Web3), le protocole de transfert inter-chaînes (CCTP), le texte chiffré du secret d'entité pour les portefeuilles contrôlés par le développeur, les webhooks, l'idempotence et la conformité KYB. Attendez-vous à des extraits curl et Node que vous pourrez coller dans votre terminal. Lecture connexe : notre guide sur la meilleure API fiat on-ramp off-ramp compare Circle à ses concurrents les plus proches.

💡
Vous voudrez également un client API capable de gérer à la fois REST et Web3 de manière fluide pendant que vous prototypez. Apidog gère l'authentification Bearer de Circle, le changement d'environnement et la relecture de webhooks dans un seul espace de travail, vous permettant ainsi de tester le sandbox et la production côte à côte sans réécrire votre collection.
bouton

En bref

Qu'est-ce que l'API Circle ?

Circle est une société de paiement réglementée qui émet l'USDC et opère les infrastructures qui le maintiennent indexé sur le dollar américain. L'API Circle expose quatre gammes de produits que vous pouvez combiner :

Si vous comparez Circle à une infrastructure Web3 à usage général, lisez notre analyse de la meilleure API de portefeuille crypto et le guide comment utiliser l'API Alchemy pour voir où chaque outil s'intègre.

Authentification et configuration

Créez un compte sur console.circle.com. La console vous offre deux environnements : sandbox et production. Le sandbox est gratuit et en libre-service ; la production nécessite l'approbation Know Your Business (KYB), ce qui prend quelques jours ouvrables et requiert des documents d'incorporation, des informations sur les propriétaires effectifs et un compte de financement.

Générez une clé API sous Développeurs → Clés API. Le format de la clé est TEST_API_KEY:<id>:<secret> pour le sandbox ou LIVE_API_KEY:<id>:<secret> pour la production. Transmettez-la comme un token Bearer :

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

URLs de base :

Pour les portefeuilles contrôlés par le développeur dans W3S, vous avez également besoin d'un secret d'entité : une chaîne hexadécimale de 32 octets que vous générez une fois et enregistrez via le tableau de bord. Chaque appel d'écriture doit inclure un entitySecretCiphertext frais, qui est le secret d'entité chiffré avec la clé publique RSA de Circle. Le SDK Node le régénère automatiquement ; si vous implémentez le vôtre, faites pivoter le texte chiffré à chaque requête car Circle rejette les valeurs réutilisées.

Installez le SDK Node :

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

Endpoints principaux

Créer un ensemble de portefeuilles et un portefeuille

Les portefeuilles dans W3S résident à l'intérieur d'un ensemble de portefeuilles (un groupe partageant une seule graine HD). Créez d'abord l'ensemble, puis générez des portefeuilles à l'intérieur.

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);

Chaque portefeuille renvoie un id, une adresse et la blockchain sur laquelle il se trouve. Financez-le avec de l'USDC de testnet depuis le faucet Circle pour continuer.

Transférer de l'USDC depuis un portefeuille contrôlé par le développeur

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" } },
});

La réponse renvoie un id de transaction que vous pouvez interroger via GET /v1/w3s/transactions/{id} ou écouter via webhook.

Accepter un paiement par carte et le régler en 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": "..." }
  }'

Les données de carte doivent être chiffrées PGP avec la clé publique de Circle (récupérez-la depuis /v1/encryption/public). La réponse renvoie un id de paiement qui passe par les états pending → confirmed → paid (en attente → confirmé → payé).

Envoyer un virement par virement bancaire ou 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" }
  }'

Déplacer l'USDC inter-chaînes avec CCTP

Le CCTP est un protocole de smart contract, et non un endpoint REST, vous combinez donc une gravure on-chain avec le service d'attestation de Circle :

  1. Appelez depositForBurn sur le contrat TokenMessenger de la chaîne source.
  2. Interrogez https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} jusqu'à ce que status: "complete" et que vous receviez un blob hexadécimal d'attestation.
  3. Appelez receiveMessage sur le contrat MessageTransmitter de la chaîne de destination avec les octets du message et l'attestation.

Vous obtenez de l'USDC natif sur la chaîne de destination, frappé de toutes pièces contre une gravure vérifiable. Pas de tokens enveloppés, pas de risque de liquidité de pont.

Webhooks et idempotence

Circle envoie des événements (payments, payouts, transfers, chargebacks) à tout endpoint HTTPS auquel vous vous abonnez via /v1/notifications/subscriptions. Chaque webhook est signé avec une clé ECDSA ; récupérez la clé publique de /v1/notifications/publicKey/get et vérifiez l'en-tête X-Circle-Signature avant de faire confiance à la charge utile.

Chaque endpoint mutatif nécessite un en-tête Idempotency-Key (un UUID v4 est standard). Réessayer une requête avec la même clé renvoie la réponse originale au lieu de créer un paiement en double. C'est important : les cartes et les virements ne pardonnent pas les doubles envois.

Erreurs courantes et limites de débit

Pour une vue d'ensemble de l'infrastructure de cartes, notre tour d'horizon de la meilleure API d'émission de cartes couvre les émetteurs qui s'associent bien aux paiements Circle.

Tarification de l'API Circle

Le sandbox est gratuit. En production, Circle Mint ne facture rien pour frapper ou échanger de l'USDC pour les clients institutionnels approuvés avec un volume éligible. Circle Payments prend un pourcentage plus des frais fixes par transaction par carte (généralement 2,9 % + 30 cents, négociés à l'échelle). Les virements vers les États-Unis coûtent quelques dollars par transaction. Les portefeuilles W3S sont tarifés par portefeuille et par transaction ; contactez le service commercial pour un devis de production. Le CCTP lui-même est gratuit ; vous payez les frais de gaz de la chaîne source et de destination.

Tester l'API Circle avec Apidog

La surface de Circle s'étend sur REST, les webhooks signés et les contrats on-chain, de sorte qu'une seule collection Postman capture rarement le flux complet. Apidog importe directement la spécification OpenAPI de Circle, stocke les tokens Bearer du sandbox et de la production comme environnements distincts, et vous permet d'écrire un script de test qui enchaîne un paiement par carte, un virement et une vérification de webhook en une seule exécution.

Téléchargez Apidog et chargez la spécification Circle depuis leur portail développeur. Utilisez le serveur de simulation pour simuler les livraisons de webhooks pendant que vous construisez le gestionnaire de vérification, puis passez à un endpoint réel une fois que vous êtes prêt. Pour les équipes, l'espace de travail partagé protège votre secret d'entité des conversations et versionne votre collection à côté de votre code backend.

FAQ

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger
Comment utiliser l'API Circle : Paiements USDC, Wallets et Versements