Un'API di pagamento progettata per il codice degli agenti AI.
Una piccola API REST. Webhook firmati. SDK ufficiali in cinque lingue. Costruita affinché il tuo agente possa inviare e regolare USDC e verificare i pagamenti in poche righe di codice.
L'API Blockchain0x è deliberatamente piccola. Non vogliamo che tu legga la documentazione per un'ora per effettuare il tuo primo pagamento. Vogliamo che tu copi uno snippet, incolli la tua chiave API e lo esegua.
Una piccola superficie, costruita per il codice dell'agente.
Le rotte a forma di pagamento sono qui sotto. Webhooks, api-keys e autorizzazioni di spesa in sola lettura completano la superficie; l'SDK avvolge tutto.
/v1/paymentsInvia un pagamento USDC da un wallet dell'agente/v1/transactions/{id}Recupera lo stato e l'hash di una transazione/v1/payment-requests/{id}/settleRegola una fattura con prova on-chain/v1/agents/{id}Recupera un portafoglio agente/v1/agentsCrea un portafoglio agenteTutti firmati con HMAC-SHA256.
Firma in X-Blockchain0x-Signature intestazione. Finestra di riproduzione di 5 minuti. Chiavi di idempotenza su ogni POST.
payment.receivedUSDC è arrivato in uno dei tuoi wallet agenti
payment.sentun pagamento in uscita dal tuo agente si è stabilito sulla catena
wallet.deployedil wallet intelligente di un agente è stato distribuito
webhook.testuna consegna di test che hai attivato dal dashboard
Invia USDC dal wallet del tuo agente.
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 networkClient tipizzati per TypeScript e Python.
npm install @blockchain0x/nodeFunziona con Node 18+. Tipi TypeScript nativi.
pip install blockchain0xPython 3.9+. Client sincronizzati e asincroni.
I corpi delle richieste che l'SDK avvolge.
Questi sono gli input verificati per ogni rotta. Le risposte sono mostrate brevemente qui; le forme tipizzate complete vivono nell'SDK e nella documentazione API. Gli importi sono unità base USDC (6 decimali).
/v1/paymentsInvia un pagamento USDC (payments.create). amountWei è l'unità base USDC (6 decimali). Potrebbe restituire 503 fino a quando l'adattatore della catena non è collegato.
{
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000",
"metadata": { "reason": "Research report" }
}{
"txHash": "0xff5...e12"
}/v1/payment-requests/{id}/settleRegola una richiesta di pagamento (fattura) creata nel dashboard, con prova on-chain (paymentRequests.settle). Non esiste un percorso di creazione - solo regolazione.
{
"txHash": "0xff5...e12",
"payerAddress": "0xBuyer...",
"amountUsdcVerified": "0.10"
}{
"txHash": "0xff5...e12"
}/v1/transactions/{id}Recupera una singola transazione per id (transactions.get).
(no body){
"id": "tx_01J9...",
"txHash": "0xff5...e12"
}/v1/agents/{id}Recupera un portafoglio agente (agents.get). La sua pagina pubblica si trova su 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-permissionsLeggi i permessi di spesa di un agente. SOLO LETTURA tramite l'API - creazione e modifiche sono solo nel dashboard.
(no body){
"allowance_wei": "5000000",
"per_tx_wei": "1000000",
"period_seconds": 86400,
"start_at": "2026-05-15T00:00:00Z",
"revoked_at": null
}Verifica sempre la firma prima di fidarti del payload.
Chiunque può POSTare al tuo URL di callback. La firma è ciò che dimostra che l'evento è effettivamente provenuto da noi.
Ogni consegna porta un X-Blockchain0x-Signature intestazione (t=<unix>,v1=<hex>) - un HMAC-SHA256 sulla stringa `${t}.${rawBody}` con il tuo segreto webhook, all'interno di una finestra di replay di 5 minuti. In Node, webhooks.verify da @blockchain0x/node lo fa e restituisce un'unione discriminata su cui ramificare. In altre lingue, calcola lo stesso HMAC e confronta in tempo costante. Leggi il corpo RAW, non una copia analizzata - la re-serializzazione rompe la firma.
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", 200Il secret del webhook viene restituito una sola volta quando crei o ruoti il webhook (webhooks.rotateSecret), e BLOCKCHAIN0X_WEBHOOK_SECRET è da dove il tuo handler lo legge. La rotazione invalida il secret precedente, quindi coordina il rilascio: imposta il nuovo secret nell'env del server, fai il deploy, poi ruota. Gli eventi inclusi sono payment.received, payment.sent, wallet.deployed e webhook.test - instrada in base al tipo di evento, ignora il resto.
Riprova in sicurezza. L'API non pagherà due volte.
Ritenta il codice dell'agente. Le reti perdono connessioni. Gli LLM decidono di chiamare lo strumento due volte. Per rendere questo sicuro, invia un Idempotency-Key intestazione sul POST. payments.create nell'SDK crea automaticamente uno stabile per te, quindi una chiamata ripetuta si riduce a un'unica sottomissione on-chain invece di pagare due volte. Sovrascrivilo con la tua chiave quando vuoi deduplicare la stessa operazione logica tra i processi.
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" }'- Prima chiamata: invia il pagamento, restituisce la transazione.
- Riprova con la stessa chiave: si riduce a una sola sottomissione on-chain invece di pagare due volte.
- L'SDK gestisce questo: payments.create genera automaticamente una chiave di idempotenza stabile, quindi una chiamata ripetuta è sicura di default.
- Sovrascrivi: passa la tua chiave quando vuoi deduplicare la stessa operazione logica tra processi.
Il pattern raccomandato è generare un UUID per ogni operazione logica nel codice del tuo agente (ad esempio, un UUID per "paga il fornitore X per l'ordine Y") e riutilizzarlo attraverso i tentativi fino a quando l'operazione non ha successo. Gli SDK ufficiali generano automaticamente uno per payments.create se non lo specifichi.
Leggi il tuo limite dalla risposta, non da una tabella.
I limiti si scalano con il tuo piano. Piuttosto che codificare numeri che si discostano, ogni risposta ti dice dove ti trovi e gli SDK gestiscono il backoff per te.
Intestazioni su ogni risposta di successo
X-RateLimit-Limit: il tasso costante del tuo pianoX-RateLimit-Remaining: quante chiamate rimaste in questa finestraX-RateLimit-Reset: secondi unix quando la finestra si resetta
Quando raggiungi il limite (HTTP 429)
- La risposta include
Retry-Afterin secondi - Gli SDK ufficiali riprovano su 429 e 5xx con un backoff esponenziale, rispettando Retry-After
- La maggior parte del codice non gestisce mai il 429 manualmente perché l'SDK lo fa già
Parla x402 fluentemente. Funziona anche senza.
x402 è il protocollo aperto per i pagamenti nativi HTTP. La premessa: qualsiasi API che restituisce 402 Payment Required può pubblicizzare i requisiti di pagamento nella risposta, e qualsiasi client che comprende la specifica può pagare e ripetere - nessuna registrazione, nessuna chiave API, nessuna negoziazione fuori banda. Blockchain0x fornisce pacchetti x402 reali: un client lato pagamento e adattatori server lato ricezione. L'unico schema oggi è exact-usdc, su 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" }
]
}Cosa fa il chiamante dell'agente
- Legge il body 402: versione 1, la risorsa e un accepts[] non vuoto di requisiti di pagamento (scheme exact-usdc, network eip155:8453 per Base).
- Crea un pagamento e reinvia la richiesta con un header X-Payment: exact-usdc:<base64(json)>.
- Sul lato pagamenti, createX402Client({ sdk }) di @blockchain0x/x402 fa questo per te - risponde automaticamente ai 402.
- Il tuo server verifica l'header X-Payment ed esegue la richiesta originale.
Entrambi i lati, pacchetti reali
Sul lato pagamento, createX402Client({ sdk }) da @blockchain0x/x402 avvolge fetch e risponde automaticamente ai 402. Dalla parte di ricezione, createX402Plugin (Fastify) e createX402Middleware (Express) crea i tuoi endpoint. Oppure salta x402 e usa direttamente l'API REST - i due si compongono, quindi puoi aggiungere x402 quando sei pronto.