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

Circle émet l'USDC, le deuxième plus grand stablecoin par capitalisation boursière, et propose une suite d'API pour déplacer des dollars on-chain sans avoir à construire une infrastructure réglementaire ou bancaire complexe. Si vous souhaitez régler un paiement de marketplace en quelques minutes, permettre à un utilisateur de déposer par carte et de retirer en USDC, ou déplacer des stablecoins sur huit blockchains via un seul appel, l'API Circle est le chemin le plus direct. Consultez la documentation officielle sur developers.circle.com et le guide d’introduction à l’USDC sur circle.com/en/usdc avant de coder.

Essayez Apidog dès aujourd'hui

Ce guide couvre : création de compte, sandbox vs production, authentification par token Bearer, endpoints de paiements et virements, Circle Wallets (Web3 Services), CCTP (protocole de transfert inter-chaînes), gestion du secret d'entité pour portefeuilles contrôlés par le développeur, webhooks, idempotence, et conformité KYB. Vous trouverez des extraits curl et Node prêts à l'emploi. Pour comparer Circle à la concurrence, lisez notre guide sur la meilleure API fiat on-ramp off-ramp.

💡Privilégiez un client API qui gère REST et Web3 pendant vos prototypes. Apidog gère l'auth Bearer de Circle, le changement d'environnement et la relecture de webhooks dans un seul workspace, pour tester sandbox et production côte à côte sans réécrire votre collection.

En bref

• L'API Circle regroupe plusieurs services : Circle Payments (cartes, ACH, virements), Circle Mint (émission institutionnelle d'USDC), Circle Wallets / W3S (portefeuilles programmables) et CCTP (transfert inter-chaînes d'USDC natif).
• Authentifiez-vous avec un token Bearer. Les clés sandbox débutent par TEST_API_KEY:, celles de prod par LIVE_API_KEY:.
• Les portefeuilles contrôlés par le développeur requièrent un secret d'entité chiffré (RSA, à régénérer à chaque écriture).
• Le CCTP permet de déplacer de l'USDC natif entre Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana, etc., via un mécanisme de gravure/frappe attestée.
• L'approbation KYB est nécessaire pour la production. Le sandbox est accessible à tous.
• Utilisez une clé d'idempotence pour chaque requête mutative et vérifiez les signatures de webhooks avec la clé publique de /notifications/publicKey/get.

Qu'est-ce que l'API Circle ?

Circle est un acteur réglementé qui émet l’USDC et maintient l’infrastructure associée. L’API Circle expose quatre produits principaux, combinables selon vos besoins :

• API Circle Payments : accepte cartes, virements ACH, SEPA et bancaires ; règle en USDC sur votre portefeuille marchand.
• API Circle Payouts : virements bancaires ou ACH depuis votre solde USDC vers un compte bancaire bénéficiaire.
• Circle Wallets (W3S) : crée des portefeuilles sous garde ou contrôlés par le développeur sur plusieurs chaînes, signe les transactions et gère les frais.
• CCTP : grave l’USDC sur la chaîne source et frappe un USDC natif sur la chaîne destination (pas de wrapped tokens).

Pour une comparaison des solutions Web3, consultez notre analyse de la meilleure API de portefeuille crypto et le guide comment utiliser l'API Alchemy.

Authentification et configuration

1. Créez un compte sur console.circle.com.
2. Deux environnements : sandbox (gratuit, auto-service) et production (requiert KYB, quelques jours ouvrables).
3. Générez une clé API sous Développeurs → Clés API.
   • Format clé : TEST_API_KEY:<id>:<secret> (sandbox) ou LIVE_API_KEY:<id>:<secret> (prod).
   • Passez-la dans l’en-tête Authorization :

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

URLs de base :

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

Pour les portefeuilles contrôlés par le développeur (W3S), générez un secret d'entité (hex 32 octets) via le dashboard. Chaque opération d’écriture exige un entitySecretCiphertext chiffré RSA avec la clé publique Circle. Le SDK Node gère automatiquement la régénération à chaque requête.

Installez le SDK Node :

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

Endpoints principaux

Créer un ensemble de portefeuilles et un portefeuille

Les portefeuilles W3S résident dans un ensemble de portefeuilles (groupe HD). Créez l’ensemble, puis des portefeuilles associés :

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 retourne un id, une adresse et la blockchain cible. Utilisez le faucet USDC testnet pour créditer le portefeuille.

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 sur ETH-SEPOLIA
  destinationAddress: "0xRecipient...",
  amount: ["10.00"],
  fee: { type: "level", config: { feeLevel: "MEDIUM" } },
});

La réponse retourne un id de transaction consultable via GET /v1/w3s/transactions/{id} ou 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": "[e-mail]", "sessionId": "..." }
  }'

Chiffrez les données de carte avec la clé publique PGP de Circle (/v1/encryption/public). La réponse passe par les états pending → confirmed → paid.

Envoyer un 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": "[e-mail]" }
  }'

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

CCTP repose sur un protocole smart contract + attestation 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'à status: "complete" et récupérez l’attestation.
3. Appelez receiveMessage sur le contrat MessageTransmitter de la chaîne de destination avec le message et l’attestation.

Vous obtenez de l’USDC natif sur la chaîne de destination, frappé lors d’une gravure vérifiée.

Webhooks et idempotence

• Abonnez-vous aux événements (payments, payouts, transfers, chargebacks) via /v1/notifications/subscriptions.
• Chaque webhook est signé ECDSA. Récupérez la clé publique (/v1/notifications/publicKey/get) et vérifiez l’en-tête X-Circle-Signature.
• Chaque requête mutative exige un en-tête Idempotency-Key (UUID v4 standard). Répétez une requête avec la même clé pour éviter les doublons (essentiel pour paiements et virements).

Erreurs courantes et limites de débit

• 401 Unauthorized : token manquant, malformé ou mauvais environnement.
• 400 invalid_entity_secret_ciphertext : texte chiffré réutilisé ou clé publique expirée. Régénérez.
• 429 Too Many Requests : sandbox limité à ~10 req/s/endpoint. Production : limite augmentée avec volume. Implémentez du retry exponentiel.
• insufficient_funds : solde USDC insuffisant ou carte refusée.

Pour une vue d’ensemble de l’infrastructure carte, consultez notre tour d’horizon de la meilleure API d’émission de cartes.

Tarification de l'API Circle

• Sandbox : gratuit.
• Production : Circle Mint ne facture pas la frappe/échange USDC pour institutions approuvées. Circle Payments : pourcentage + frais fixes par transaction (typiquement 2,9 % + 30 cents). Virements US : quelques dollars par transaction. W3S : tarifé par portefeuille/transaction (voir avec le commercial). CCTP : gratuit, seuls les frais de gas s’appliquent.

Tester l'API Circle avec Apidog

La surface Circle couvre REST, webhooks signés et contrats on-chain : une seule collection Postman est rarement suffisante. Apidog importe la spec OpenAPI de Circle, gère les tokens Bearer pour sandbox/production en tant qu'environnements distincts, et permet de chaîner paiement carte, virement et vérification webhook dans un seul script de test.

Téléchargez Apidog et chargez la spec Circle depuis leur portail développeur. Utilisez le simulateur pour tester les livraisons de webhooks pendant la construction, puis passez à un endpoint réel. En équipe, l’espace de travail partagé protège votre secret d’entité et versionne votre collection avec votre code backend.

FAQ

• Ai-je besoin du KYB pour tester l’API Circle ? Non. Les comptes sandbox sont ouverts à tous. Le KYB est requis uniquement pour la production. Le sandbox offre des faucets USDC sur chaque chaîne supportée.
• Différence entre Circle Mint et Circle Wallets ? Mint : passerelle institutionnelle (USD ⇄ USDC). Wallets/W3S : infrastructure de garde et transaction pour utilisateurs finaux. Les apps grand public utilisent Wallets, la trésorerie utilise Mint. Voir comment utiliser l’API MoonPay pour une alternative retail.
• Comment le CCTP évite-t-il le risque de pont ? USDC natif gravé sur la source, frappé sur la destination contre attestation signée Circle. Aucun pool de liquidité tiers.
• Peut-on utiliser Circle Wallets sans gérer de clés ? Oui. Les portefeuilles utilisateurs W3S utilisent MPC/PIN : les utilisateurs autorisent via le SDK Circle, vous ne touchez pas la clé privée. Les portefeuilles dev placent la signature sur votre backend (via secret d’entité).
• Circle prend-il en charge Solana et les chaînes non-EVM ? Oui. W3S couvre Solana, Aptos, NEAR, et plusieurs L2 EVM. CCTP v2 a étendu le support Solana en 2024.
• Comment faire pivoter le secret d’entité en sécurité ? Rotation via dashboard. Générez, enregistrez le nouveau secret, acceptez les deux textes chiffrés pendant la transition. Le SDK lit la variable d’environnement, donc un déploiement progressif suffit.