Uma API de pagamento projetada para código de agente de IA.
Uma pequena API REST. Webhooks assinados. SDKs oficiais em cinco idiomas. Construído para que seu agente possa enviar e liquidar USDC e verificar pagamentos em algumas linhas de código.
A API Blockchain0x é deliberadamente pequena. Não queremos que você leia a documentação por uma hora para fazer seu primeiro pagamento. Queremos que você copie um trecho, cole sua chave de API e execute.
Uma pequena superfície, construída para código de agente.
As rotas de pagamento estão abaixo. Webhooks, chaves de API e permissões de gasto somente leitura completam a superfície; o SDK envolve tudo isso.
/v1/paymentsEnvie um pagamento USDC de uma carteira de agente/v1/transactions/{id}Busque o status e hash de uma transação/v1/payment-requests/{id}/settleLiquidar uma fatura com prova on-chain/v1/agents/{id}Busque uma carteira de agente/v1/agentsCriar uma carteira de agenteTodos assinados com HMAC-SHA256.
Assinatura em X-Blockchain0x-Signature cabeçalho. Janela de repetição de 5 minutos. Chaves de idempotência em cada POST.
payment.receivedUSDC chegou em uma das suas carteiras de agente
payment.sentum pagamento de saída do seu agente foi liquidado na cadeia
wallet.deployeda carteira inteligente de um agente foi implantada
webhook.testuma entrega de teste que você acionou a partir do painel
Envie USDC da carteira do seu 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 networkClientes tipados para TypeScript e Python.
npm install @blockchain0x/nodeFunciona com Node 18+. Tipos nativos de TypeScript.
pip install blockchain0xPython 3.9+. Clientes síncronos e assíncronos.
Os corpos de solicitação que o SDK envolve.
Esses são os inputs verificados para cada rota. As respostas são mostradas de forma resumida aqui; as formas tipadas completas estão no SDK e na referência da API. Os valores são unidades base de USDC (6 casas decimais).
/v1/paymentsEnvie um pagamento USDC (payments.create). amountWei são unidades base de USDC (6 casas decimais). Pode retornar 503 até que o adaptador de cadeia esteja conectado.
{
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000",
"metadata": { "reason": "Research report" }
}{
"txHash": "0xff5...e12"
}/v1/payment-requests/{id}/settleLiquidar um pedido de pagamento (fatura) criado no painel, com prova on-chain (paymentRequests.settle). Não há rota de criação - apenas liquidar.
{
"txHash": "0xff5...e12",
"payerAddress": "0xBuyer...",
"amountUsdcVerified": "0.10"
}{
"txHash": "0xff5...e12"
}/v1/transactions/{id}Busque uma única transação por id (transactions.get).
(no body){
"id": "tx_01J9...",
"txHash": "0xff5...e12"
}/v1/agents/{id}Busque uma carteira de agente (agents.get). Sua página pública está em 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-permissionsLeia as permissões de gasto de um agente. APENAS LEITURA via a API - criação e alterações são apenas no painel.
(no body){
"allowance_wei": "5000000",
"per_tx_wei": "1000000",
"period_seconds": 86400,
"start_at": "2026-05-15T00:00:00Z",
"revoked_at": null
}Sempre verifique a assinatura antes de confiar no payload.
Qualquer um pode POST para sua URL de callback. A assinatura é o que prova que o evento realmente veio de nós.
Cada entrega carrega um X-Blockchain0x-Signature cabeçalho (t=<unix>,v1=<hex>) - um HMAC-SHA256 sobre a string `${t}.${rawBody}` com seu segredo de webhook, dentro de uma janela de replay de 5 minutos. No Node, webhooks.verify de @blockchain0x/node faz isso e retorna uma união discriminada na qual você ramifica. Em outras linguagens, calcule o mesmo HMAC e compare em tempo constante. Leia o corpo RAW, não uma cópia analisada - re-serializar quebra a assinatura.
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", 200O webhook secret é retornado uma única vez quando você cria ou rotaciona o webhook (webhooks.rotateSecret), e é de BLOCKCHAIN0X_WEBHOOK_SECRET que seu handler o lê. Rotacionar invalida o segredo antigo, então coordene o rollout: defina o novo segredo no env do seu servidor, faça o deploy e depois rotacione. Os eventos disponibilizados são payment.received, payment.sent, wallet.deployed e webhook.test - faça branch pelo tipo de evento e ignore o restante.
Tente novamente com segurança. A API não pagará duas vezes.
Tentativas de código do agente. Redes perdem conexões. LLMs decidem chamar a ferramenta duas vezes. Para tornar isso seguro, envie um Idempotency-Key cabeçalho no POST. payments.create no SDK auto-minta um estável para você, então uma chamada reexecutada se colapsa em uma única submissão on-chain em vez de pagar duas vezes. Substitua-o pela sua própria chave quando quiser deduplicar a mesma operação lógica entre processos.
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" }'- Primeira chamada: submete o pagamento, retorna a transação.
- Tente novamente com a mesma chave: colapsa para uma única submissão on-chain em vez de pagar duas vezes.
- O SDK cuida disso: payments.create cria automaticamente uma Idempotency-Key estável, então uma chamada reprocessada é segura desde o início.
- Substitua-o: passe sua própria chave quando quiser deduplicar a mesma operação lógica entre processos.
O padrão recomendado é gerar um UUID por operação lógica no seu código de agente (por exemplo, um UUID por "pagar o fornecedor X pelo pedido Y") e reutilizá-lo em tentativas até que a operação seja bem-sucedida. Os SDKs oficiais geram automaticamente um para payments.create se você não especificá-lo.
Leia seu limite da resposta, não de uma tabela.
Os limites escalam com seu plano. Em vez de codificar números que mudam, cada resposta informa onde você está e os SDKs lidam com o retrocesso para você.
Cabeçalhos em cada resposta de sucesso
X-RateLimit-Limit: a taxa fixa do seu planoX-RateLimit-Remaining: quantas chamadas restam nesta janelaX-RateLimit-Reset: segundos unix quando a janela é redefinida
Quando você atinge o limite (HTTP 429)
- A resposta inclui
Retry-Afterem segundos - Os SDKs oficiais tentam novamente em 429 e 5xx com backoff exponencial, respeitando Retry-After
- A maioria do código nunca lida com 429 manualmente porque o SDK já faz isso.
Fala x402 fluentemente. Funciona sem isso também.
x402 é o protocolo aberto para pagamentos nativos de HTTP. A premissa: qualquer API que retorna 402 Payment Required pode anunciar requisitos de pagamento na resposta, e qualquer cliente que entende a especificação pode pagar e tentar novamente - sem cadastro, sem chave de API, sem negociação fora de banda. Blockchain0x fornece pacotes x402 reais: um cliente do lado do pagamento e adaptadores de servidor do lado do recebimento. O único esquema hoje é exact-usdc, na 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" }
]
}O que o chamador do agente faz
- Lê o corpo do 402: versão 1, o recurso e um accepts[] não vazio de requisitos de pagamento (scheme exact-usdc, network eip155:8453 para Base).
- Cria um pagamento e reenvia a requisição com um cabeçalho X-Payment: exact-usdc:<base64(json)>.
- No lado de pagamento, createX402Client({ sdk }) de @blockchain0x/x402 faz isso por você - ele responde a 402s automaticamente.
- Seu servidor verifica o cabeçalho X-Payment e atende à solicitação original.
Ambos os lados, pacotes reais
Do lado do pagamento, createX402Client({ sdk }) de @blockchain0x/x402 envolve fetch e responde 402s automaticamente. No lado de recebimento, createX402Plugin (Fastify) e createX402Middleware (Express) crie seus próprios endpoints. Ou pule o x402 e use a API REST diretamente - os dois se compõem, então você pode adicionar o x402 quando estiver pronto.