Emre Demir

Posted on Apr 23 • Originally published at apidog.com

Circle API: USDC Zahlungen, Wallets & Auszahlungen nutzen

Circle gibt USDC aus, den zweitgrößten Stablecoin nach Marktkapitalisierung, und stellt APIs bereit, mit denen du Dollar On-Chain bewegen kannst, ohne selbst Custody-, Compliance- oder Bankinfrastruktur aufbauen zu müssen. Wenn du Marktplatz-Auszahlungen in Minuten abwickeln, Nutzern Einzahlungen per Karte ermöglichen oder Stablecoins über acht Blockchains hinweg mit einem einzigen API-Call transferieren willst, ist die Circle API dein direkter Weg. Die offiziellen Dokumente findest du unter developers.circle.com. Lies auch den USDC-Einführungsleitfaden unter circle.com/en/usdc, bevor du startest.

Teste Apidog noch heute

In diesem Guide lernst du die komplette Entwickleroberfläche kennen: Kontoerstellung, Sandbox vs. Produktion, Bearer-Token-Authentifizierung, Payment- und Payout-Endpunkte, Circle Wallets (Web3 Services), Cross-Chain Transfer Protocol (CCTP), Entity-Secret-Ciphertext für Entwickler-Wallets, Webhooks, Idempotenz und KYB-Compliance. Du findest konkrete curl- und Node-Snippets zum direkten Ausprobieren. Lies auch unseren Vergleich zur besten Fiat On-Ramp Off-Ramp API für einen Marktüberblick.

💡Du brauchst einen API-Client, der REST und Web3 kann. Apidog unterstützt Circles Bearer-Auth, Umgebungswechsel und Webhook-Replay in einem Workspace. Teste Sandbox und Produktion parallel, ohne deine Sammlung zu duplizieren.

TL;DR

Die Circle API besteht aus mehreren Diensten: Circle Payments (Karte, ACH, Überweisung), Circle Mint (USDC-Ausgabe für Institutionen), Circle Wallets/W3S (programmierbare Wallets), CCTP (native Cross-Chain USDC Transfers).
Authentifiziere dich mit einem Bearer-Token: Sandbox-Schlüssel starten mit TEST_API_KEY:, Produktionsschlüssel mit LIVE_API_KEY:.
Entwicklergesteuerte Wallets benötigen für jeden Schreibvorgang einen neuen Entity-Secret-Ciphertext (RSA-verschlüsselt).
CCTP transferiert native USDC via Burn-and-Mint über Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana und mehr.
Für die Produktionsumgebung ist KYB erforderlich. Die Sandbox ist offen für alle Entwickler.
Verwende immer Idempotency-Keys bei mutierenden Requests und prüfe Webhook-Signaturen mit dem öffentlichen Schlüssel von /notifications/publicKey/get.

Was ist die Circle API?

Circle ist ein reguliertes Zahlungsunternehmen, das USDC emittiert und verwaltet. Die API umfasst vier Produktbereiche, die du kombinieren kannst:

Circle Payments API: Akzeptiere Karten, ACH, SEPA, Überweisung – der Betrag landet als USDC in deiner Händler-Wallet.
Circle Payouts API: Sende Überweisungen/ACH vom USDC-Guthaben an registrierte Bankkonten.
Circle Wallets (W3S): Erstelle custodial oder developer-controlled Wallets auf mehreren Chains, signiere Transaktionen, verwalte Gas.
CCTP: Verbrenne USDC auf einer Chain und prägt sie auf einer Ziel-Chain neu – du erhältst native Assets ohne Wrapped Token.

Mehr zur Web3-Infrastruktur findest du in unserem Überblick zur besten Krypto-Wallet-API sowie zum Alchemy API Guide.

Authentifizierung und Einrichtung

Erstelle ein Konto auf console.circle.com.
Du bekommst zwei Umgebungen: Sandbox (direkt verfügbar) und Produktion (erfordert KYB mit Unternehmensdokumenten und Bankverbindung).
Generiere einen API-Schlüssel (Sandbox: TEST_API_KEY:<id>:<secret>, Produktion: LIVE_API_KEY:<id>:<secret>). Nutze ihn als Bearer-Token:

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

Basis-URLs:

Sandbox: https://api-sandbox.circle.com
Produktion: https://api.circle.com

Für developer-controlled Wallets (W3S) brauchst du ein Entity Secret (32 Byte Hex-String, einmal generieren und im Dashboard registrieren). Jeder Schreibaufruf erfordert einen frischen entitySecretCiphertext, erzeugt mit Circles RSA-Public-Key. Das Node SDK übernimmt das automatisch, bei eigener Implementierung musst du den Ciphertext bei jedem Request rotieren.

Node SDK Installation:

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

Kern-Endpunkte

Wallet-Set und Wallet erstellen

Wallets liegen in einem Wallet-Set (Gruppe mit gemeinsamem HD-Seed). Erst Set erstellen, dann Wallets darin anlegen:

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

Jede Wallet liefert eine id, address und die jeweilige Blockchain zurück. Fülle sie mit Testnet-USDC vom Circle Faucet auf.

USDC von einer developer-controlled Wallet übertragen

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

Antwort enthält eine Transaktions-id. Status abfragen via GET /v1/w3s/transactions/{id} oder per Webhook.

Kartenzahlung akzeptieren und als USDC abrechnen

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": "..." }
  }'

Karten müssen PGP-verschlüsselt sein (Public Key via /v1/encryption/public). Antwort liefert eine Payment-id, Status: pending → confirmed → paid.

Auszahlung per Überweisung oder 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" }
  }'

USDC Cross-Chain mit CCTP

CCTP ist ein On-Chain-Protokoll:

depositForBurn auf dem TokenMessenger-Contract der Quell-Chain ausführen.
Status via https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} abfragen, bis status: "complete" und ein attestation Hex-Blob geliefert wird.
receiveMessage auf dem MessageTransmitter-Contract der Ziel-Chain mit diesen Daten aufrufen.

So erhältst du native USDC auf der Ziel-Chain – kein Wrapped Token, kein Brückenrisiko.

Webhooks und Idempotenz

Circle sendet Events (payments, payouts, transfers, chargebacks) an konfigurierte HTTPS-Endpoints (Subscription via /v1/notifications/subscriptions). Jeder Webhook ist ECDSA-signiert – prüfe den Public Key aus /v1/notifications/publicKey/get gegen den X-Circle-Signature-Header.

Jede mutierende API benötigt einen Idempotency-Key-Header (UUID v4). Identische Keys liefern die ursprüngliche Antwort zurück und verhindern doppelte Zahlungen – essenziell für Karten und Überweisungen.

Häufige Fehler & Ratenlimits

401 Unauthorized: Bearer-Token fehlt/falsch oder falsche Umgebung.
400 invalid_entity_secret_ciphertext: Ciphertext wiederverwendet oder mit altem Public Key verschlüsselt. Neu generieren.
429 Too Many Requests: Sandbox ~10 Requests/Sek./Endpoint, Produktion skaliert mit Volumen. Implementiere Exponential Backoff.
insufficient_funds: Nicht genug USDC auf Wallet oder Karte hat AVS/CVV-Prüfung nicht bestanden.

Weitere Details zur Karteninfrastruktur im Karten-API-Leitfaden.

Circle API Preise

Sandbox: Kostenlos.
Produktion:
- Circle Mint: Kostenlos für zugelassene Institutionen mit Volumen.
- Circle Payments: Typisch 2,9% + 30 Cent pro Kartentransaktion (verhandelbar).
- Payouts: Überweisungen kosten wenige Dollar pro Transaktion.
- W3S Wallets: Preis pro Wallet und pro Transaktion (Vertrieb kontaktieren).
- CCTP: Kostenlos; du zahlst nur die Gasgebühren.

Circle API mit Apidog testen

Circles API kombiniert REST, signierte Webhooks und On-Chain-Contracts – das überfordert klassische Postman-Sammlungen. Apidog importiert Circles OpenAPI-Spezifikation direkt, trennt Sandbox- und Produktions-Tokens als separate Umgebungen und erlaubt Testskripte, die Payments, Payouts und Webhook-Checks in einem Lauf verbinden.

Lade Apidog herunter und importiere die Circle-Spezifikation. Simuliere Webhooks mit dem Mock-Server, entwickle deinen Verifizierungs-Handler und schalte dann auf echte Endpunkte um. Im Team schützt der gemeinsame Workspace dein Entity Secret und versioniert deine Sammlung mit dem Backend-Code.

FAQ

Benötige ich KYB, um die Circle API zu testen?

Nein. Sandbox-Accounts sind für jeden mit E-Mail frei verfügbar. KYB brauchst du erst beim Live-Geldfluss. Die Sandbox bietet Faucets für USDC auf allen Chains.

Was ist der Unterschied zwischen Circle Mint und Circle Wallets?

Circle Mint ist die institutionelle Fiat-Onramp: USD einzahlen, USDC erhalten und umgekehrt. Circle Wallets/W3S ist Custody- und Transaktionsinfrastruktur für Endnutzer. Verbraucher-Apps nutzen Wallets; Treasury-Apps Mint. Siehe auch unseren MoonPay API Leitfaden als Retail-Alternative.

Wie vermeidet CCTP Brückenrisiko?

USDC wird auf der Quell-Chain verbrannt und auf der Ziel-Chain via signierter Attestierung von Circle neu geprägt. Kein gesperrter Liquiditätspool, kein Drittanbieter-Validator-Set.

Kann ich Circle Wallets nutzen, ohne Schlüssel zu halten?

Ja. User-controlled Wallets in W3S verwenden MPC und PIN-basierte Authentifizierung – Endnutzer autorisieren über das SDK, du hältst keine privaten Schlüssel. Developer-controlled Wallets autorisieren Transaktionen via Entity Secret auf deinem Backend.

Unterstützt Circle Solana und Non-EVM-Chains?

Ja. W3S deckt Solana, Aptos, NEAR und diverse EVM-L2s ab. CCTP v2 unterstützt seit 2024 Solana → native USDC frei zwischen Solana und EVM-Chains transferieren.

Wie rotiere ich das Entity Secret sicher?

Im Dashboard ein neues Secret generieren und parallel zum alten für kurze Zeit beide zulassen. Das SDK liest das Secret aus der Umgebungsvariable – Rolling-Deploy genügt.

DEV Community