Blog

Circle API: USDC Zahlungen, Wallets & Auszahlungen nutzen

Ashley Innocent

Ashley Innocent

23 April 2026

Circle API: USDC Zahlungen, Wallets & Auszahlungen nutzen

Apidog für Unternehmen

On-Premises-Bereitstellung

SSO & RBAC

SOC 2 konform

Apidog Enterprise entdecken

Circle gibt USDC aus, den zweitgrößten Stablecoin nach Marktkapitalisierung, und stellt eine Reihe von APIs bereit, mit denen Sie Dollar On-Chain bewegen können, ohne Custody-, Compliance- oder Bankinfrastruktur von Grund auf neu aufbauen zu müssen. Wenn Sie schon immer eine Marktplatz-Auszahlung in Minuten abwickeln, einem Benutzer erlauben wollten, per Karte einzuzahlen und als USDC abzuheben, oder Stablecoins über acht Blockchains hinweg mit einem einzigen Aufruf zu bewegen, ist die Circle API der kürzeste Weg dorthin. Die offiziellen Dokumente finden Sie unter developers.circle.com, und der USDC-Einführungsleitfaden unter circle.com/en/usdc ist lesenswert, bevor Sie loslegen.

Dieser Leitfaden führt Sie durch die gesamte Entwickleroberfläche: Kontoerstellung, Sandbox vs. Produktion, Bearer-Token-Authentifizierung, Endpunkte für Zahlungen und Auszahlungen, Circle Wallets (Web3 Services), das Cross-Chain Transfer Protocol (CCTP), Entity-Secret-Ciphertext für Entwicklergesteuerte Wallets, Webhooks, Idempotenz und KYB-Compliance. Erwarten Sie curl- und Node-Snippets, die Sie in Ihr Terminal einfügen können. Verwandte Lektüre: Unser Leitfaden zur besten Fiat On-Ramp Off-Ramp API vergleicht Circle mit seinen engsten Konkurrenten.

💡
Sie benötigen auch einen API-Client, der sowohl REST als auch Web3 fließend spricht, während Sie Prototypen erstellen. Apidog verarbeitet Circles Bearer-Authentifizierung, den Umgebungswechsel und das Webhook-Replay in einem einzigen Arbeitsbereich, sodass Sie Sandbox und Produktion nebeneinander testen können, ohne Ihre Sammlung neu schreiben zu müssen.
Button

TL;DR

Was ist die Circle API?

Circle ist ein reguliertes Zahlungsunternehmen, das USDC ausgibt und die Infrastruktur betreibt, die es an den US-Dollar bindet. Die Circle API bietet vier Produktlinien, die Sie kombinieren können:

Wenn Sie Circle mit der allgemeinen Web3-Infrastruktur vergleichen, lesen Sie unseren Überblick über die beste Krypto-Wallet-API und den Leitfaden wie man die Alchemy API verwendet, um zu sehen, wo jedes Tool passt.

Authentifizierung und Einrichtung

Erstellen Sie ein Konto unter console.circle.com. Die Konsole bietet Ihnen zwei Umgebungen: Sandbox und Produktion. Sandbox ist kostenlos und selbstbedienbar; die Produktion erfordert eine Know Your Business (KYB)-Genehmigung, die einige Werktage dauert und Gründungsdokumente, Informationen zum wirtschaftlichen Eigentümer und ein Finanzierungskonto erfordert.

Generieren Sie einen API-Schlüssel unter Entwickler → API-Schlüssel. Das Schlüsselformat ist TEST_API_KEY:<id>:<secret> in der Sandbox oder LIVE_API_KEY:<id>:<secret> in der Produktion. Übergeben Sie ihn als Bearer-Token:

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

Basis-URLs:

Für Entwicklergesteuerte Wallets in W3S benötigen Sie auch ein Entity Secret: eine 32-Byte-Hex-Zeichenkette, die Sie einmal generieren und über das Dashboard registrieren. Jeder Schreibaufruf muss einen frischen entitySecretCiphertext enthalten, der das Entity Secret ist, verschlüsselt mit Circles RSA-öffentlichem Schlüssel. Das Node SDK generiert ihn automatisch neu; wenn Sie Ihre eigene Implementierung erstellen, rotieren Sie den Ciphertext bei jeder Anfrage, da Circle wiederverwendete Werte ablehnt.

Installieren Sie das Node SDK:

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

Kern-Endpunkte

Ein Wallet-Set und eine Wallet erstellen

Wallets in W3S befinden sich innerhalb eines Wallet-Sets (einer Gruppe, die einen HD-Seed teilt). Erstellen Sie zuerst das Set und dann Wallets darin.

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 gibt eine id, eine address und die Blockchain, auf der sie sich befindet, zurück. Füllen Sie sie mit Testnet-USDC vom Circle Faucet auf, um fortzufahren.

USDC von einer entwicklergesteuerten Wallet übertragen

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

Die Antwort gibt eine Transaktions-id zurück, die Sie über GET /v1/w3s/transactions/{id} abfragen oder über einen Webhook abhören können.

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

Kartendaten müssen PGP-verschlüsselt mit dem öffentlichen Schlüssel von Circle sein (abrufbar unter /v1/encryption/public). Die Antwort gibt eine Zahlungs-id zurück, die die Stadien pending → confirmed → paid durchläuft.

Eine Auszahlung per Überweisung oder ACH senden

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 bewegen

CCTP ist ein Smart-Contract-Protokoll, kein REST-Endpunkt, daher kombinieren Sie ein On-Chain-Burn mit Circles Attestierungsdienst:

  1. Rufen Sie depositForBurn auf dem TokenMessenger-Vertrag auf der Quell-Chain auf.
  2. Fragen Sie https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} ab, bis status: "complete" ist und Sie einen attestation Hex-Blob erhalten.
  3. Rufen Sie receiveMessage auf dem MessageTransmitter-Vertrag auf der Ziel-Chain mit den Nachrichten-Bytes und der Attestierung auf.

Sie erhalten am Ende native USDC auf der Ziel-Chain, aus dem Nichts geprägt gegen einen überprüfbaren Burn. Keine Wrapped Tokens, kein Brückenliquiditätsrisiko.

Webhooks und Idempotenz

Circle POSTet Ereignisse (payments, payouts, transfers, chargebacks) an jeden HTTPS-Endpunkt, den Sie über /v1/notifications/subscriptions abonnieren. Jeder Webhook ist mit einem ECDSA-Schlüssel signiert; rufen Sie den öffentlichen Schlüssel von /v1/notifications/publicKey/get ab und überprüfen Sie den X-Circle-Signature-Header, bevor Sie der Payload vertrauen.

Jeder mutierende Endpunkt erfordert einen Idempotency-Key-Header (eine UUID v4 ist Standard). Das Wiederholen einer Anfrage mit demselben Schlüssel gibt die ursprüngliche Antwort zurück, anstatt eine doppelte Zahlung zu erstellen. Dies ist wichtig: Karten und Überweisungen verzeihen keine doppelten Sendungen.

Häufige Fehler und Ratenbegrenzungen

Für einen breiteren Überblick über die Karteninfrastruktur beleuchtet unser Leitfaden zur besten Kartenherausgabe-API Emittenten, die gut mit Circle-Auszahlungen harmonieren.

Circle API Preise

Die Sandbox ist kostenlos. In der Produktion berechnet Circle Mint nichts für das Prägen oder Einlösen von USDC für genehmigte institutionelle Kunden mit qualifiziertem Volumen. Circle Payments erhebt einen Prozentsatz plus eine feste Gebühr pro Kartentransaktion (typischerweise 2,9 % + 30 Cent, bei größeren Mengen verhandelbar). Auszahlungen an US-Überweisungen kosten ein paar Dollar pro Transaktion. W3S-Wallets werden pro Wallet und pro Transaktion bepreist; kontaktieren Sie den Vertrieb für ein Produktionsangebot. CCTP selbst ist kostenlos; Sie zahlen Gasgebühren für die Quell- und Ziel-Chain.

Testen der Circle API mit Apidog

Circles Oberfläche umfasst REST, signierte Webhooks und On-Chain-Verträge, sodass eine einzelne Postman-Sammlung selten den gesamten Ablauf abbildet. Apidog importiert Circles OpenAPI-Spezifikation direkt, speichert Sandbox- und Produktions-Bearer-Tokens als separate Umgebungen und ermöglicht Ihnen das Schreiben eines Testskripts, das eine Kartenzahlung, eine Auszahlung und eine Webhook-Verifizierung in einem einzigen Durchlauf miteinander verbindet.

Laden Sie Apidog herunter und laden Sie die Circle-Spezifikation von deren Entwicklerportal. Verwenden Sie den Mock-Server, um Webhook-Zustellungen zu simulieren, während Sie den Verifizierungs-Handler erstellen, und wechseln Sie dann zu einem realen Endpunkt, sobald Sie bereit sind. Für Teams hält der gemeinsame Arbeitsbereich Ihr Entity Secret aus dem Chat fern und versioniert Ihre Sammlung zusammen mit Ihrem Backend-Code.

FAQ

Benötige ich KYB, um die Circle API zu testen?Nein. Sandbox-Konten stehen jedem mit einer E-Mail-Adresse offen. Sie benötigen KYB nur, um echte Dollar in der Produktion zu bewegen. Die Sandbox wird mit Faucets für USDC auf jeder unterstützten Chain geliefert.

Was ist der Unterschied zwischen Circle Mint und Circle Wallets?Circle Mint ist die institutionelle On-Ramp: Sie überweisen USD ein, Sie erhalten USDC heraus (und umgekehrt). Circle Wallets / W3S ist die Custody- und Transaktionsinfrastruktur für Ihre Endbenutzer. Die meisten Verbraucher-Apps verwenden Wallets; Treasury-Apps verwenden Mint direkt. Unser Leitfaden zur Verwendung der MoonPay API behandelt eine reine Einzelhandelsalternative, wenn Sie keine Mint-Level-Ausgabe benötigen.

Wie vermeidet CCTP ein Brückenrisiko?Native USDC werden auf der Quell-Chain verbrannt und auf der Ziel-Chain gegen eine signierte Attestierung von Circle neu geprägt. Es gibt keinen gesperrten Liquiditätspool, der durch einen Brücken-Exploit geleert werden könnte. Sie vertrauen immer noch dem Attestierungsdienst von Circle, aber Sie vertrauen keinem Validator-Set einer Drittanbieter-Brücke.

Kann ich Circle Wallets verwenden, ohne Schlüssel zu halten?Ja. Benutzergesteuerte Wallets in W3S verwenden MPC und PIN-basierte Authentifizierung, sodass Endbenutzer Transaktionen über Circles SDK autorisieren und Sie niemals einen privaten Schlüssel berühren. Entwicklergesteuerte Wallets legen die Signaturberechtigung über das Entity Secret auf Ihr Backend.

Unterstützt Circle Solana und Nicht-EVM-Chains?Ja. W3S deckt Solana, Aptos, NEAR und mehrere EVM L2s ab. CCTP v2 erweiterte die Solana-Unterstützung im Jahr 2024, sodass native USDC nun frei zwischen Solana und dem EVM-Ökosystem bewegt werden können.

Wie rotiere ich das Entity Secret sicher?Circle unterstützt die Rotation des Entity Secrets über das Dashboard. Generieren Sie ein neues Secret, registrieren Sie es und lassen Sie sowohl alte als auch neue Ciphertexte parallel für ein kurzes Übergangsfenster laufen. Das SDK liest das Secret, das in Ihrer Umgebungsvariable ist, sodass eine Rolling-Deploy es sauber handhabt.

Praktizieren Sie API Design-First in Apidog

Entdecken Sie eine einfachere Möglichkeit, APIs zu erstellen und zu nutzen

Kostenlos registrierenDownload