Eine Zahlungs-API, die für KI-Agenten-Code entwickelt wurde.
Eine kleine REST API. Signierte Webhooks. Offizielle SDKs in fünf Sprachen. Entwickelt, damit Ihr Agent USDC senden und abwickeln und Zahlungen in wenigen Zeilen Code überprüfen kann.
Die Blockchain0x API ist absichtlich klein. Wir möchten nicht, dass Sie eine Stunde Dokumentation lesen, um Ihre erste Zahlung zu tätigen. Wir möchten, dass Sie einen Code-Schnipsel kopieren, Ihren API-Schlüssel einfügen und ihn ausführen.
Eine kleine Oberfläche, die für Agentencode erstellt wurde.
Die zahlungsbezogenen Routen sind unten aufgeführt. Webhooks, API-Schlüssel und nur lesbare Ausgabenberechtigungen runden die Oberfläche ab; das SDK wickelt alles ab.
/v1/paymentsSenden Sie eine USDC-Zahlung von einer Agenten-Wallet/v1/transactions/{id}Rufen Sie den Status und den Hash einer Transaktion ab/v1/payment-requests/{id}/settleEine Rechnung mit On-Chain-Beweis abwickeln/v1/agents/{id}Rufen Sie eine Agenten-Wallet ab/v1/agentsAgenten-Wallet erstellenAlle mit HMAC-SHA256 signiert.
Unterschrift in der X-Blockchain0x-Signature Header. Replay-Fenster von 5 Minuten. Idempotenzschlüssel bei jedem POST.
payment.receivedUSDC ist in einer Ihrer Agenten-Wallets angekommen.
payment.senteine ausgehende Zahlung von Ihrem Agenten wurde on-chain abgeschlossen
wallet.deployeddie Smart Wallet eines Agenten wurde bereitgestellt
webhook.testeine Testlieferung, die Sie vom Dashboard aus ausgelöst haben
Senden Sie USDC von der Wallet Ihres Agenten.
from blockchain0x import Client
client = Client(api_key="sk_test_...") # sk_test_ testnet, sk_live_ mainnet
tx = client.payments.create(body={
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000", # USDC base units (6 decimals): 0.01 USDC
})
print(tx) # may return 503 until the chain adapter is wired for your networkTypisierte Clients für TypeScript und Python.
npm install @blockchain0x/nodeFunktioniert mit Node 18+. Native TypeScript-Typen.
pip install blockchain0xPython 3.9+. Sync- und asynchrone Clients.
Die Anforderungsinhalte, die das SDK umschließt.
Dies sind die verifizierten Eingaben für jede Route. Antworten werden hier kurz angezeigt; die vollständigen typisierten Formen befinden sich im SDK und in der API-Referenz. Beträge sind USDC-Basiseinheiten (6 Dezimalstellen).
/v1/paymentsSenden Sie eine USDC-Zahlung (payments.create). amountWei sind USDC-Basiseinheiten (6 Dezimalstellen). Kann 503 zurückgeben, bis der Chain-Adapter verbunden ist.
{
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000",
"metadata": { "reason": "Research report" }
}{
"txHash": "0xff5...e12"
}/v1/payment-requests/{id}/settleSetzen Sie eine Zahlungsanforderung (Rechnung) um, die im Dashboard erstellt wurde, mit On-Chain-Beweis (paymentRequests.settle). Es gibt keinen Erstellungsweg - nur abwickeln.
{
"txHash": "0xff5...e12",
"payerAddress": "0xBuyer...",
"amountUsdcVerified": "0.10"
}{
"txHash": "0xff5...e12"
}/v1/transactions/{id}Rufen Sie eine einzelne Transaktion nach ID ab (transactions.get).
(no body){
"id": "tx_01J9...",
"txHash": "0xff5...e12"
}/v1/agents/{id}Rufen Sie eine Agenten-Wallet ab (agents.get). Ihre öffentliche Seite befindet sich unter wallet.blockchain0x.com/a/{slug}.
(no body){
"id": "agt_01J9QKE...",
"name": "research-bot",
"public_url": "https://wallet.blockchain0x.com/a/research-bot"
}/v1/agents/{id}/spend-permissionsLesen Sie die Ausgabenberechtigungen eines Agenten. NUR-LESEN über die API - Erstellung und Änderungen sind nur im Dashboard möglich.
(no body){
"allowance_wei": "5000000",
"per_tx_wei": "1000000",
"period_seconds": 86400,
"start_at": "2026-05-15T00:00:00Z",
"revoked_at": null
}Überprüfen Sie immer die Signatur, bevor Sie der Nutzlast vertrauen.
Jeder kann an Ihre Callback-URL POSTEN. Die Signatur beweist, dass das Ereignis tatsächlich von uns stammt.
Jede Lieferung trägt ein X-Blockchain0x-Signature header (t=<unix>,v1=<hex>) - ein HMAC-SHA256 über den String `${t}.${rawBody}` mit Ihrem Webhook-Geheimnis, innerhalb eines 5-minütigen Replay-Fensters. In Node erledigt webhooks.verify von @blockchain0x/node dies und gibt eine diskriminierte Vereinigung zurück, auf der Sie verzweigen. In anderen Sprachen berechnen Sie dasselbe HMAC und vergleichen Sie in konstanter Zeit. Lesen Sie den RAW-Körper, nicht eine geparste Kopie - das erneute Serialisieren bricht die Signatur.
import express from "express";
import { webhooks } from "@blockchain0x/node";
const app = express();
// Capture the RAW body. The HMAC is over the exact bytes on the wire.
app.use(express.raw({ type: "application/json" }));
app.post("/webhooks/payment", (req, res) => {
const result = webhooks.verify({
headers: req.headers,
rawBody: req.body, // Buffer, raw bytes
secret: process.env.BLOCKCHAIN0X_WEBHOOK_SECRET!,
});
if (!result.ok) return res.status(400).json({ code: result.code });
// result.eventType is "payment.received" | "payment.sent" | ...
handleEvent(result);
res.status(200).send("ok");
});import hmac, hashlib, os, time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["BLOCKCHAIN0X_WEBHOOK_SECRET"].encode()
@app.post("/webhooks/payment")
def receive():
raw = request.get_data() # RAW bytes - do not parse first
sig = request.headers.get("X-Blockchain0x-Signature", "")
ts = request.headers.get("X-Blockchain0x-Timestamp", "")
# Header is "t=<unix>,v1=<hex>"; some proxies send bare hex + the ts header.
parts = dict(p.split("=", 1) for p in sig.split(",") if "=" in p)
t, v1 = parts.get("t", ts), parts.get("v1", sig)
want = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(want, v1) or abs(time.time() - int(t)) > 300:
abort(401)
handle_event(request.headers.get("X-Blockchain0x-Event-Type"), request.get_json())
return "ok", 200Das Webhook-Geheimnis wird einmal zurückgegeben, wenn Sie das Webhook erstellen oder rotieren (webhooks.rotateSecret), und BLOCKCHAIN0X_WEBHOOK_SECRET ist der Ort, an dem Ihr Handler es liest. Das Rotieren macht das alte Geheimnis ungültig, also koordinieren Sie die Bereitstellung: Setzen Sie das neue Geheimnis in der Umgebung Ihres Servers, implementieren Sie es und rotieren Sie dann. Die ausgelieferten Ereignisse sind payment.received, payment.sent, wallet.deployed und webhook.test - verzweigen Sie sich nach dem Ereignistyp, ignorieren Sie den Rest.
Sicher erneut versuchen. Die API wird nicht zweimal zahlen.
Agentencode-Wiederholungen. Netzwerke trennen Verbindungen. LLMs entscheiden sich, das Tool zweimal aufzurufen. Um dies sicher zu machen, senden Sie ein Idempotency-Key header im POST. payments.create im SDK mintet automatisch einen stabilen für Sie, sodass ein wiederholter Aufruf auf eine einzige On-Chain-Übermittlung zusammenfällt, anstatt zweimal zu zahlen. Überschreiben Sie es mit Ihrem eigenen Schlüssel, wenn Sie die gleiche logische Operation über Prozesse hinweg deduplizieren möchten.
curl -X POST https://api.blockchain0x.com/v1/payments \
-H "Authorization: Bearer $BLOCKCHAIN0X_API_KEY" \
-H "Idempotency-Key: 8e2c3a40-pay-vendor-once" \
-H "Content-Type: application/json" \
-d '{ "agentId": "agt_123", "to": "0xRecipient", "amountWei": "10000" }'- Erster Anruf: reicht die Zahlung ein, gibt die Transaktion zurück.
- Erneut versuchen mit dem gleichen Schlüssel: fällt auf eine On-Chain-Einreichung zusammen, anstatt zweimal zu zahlen.
- Das SDK kümmert sich darum: payments.create mintet automatisch einen stabilen Idempotency-Key, sodass ein wiederholter Aufruf sofort sicher ist.
- Überschreiben Sie es: geben Sie Ihren eigenen Schlüssel an, wenn Sie dieselbe logische Operation über Prozesse hinweg deduplizieren möchten.
Das empfohlene Muster besteht darin, für jede logische Operation in Ihrem Agenten-Code eine UUID zu generieren (z. B. eine UUID pro "Zahlung an Anbieter X für Bestellung Y") und sie über Wiederholungen hinweg wiederzuverwenden, bis die Operation erfolgreich ist. Die offiziellen SDKs generieren automatisch eine für payments.create, wenn Sie sie nicht angeben.
Lesen Sie Ihr Limit aus der Antwort, nicht aus einer Tabelle.
Grenzen skalieren mit Ihrem Plan. Anstatt Zahlen hart zu kodieren, die abweichen, sagt Ihnen jede Antwort, wo Sie stehen, und die SDKs kümmern sich um das Zurücksetzen für Sie.
Header bei jeder Erfolgsantwort
X-RateLimit-Limit: der feste Satz Ihres PlansX-RateLimit-Remaining: wie viele Anrufe in diesem Fenster verbleibenX-RateLimit-Reset: Unix-Sekunden, wenn das Fenster zurückgesetzt wird
Wenn Sie die Obergrenze erreichen (HTTP 429)
- Antwort beinhaltet
Retry-Afterin Sekunden - Die offiziellen SDKs versuchen es bei 429 und 5xx mit exponentiellem Backoff erneut und beachten Retry-After
- Der größte Teil des Codes behandelt 429 nie manuell, da das SDK dies bereits tut
Spricht x402 fließend. Funktioniert auch ohne.
x402 ist das offene Protokoll für HTTP-native Zahlungen. Die Prämisse: Jede API, die 402 Payment Required zurückgibt, kann Zahlungsanforderungen in der Antwort angeben, und jeder Client, der die Spezifikation versteht, kann zahlen und erneut versuchen - keine Anmeldung, kein API-Schlüssel, keine außerbandliche Verhandlung. Blockchain0x liefert echte x402-Pakete: einen Zahlungskunden und Empfangsserveradapter. Das einzige Schema heute ist exact-usdc, auf Base.
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"version": 1,
"resource": "https://api.example.com/paid-endpoint",
"accepts": [
{ "scheme": "exact-usdc", "network": "eip155:8453" }
]
}Was der Agentenaufrufer tut
- Liest den 402-Body: Version 1, die Resource und ein nicht-leeres accepts[] mit Zahlungsanforderungen (scheme exact-usdc, network eip155:8453 für Base).
- Erstellt eine Zahlung und sendet die Anfrage mit einem X-Payment: exact-usdc:<base64(json)>-Header erneut.
- Auf der Zahlungsseite erledigt `createX402Client({ sdk })` aus `@blockchain0x/x402` das für Sie - es beantwortet 402s automatisch.
- Ihr Server überprüft den X-Payment-Header und führt die ursprüngliche Anfrage aus.
Beide Seiten, echte Pakete
Auf der Zahlungsseite, createX402Client({ sdk }) von @blockchain0x/x402 umschließt fetch und beantwortet 402s automatisch. Auf der Empfangsseite, createX402Plugin (Fastify) und createX402Middleware (Express) gate your own endpoints. Oder überspringen Sie x402 und verwenden Sie die REST API direkt - die beiden ergänzen sich, sodass Sie x402 hinzufügen können, wenn Sie bereit sind.