Een betalings-API ontworpen voor AI-agentcode.
Een kleine REST API. Ondertekende webhooks. Officiële SDKs in vijf talen. Gebouwd zodat jouw agent USDC kan verzenden en verrekenen en betalingen kan verifiëren in een paar regels code.
De Blockchain0x API is opzettelijk klein. We willen niet dat je een uur documentatie leest om je eerste betaling te doen. We willen dat je een snippet kopieert, je API-sleutel plakt en het uitvoert.
Een klein oppervlak, gebouwd voor agentcode.
De betaling-vormige routes zijn hieronder. Webhooks, api-sleutels, en alleen-lezen uitgaven-permissies ronden het oppervlak af; de SDK wikkelt alles in.
/v1/paymentsStuur een USDC-betaling vanuit een agent wallet/v1/transactions/{id}Haal de status en hash van een transactie op/v1/payment-requests/{id}/settleVerwerk een factuur met on-chain bewijs/v1/agents/{id}Haal een agent wallet op/v1/agentsMaak een agent wallet aanAlle ondertekend met HMAC-SHA256.
Handtekening in de X-Blockchain0x-Signature header. Replay-venster van 5 minuten. Idempotentie-sleutels bij elke POST.
payment.receivedUSDC is aangekomen in een van je agent wallets
payment.senteen uitgaande betaling van je agent werd op de keten afgehandeld
wallet.deployedde slimme portemonnee van een agent werd ingezet
webhook.testeen testlevering die je vanuit het dashboard hebt geactiveerd
Stuur USDC vanuit de wallet van je agent.
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 networkTyped clients voor TypeScript en Python.
npm install @blockchain0x/nodeWerkt met Node 18+. Native TypeScript-typen.
pip install blockchain0xPython 3.9+. Sync en async clients.
De aanvraaglichamen die de SDK wikkelt.
Dit zijn de geverifieerde invoerwaarden voor elke route. Antwoorden worden hier kort weergegeven; de volledige getypte vormen bevinden zich in de SDK en de API-referentie. Bedragen zijn USDC basis eenheden (6 decimalen).
/v1/paymentsStuur een USDC-betaling (payments.create). amountWei is USDC basis eenheden (6 decimalen). Kan 503 retourneren totdat de chain adapter is aangesloten.
{
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000",
"metadata": { "reason": "Research report" }
}{
"txHash": "0xff5...e12"
}/v1/payment-requests/{id}/settleVerwerk een betalingsverzoek (factuur) dat in het dashboard is aangemaakt, met on-chain bewijs (paymentRequests.settle). Er is geen aanmaakroute - alleen afhandelen.
{
"txHash": "0xff5...e12",
"payerAddress": "0xBuyer...",
"amountUsdcVerified": "0.10"
}{
"txHash": "0xff5...e12"
}/v1/transactions/{id}Haal een enkele transactie op op id (transactions.get).
(no body){
"id": "tx_01J9...",
"txHash": "0xff5...e12"
}/v1/agents/{id}Haal een agent wallet op (agents.get). De openbare pagina bevindt zich op 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-permissionsLees de uitgavenrechten van een agent. LEES-ALEN via de API - creatie en wijzigingen zijn alleen via het dashboard.
(no body){
"allowance_wei": "5000000",
"per_tx_wei": "1000000",
"period_seconds": 86400,
"start_at": "2026-05-15T00:00:00Z",
"revoked_at": null
}Verifieer altijd de handtekening voordat je de payload vertrouwt.
Iedereen kan POST naar je callback-URL. De handtekening is wat bewijst dat de gebeurtenis daadwerkelijk van ons afkomstig is.
Elke levering bevat een X-Blockchain0x-Signature header (t=<unix>,v1=<hex>) - een HMAC-SHA256 over de string `${t}.${rawBody}` met je webhook geheim, binnen een replayvenster van 5 minuten. In Node doet webhooks.verify van @blockchain0x/node dit en retourneert een gediscrimineerde unie waar je op takken. In andere talen, bereken dezelfde HMAC en vergelijk in constante tijd. Lees de RAW body, niet een geparsed exemplaar - opnieuw serialiseren breekt de handtekening.
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", 200De webhook secret wordt één keer teruggegeven wanneer je de webhook aanmaakt of roteert (webhooks.rotateSecret), en BLOCKCHAIN0X_WEBHOOK_SECRET is waar je handler hem leest. Roterende wijziging maakt de oude secret ongeldig, dus coördineer de uitrol: zet de nieuwe secret in de env van je server, deploy, en roteer daarna. De meegeleverde events zijn payment.received, payment.sent, wallet.deployed en webhook.test - branch op het event type en negeer de rest.
Probeer het opnieuw op een veilige manier. De API zal niet twee keer betalen.
Agentcode herhalingen. Netwerken vallen verbindingen weg. LLM's besluiten om de tool twee keer aan te roepen. Om dit veilig te maken, stuur een Idempotency-Key header op de POST. payments.create in de SDK mint automatisch een stabiele voor jou, zodat een herhaalde oproep samenvalt met een enkele on-chain indiening in plaats van twee keer te betalen. Overschrijf het met je eigen sleutel wanneer je dezelfde logische operatie over processen wilt dedupliceren.
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" }'- Eerste oproep: dient de betaling in, retourneert de transactie.
- Probeer opnieuw met dezelfde sleutel: samenvoegen tot één on-chain indiening in plaats van twee keer te betalen.
- De SDK regelt het: payments.create auto-mints een stabiele Idempotency-Key, zodat een herhaalde oproep veilig is uit de doos.
- Overschrijf het: geef je eigen sleutel door wanneer je dezelfde logische bewerking over processen wilt dedupliceren.
Het aanbevolen patroon is om een UUID per logische operatie in jouw agentcode te genereren (bijv. één UUID per "betaal leverancier X voor bestelling Y") en deze opnieuw te gebruiken bij herhalingen totdat de operatie slaagt. De officiële SDK's genereren er automatisch één voor payments.create als je deze niet opgeeft.
Lees je limiet van de reactie, niet van een tabel.
Limieten schalen met uw plan. In plaats van getallen hard te coderen die afdrijven, vertelt elke reactie u waar u staat en de SDK's regelen de terugval voor u.
Headers op elke succesvolle reactie
X-RateLimit-Limit: de constante prijs van uw planX-RateLimit-Remaining: hoeveel oproepen zijn er nog over in dit vensterX-RateLimit-Reset: unix-seconden wanneer het venster reset
Wanneer je de limiet bereikt (HTTP 429)
- Respons bevat
Retry-Afterin seconden - De officiële SDK's proberen opnieuw bij 429 en 5xx met exponentiële terugval, met inachtneming van Retry-After
- De meeste code behandelt 429 nooit handmatig omdat de SDK dat al doet
Spreekt x402 vloeiend. Werkt ook zonder.
x402 is het open protocol voor HTTP-native betalingen. De premisse: elke API die 402 Payment Required retourneert, kan betalingsvereisten in de respons adverteren, en elke client die de specificatie begrijpt, kan betalen en opnieuw proberen - geen aanmelding, geen API-sleutel, geen onderhandelingen buiten de band. Blockchain0x levert echte x402-pakketten: een betaalzijde client en ontvangzijde server adapters. Het enige schema vandaag is exact-usdc, op 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" }
]
}Wat de agentaanroeper doet
- Leest de 402-body: versie 1, de resource en een niet-lege accepts[] met betalingsvereisten (scheme exact-usdc, network eip155:8453 voor Base).
- Maakt een betaling aan en verstuurt de request opnieuw met een X-Payment: exact-usdc:<base64(json)> header.
- Aan de betaalzijde doet createX402Client({ sdk }) uit @blockchain0x/x402 dit voor u - het beantwoordt 402's automatisch.
- Je server verifieert de X-Payment-header en voert de oorspronkelijke aanvraag uit.
Beide zijden, echte pakketten
Aan de betaalzijde, createX402Client({ sdk }) van @blockchain0x/x402 verpakt fetch en beantwoordt automatisch 402s. Aan de ontvangkant, createX402Plugin (Fastify) en createX402Middleware (Express) maak je eigen eindpunten. Of sla x402 over en gebruik de REST API direct - de twee kunnen gecombineerd worden, zodat je x402 kunt toevoegen wanneer je er klaar voor bent.