Native REST API

Die native API ist die eigene REST-Schnittstelle von blockwallets: Rechnungen in US-Cent, eine idempotente ref pro Bestellung, statische Einzahlungskonten für alle Netzwerke und mit HMAC-SHA256 signierte Webhooks. Sie erzeugt dieselben Rechnungen auf demselben gehosteten Checkout wie die Cryptomus-kompatible API, mit denselben Gebühren und demselben Guthaben.

Sie erzeugen Ihre Keys selbst im Dashboard unter „Entwickler › Integration & Keys“: einen Live- und einen Test-Key samt Webhook-Signaturgeheimnissen. Jedes wird nur einmal angezeigt; die Liste zeigt nur das Präfix. Ist für Ihr Konto die Zwei-Faktor-Authentifizierung aktiv, verlangt das Erzeugen oder Erneuern eines Live-Keys einen Code. Noch kein Händlerkonto? Zugang anfragen. Sie nutzen bereits Cryptomus? Sehen Sie sich die Cryptomus-kompatible API an (so wählen Sie).

Keys und Anfragen

Base-URL https://blockwallets.io. Anfragen und Antworten sind JSON. Jede Anfrage enthält:

• Authorization: Bearer bw_live_… oder Bearer bw_test_…: Das Präfix bestimmt den Modus, ein Test-Key sieht also nur Test-Rechnungen und läuft auf Testnets
• Content-Type: application/json bei POST-Anfragen
• Bewahren Sie Keys nur auf Ihrem Server auf, nie in einer Webseite oder App; wir speichern nur ihren Hash

Fehler liefern einen HTTP-Status und {"error": {"code": "…", "message": "…"}}: 400 invalid_request (ein Feld fehlt oder ist fehlerhaft), 401 unauthorized (Key fehlt, ist unbekannt oder deaktiviert), 404 not_found, 409 conflict (die Anfrage widerspricht dem aktuellen Zustand der Rechnung), 422 currency_unsupported.

Endpoints

Hängen Sie ?probe=1 an eine Abfrage von Rechnung oder Einzahlungskonto, um dabei die Chain zu prüfen (höchstens alle 10 Sekunden); andernfalls erhalten Sie den letzten Stand unseres Scanners, der jede Minute prüft.

Rechnung erstellen POST /v1/invoices

Rufen Sie POST /v1/invoices auf, wenn der Kunde zur Kasse geht, und leiten Sie ihn auf pay_url aus der Antwort weiter.

curl -X POST https://blockwallets.io/v1/invoices \
  -H "Authorization: Bearer $BW_KEY" -H "Content-Type: application/json" \
  -d '{"ref":"order_1042","amount":4200,"title":"Order #1042",
       "return_url":"https://shop.example/cart","success_url":"https://shop.example/thanks?order=1042",
       "meta":{"user_id":42}}'

Jede URL muss auf einer Ihrer Website-Domains liegen (Dashboard → „Entwickler › Integration & Keys“). Die Antwort ist das unten beschriebene Rechnungsobjekt; network, address und pay_amount werden gefüllt, sobald ein Netzwerk gewählt ist.

Das Rechnungsobjekt

Ids beginnen mit inv_. amount ist in US-Cent; pay_amount und paid_amount sind Coin-Mengen als Dezimal-Strings im gewählten Netzwerk.

{
  "id": "inv_01J8…",
  "ref": "order_1042",
  "mode": "live",
  "status": "pending",
  "amount": 4200,
  "currency": "USD",
  "title": "Order #1042",
  "meta": { "user_id": 42 },
  "network": null,
  "address": null,
  "pay_amount": null,
  "paid_amount": null,
  "payments": [],
  "pay_url": "https://blockwallets.io/pay/inv_01J8…",
  "return_url": "https://shop.example/cart",
  "success_url": "https://shop.example/thanks?order=1042",
  "created_at": "2026-11-03T08:00:00.000Z",
  "expires_at": "2026-11-03T09:00:00.000Z",
  "paid_at": null,
  "closed_at": null
}

Weitere Felder: pay_url (der gehostete Checkout), payments (jede Überweisung mit txid, amount, confirmations und confirmed), expires_at, paid_at, closed_at; BTC, LTC, DOGE, BCH und native Coins haben außerdem rate (US-Dollar pro Coin, 30 Minuten fest), rate_locked_until und paid_cents (bisher eingegangen, in US-Cent).

Netzwerke

Übergeben Sie die id als network. GET /v1/networks liefert die in Ihrem Modus gerade offenen Netzwerke; ein Netzwerk kann pausiert sein, lesen Sie die Liste also lieber aus, statt Werte fest einzutragen.

Einzahlungskonten (statische Adressen) POST /v1/deposit-accounts

POST /v1/deposit-accounts mit {"customer_ref": "user_42"} gibt diesem Kunden eine dauerhafte Adresse in jedem Netzwerk (alle EVM-Chains teilen sich eine Adresse). Alles, was er sendet, wird in US-Dollar gutgeschrieben, mit einem Webhook deposit.credited pro Überweisung.

curl -X POST https://blockwallets.io/v1/deposit-accounts \
  -H "Authorization: Bearer $BW_KEY" -H "Content-Type: application/json" \
  -d '{"customer_ref":"user_42"}'

{
  "id": "dac_01J8…",
  "mode": "live",
  "customer_ref": "user_42",
  "deposit_url": "https://blockwallets.io/deposit/dac_01J8…",
  "min_amount": 100,
  "currency": "USD",
  "networks": [
    { "id": "USDT_TRC20", "chain": "tron", "token": "USDT", "address": "TXy4…8kQ2", "min_amount": 100, "confirmations": 1, … },
    { "id": "USDC_BASE", "chain": "base", "token": "USDC", "address": "0x5aE1…", "min_amount": 100, "confirmations": 20, … }
  ]
}

• customer_ref: 1–128 Zeichen aus Buchstaben, Ziffern und _ . : @ -; derselbe Wert liefert immer dasselbe Konto. Optional return_url auf Ihren Domains
• Die Antwort enthält deposit_url (eine gehostete Seite mit Adressen, QR-Codes und letzten Einzahlungen) und networks (je Netzwerk id, address, min_amount, confirmations)
• Einzahlungs-ids beginnen mit dep_; amount sind US-Cent, amount_token die Coin-Menge, und Coins mit Kurs tragen den verwendeten rate

Überweisungen unter dem Mindestbetrag (meist $1, BTC $5) werden als below_min erfasst und nicht automatisch gutgeschrieben; kontaktieren Sie uns, damit sie gutgeschrieben werden.

Webhooks

Wir senden JSON per POST an die Webhook-URL im Dashboard („Entwickler › Integration & Keys“; Live und Test haben jeweils eigene URL und eigenes Secret). Der Body ist das Event:

POST /your/webhook
X-BW-Event: ev_01J8…
X-BW-Delivery: 1
X-BW-Signature: t=1793693052,v1=5f0c9b…

{"id":"ev_01J8…","type":"invoice.paid","created_at":"2026-11-03T08:04:12.000Z","invoice":{"id":"inv_01J8…","ref":"order_1042","status":"paid","amount":4200,…}}

• X-BW-Signature: t=<unix seconds>,v1=<hex>, wobei v1 = HMAC-SHA256(Webhook-Secret dieses Modus, t + . + roher Body)
• X-BW-Event: die Event-id (ev_…); deduplizieren Sie darüber
• X-BW-Delivery: die Nummer des Versuchs, beginnend bei 1

Prüfen Sie gegen den rohen Body, bevor Sie ihn parsen, lehnen Sie ein t ab, das mehr als 300 Sekunden von Ihrer Uhr abweicht, und vergleichen Sie in konstanter Zeit. invoice / deposit im Body ist dasselbe Objekt, das eine Abfrage liefert.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string), header: X-BW-Signature
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return typeof parts.v1 === "string" && parts.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Eine 2xx-Antwort gilt als zugestellt; andernfalls wiederholen wir nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 12 Stunden, 24 Stunden und 24 Stunden (insgesamt 8 Versuche).

Events und erneute Zustellung

GET /v1/events?invoice_id=inv_… (oder deposit_id=dep_…) listet die Webhooks einer Rechnung oder Einzahlung mit state, attempts, last_status und last_error. POST /v1/events/ev_…/redeliver reiht ihn sofort neu ein, zum Beispiel nachdem Sie Ihren Endpoint repariert haben. Die Seite „Entwickler › Webhook-Protokoll“ im Dashboard zeigt jeden Versuch mit Anfrage und Antwort.

Testmodus

Mit einem bw_test_-Key erstellte Rechnungen laufen auf Testnets und berühren nie echtes Geld. Der gehostete Checkout zeigt eine Schaltfläche „Zahlung simulieren“ (voll / halb / überzahlt), sodass Sie Status und Webhooks sehen, ohne Testnet-Coins zu besorgen.