Bitcoin API: BTC-Zahlungen annehmen, ohne eine Node zu betreiben

Bitcoin Cores JSON-RPC will eine synchronisierte Node, bevor die erste brauchbare Antwort kommt. Eine REST API will einen API-Key. Der Unterschied zeigt sich im Kalender: Der initiale Block-Download dauert auf typischer Hardware Tage, und danach verbraucht die Node weiter Speicherplatz und Bandbreite und muss überwacht werden, solange Ihr Produkt lebt. Unser Artikel zu Blockchain API vs. Blockchain Node vergleicht beide Ansätze im Detail. Betreiben Sie Ihre eigene Node, wenn Sie Kontrolle auf Policy-Ebene über Ihre Sicht auf das Netzwerk brauchen; nutzen Sie die API, wenn Zahlungen das Ziel sind.

Die Alltagsaufrufe lassen sich sauber auf das REST-Modell übertragen. Wo eine Node-Integration getnewaddress und listtransactions umwickelt und auf Änderungen pollt, weist die API Adressen zu und lässt den Webhook das Beobachten übernehmen. Polling-Loops verschwinden, und mit ihnen die Cron-Jobs, die an einem Wochenende still kaputtgehen.

Es gibt einen zweiten Unterschied. Rohe RPC-Methoden liefern rohe Daten. Chaingateway liefert strukturiertes JSON mit lesbaren Feldern, sodass eine Antwort direkt in Ihre Datenbank wandern kann statt durch eine Parsing-Schicht.

Die REST-Seite des Sendepfads sind drei Endpoints. POST /api/v2/bitcoin/wallets erstellt eine Wallet, verschlüsselt mit einem Passwort, das Chaingateway nicht speichert – verlieren Sie es, kann niemand die Wallet wiederherstellen, was genau der Sinn ist. POST /api/v2/bitcoin/wallets/{wallet}/addresses leitet so viele Adressen darunter ab, wie Sie brauchen; eine Wallet trägt sie alle. Und POST /api/v2/bitcoin/transactions sendet:

curl -X POST https://app.chaingateway.io/api/v2/bitcoin/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
    "amount": 0.0015,
    "walletname": "treasury",
    "password": "wallet-password",
    "speed": "medium"
  }'

Die Antwort trägt die txid der broadcasteten Transaktion. speed nimmt fast, medium oder slow und setzt das Fee-Level – den Trade-off zwischen Kosten und Zeit bis zur ersten Bestätigung. Ein optionales subtractfee: true zieht die Netzwerkgebühr vom Betrag ab, statt sie obendrauf zu addieren, was Sie wollen, wenn ein Kunde sein volles Guthaben abhebt.

Bitcoin fügt etwa alle zehn Minuten einen Block hinzu, wobei einzelne Abstände stark variieren. Jeder neue Block, der auf den mit Ihrer Transaktion gebaut wird, fügt eine Bestätigung hinzu, und jede Bestätigung erschwert eine Rückabwicklung.

Sechs Bestätigungen – etwa eine Stunde – sind seit den frühen Börsentagen der de-facto-Standard für „abgewickelt“, und das gilt weiterhin Mitte 2026.

Zehn Minuten sind ein Durchschnitt, kein Zeitplan

Die Difficulty-Adjustment hält ihn über die Zeit stabil, aber einzelne Abstände streuen breit darum – zwei Blöcke innerhalb einer Minute kommen vor, ebenso vierzigminütige Dürreperioden. Payment-UX muss das respektieren: „etwa zehn Minuten“ ist ein Durchschnitt, kein Versprechen, weshalb Ihre Checkout-Seite „meist innerhalb einer Stunde“ sagen sollte statt einen Countdown-Timer laufen zu lassen, den sie nicht einhalten kann.

Warum nicht bei null Bestätigungen gutschreiben?

Weil eine Transaktion, bis sie in einem Block steckt, im Mempool sitzt, wo sie ersetzt oder doppelt ausgegeben werden kann, und selbst der neueste Block bei einer Reorganisation aus der Chain fallen kann. Die API teilt diese Arbeit in zwei. Der Webhook feuert, sobald die Transaktion on-chain abgewickelt ist – das Payload trägt Betrag, Adresse, txid und Blocknummer –, sodass Ihre UI sofort reagieren kann. Von dort liefert GET /api/v2/bitcoin/transactions/{txid}/decoded die aktuelle Bestätigungsanzahl, sodass Ihr Ledger nur Geld gutschreibt, das Ihren Schwellenwert erreicht hat. Zeigen Sie Fortschritt früh, schreiben Sie spät gut.

Bitcoin kennt keine Kontoguthaben. Was die Chain speichert, sind unspent transaction outputs – UTXOs –, jeder ein diskreter Wertklumpen, an eine Adresse gebunden. Das „Guthaben“ einer Wallet ist eine Zahl, die Ihre Software ableitet, indem sie jedes UTXO summiert, das ihre Adressen kontrollieren; das Protokoll speichert diese Summe nirgends. Ausgeben verbraucht ganze UTXOs und erzeugt neue, inklusive eines Wechselgeld-Outputs zurück an Sie selbst, so wie die Bezahlung einer 7-Euro-Rechnung mit einem 10-Euro-Schein Münzen zurückgibt.

Ethereum läuft nach dem umgekehrten Modell. Ein Konto hat ein Guthaben, die Chain speichert es direkt, und ein Deposit ist ein Increment. Auf EVM-Chains ist es normal, einem Kunden eine Adresse zu geben und über Jahre hundert Deposits darauf anhäufen zu lassen.

Für die Deposit-Verwaltung hat das UTXO-Modell einen praktischen Vorteil: Es drängt Sie zu einer Adresse pro Kunde oder pro Rechnung, was ohnehin das sauberere Design ist. Jede eingehende Zahlung ist ein neuer Output an eine Adresse, die Sie beobachten, sodass die Zuordnung eindeutig ist – kein Memo-Parsing, kein Abgleich nach Betrag. Es bedeutet auch, dass „das Guthaben einer Adresse“ eine Frage ist, die ein Indexer beantwortet, nicht die Chain selbst – genau die Buchhaltung, die Sie auslagern, indem Sie eine API mit Webhooks nutzen statt die Maschinerie selbst zu betreiben. Die Benachrichtigung sagt Ihnen: dieser Betrag, diese Adresse, diese Transaktion, dieser Block. Den Rest erledigt Ihr Ledger.

Fügen Sie den Header X-Network: testnet hinzu, und jeder Aufruf auf dieser Seite läuft gegen Bitcoins Testnetzwerk: dieselben Routen, dieselben Response-Formen, wertlose Coins. Faucets geben kostenlos Test-BTC aus, sodass sich der gesamte Deposit-Flow – Adresse, Zahlung, Webhook, Bestätigungen – Ende-zu-Ende proben lässt, ohne einen Satoshi auszugeben.

Halten Sie den Header hinter der Konfiguration statt im Code verstreut, und geben Sie Ihrer Staging-Umgebung eine separate Callback-URL, damit Test-Deposits nicht in das Produktions-Ledger sickern können. Funktioniert die Probe, entfernen Sie den Header. Sonst ändert sich nichts an der Integration, was der Sinn ist: Das erste Mainnet-Deposit sollte langweilig sein.

Ein Payments-Backend verdient sich an den schlechten Tagen seine Existenzberechtigung, planen Sie also die Fehlerpfade explizit.

Auf der HTTP-Ebene gelten die üblichen REST-Regeln. Ein 401 bedeutet, dass der Bearer-Token falsch oder fehlend ist; korrigieren Sie den Key, statt es erneut zu versuchen. Andere 4xx-Antworten weisen auf den Request selbst hin – loggen Sie den Body, der das Problem benennt, und behandeln Sie es als Bug. Antworten im 5xx-Bereich und Timeouts sind vorübergehend; wiederholen Sie diese mit Backoff.

Die Bitcoin-spezifischen Fehlermodi liegen oberhalb von HTTP. Ein Deposit, das nie bestätigt, hat meist zu wenig Gebühr bezahlt und steckt im Mempool fest; es kann Stunden später bestätigen oder ganz verschwinden, weshalb detected und settled in Ihrem System getrennte Zustände bleiben müssen. Eine Benachrichtigung mit einem Betrag unter der Rechnung ist eine Geschäftsentscheidung, kein Fehler – behandeln Sie sie im Code, nicht in einer Support-Warteschlange. Und war Ihr Webhook-Endpoint down, warten die fehlgeschlagenen Zustellungen auf Sie: GET /api/v2/bitcoin/webhooks/notifications/failed listet sie auf, POST /api/v2/bitcoin/webhooks/notifications/{id}/retry sendet jede erneut, und die vollständige Liste unter GET /api/v2/bitcoin/webhooks/notifications lässt Sie mit dem Ledger abgleichen und Lücken gutschreiben. Führen Sie diesen Abgleich nächtlich durch, selbst wenn nichts falsch aussieht. Ein Reconciliation-Job, der nur nach Vorfällen läuft, findet seine Bugs in Produktion.

Bitcoin selbst kennt kein USDT oder USDC – Stablecoins leben auf anderen Chains. Was die geteilte Plattform Ihnen gibt, ist ein Vorsprung: Ihre Bitcoin-Integration spricht bereits dieselbe API wie unsere Ethereum- und TRON-Endpoints. Nehmen Sie heute BTC an, fügen Sie im nächsten Sprint USDT auf TRON mit demselben Key und demselben Webhook-Handler hinzu. Die Blockchain-API-Übersicht listet alle sieben unterstützten Chains.

Die praktische Reihenfolge für die meisten Teams: BTC-Deposits zuerst launchen, weil Kunden genau danach namentlich fragen, dann Zahlungsdaten entscheiden lassen, welche Stablecoin-Schiene als Zweites dazukommt. Bei Chaingateway nutzt diese zweite Schiene Ihre Signaturverifizierung, Ihren Reconciliation-Job und Ihre Deposit-Zustandsmaschine unverändert.

• Es hat die längste Erfolgsgeschichte jeder Blockchain, im Betrieb seit 2009, und die breiteste Anerkennung unter Endnutzern.
• Das Netzwerk wickelt rund um die Uhr ab. Es gibt keine Bankzeiten und keine regionalen Cut-offs.
• Bestätigungen folgen einem vorhersehbaren Rhythmus, mit einem neuen Block etwa alle zehn Minuten, was Payment-Workflows leicht kalkulierbar hält.
• Die Adoption ist die größte aller Krypto-Netzwerke, sodass „Nehmt ihr Bitcoin?“ weiterhin die erste Frage von Kunden ist.

Keine dieser Eigenschaften stammt aus einem Roadmap-Update; es sind dieselben Garantien, mit denen das Netzwerk ausgeliefert wurde. Diese Stabilität ist das Argument für BTC in Produkten mit langem Horizont: Eine dieses Jahr gebaute Integration wird nicht durch einen Protokoll-Kurswechsel im nächsten Jahr obsolet – mehr, als die meisten Payment-Stacks von sich behaupten können.

Der naheliegende Fall ist Checkout: Ein Kunde wählt Bitcoin, und Ihre App weist eine Adresse zu; der Webhook bestätigt die Zahlung. Dieselben Bausteine tragen auch schwerere Lasten. Börsen und Gaming-Plattformen betreiben eine Deposit-Adresse pro Nutzer und schreiben Guthaben bei Bestätigung gut. Auszahlungs- und Remittance-Flows treiben grenzüberschreitende Transfers ohne Korrespondenzbanken dazwischen. Abo-Geschäfte generieren jeden Zyklus eine frische Rechnungsadresse und lassen den Webhook sie abschließen.

Was diese Fälle gemeinsam haben, ist die Form der Arbeit. Bitcoin übernimmt die Abwicklung; Ihre Anwendung übernimmt den Zustand. Die API sitzt zwischen beiden und verwandelt Chain-Events in HTTP-Aufrufe, die Ihr Framework bereits zu routen weiß – weshalb der Checkout-Fall und der Börsen-Fall auf derselben Handvoll Endpoints laufen.