AI ajan kodu için tasarlanmış bir ödeme API'si.
Küçük bir REST API'si. İmzalı webhooklar. Beş dilde resmi SDK'lar. Ajanınızın USDC gönderebilmesi, ödemeleri yerleştirebilmesi ve birkaç satır kodda doğrulayabilmesi için inşa edilmiştir.
Blockchain0x API'si kasıtlı olarak küçüktür. İlk ödemenizi yapmak için bir saat boyunca belge okumanızı istemiyoruz. Bir kod parçasını kopyalamanızı, API anahtarınızı yapıştırmanızı ve çalıştırmanızı istiyoruz.
Ajan kodu için inşa edilmiş küçük bir yüzey.
Ödeme biçimindeki rotalar aşağıdadır. Webhook'lar, api anahtarları ve yalnızca okunabilir harcama izinleri yüzeyi tamamlar; SDK bunların hepsini sarar.
/v1/paymentsBir ajan cüzdanından USDC ödemesi gönderin/v1/transactions/{id}Bir işlemin durumunu ve hash'ini alın/v1/payment-requests/{id}/settleZincir üzerindeki kanıtla bir faturayı kesin/v1/agents/{id}Bir ajan cüzdanını alın/v1/agentsBir ajan cüzdanı oluşturTüm HMAC-SHA256 ile imzalanmıştır.
İmza içinde X-Blockchain0x-Signature başlığı. Tekrar oynatma penceresi 5 dakikadır. Her POST'ta idempotency anahtarları.
payment.receivedUSDC, ajans cüzdanlarınızdan birine geldi
payment.sentagent'ınızdan çıkan bir ödeme zincirde settle oldu
wallet.deployedbir agent'ın smart wallet'ı deploy edildi
webhook.testdashboard'dan tetiklediğiniz bir test teslimatı
Ajanınızın cüzdanından USDC gönderin.
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 networkTypeScript ve Python için tipli istemciler.
npm install @blockchain0x/nodeNode 18+ ile çalışır. Yerel TypeScript türleri.
pip install blockchain0xPython 3.9+. Senkron ve asenkron istemciler.
SDK'nın sardığı istek gövdeleri.
Bunlar her rota için doğrulanmış girdilerdir. Yanıtlar burada kısa gösterilmektedir; tam tipli şekiller SDK'da ve API referansında yer alır. Miktarlar USDC temel birimleridir (6 ondalık).
/v1/paymentsBir USDC ödemesi gönderin (payments.create). amountWei, USDC temel birimleridir (6 ondalık). Zincir adaptörü bağlanana kadar 503 dönebilir.
{
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000",
"metadata": { "reason": "Research report" }
}{
"txHash": "0xff5...e12"
}/v1/payment-requests/{id}/settleGösterge panelinde oluşturulan bir ödeme talebini (fatura) zincir üzerindeki kanıtla (paymentRequests.settle) kesin. Oluşturma yolu yoktur - sadece kesin.
{
"txHash": "0xff5...e12",
"payerAddress": "0xBuyer...",
"amountUsdcVerified": "0.10"
}{
"txHash": "0xff5...e12"
}/v1/transactions/{id}Bir işlemi id ile alın (transactions.get).
(no body){
"id": "tx_01J9...",
"txHash": "0xff5...e12"
}/v1/agents/{id}Bir ajan cüzdanını alın (agents.get). Kamu sayfası wallet.blockchain0x.com/a/{slug} adresindedir.
(no body){
"id": "agt_01J9QKE...",
"name": "research-bot",
"public_url": "https://wallet.blockchain0x.com/a/research-bot"
}/v1/agents/{id}/spend-permissionsBir ajanın harcama izinlerini okuyun. API üzerinden OKUMA-ONLY - oluşturma ve değişiklikler yalnızca kontrol panelindedir.
(no body){
"allowance_wei": "5000000",
"per_tx_wei": "1000000",
"period_seconds": 86400,
"start_at": "2026-05-15T00:00:00Z",
"revoked_at": null
}Yükü güvenmeden önce her zaman imzayı doğrulayın.
Herkes geri çağırma URL'nize POST yapabilir. İmza, olayın gerçekten bizden geldiğini kanıtlar.
Her teslimat bir X-Blockchain0x-Signature header (t=<unix>,v1=<hex>) - `${t}.${rawBody}` dizesi üzerinde webhook gizlinizle HMAC-SHA256. 5 dakikalık tekrar penceresi içinde. Node'da, @blockchain0x/node'dan webhooks.verify bunu yapar ve dallanabileceğiniz ayrıştırılmış bir birleşim döner. Diğer dillerde, aynı HMAC'yi hesaplayın ve sabit zaman içinde karşılaştırın. RAW gövdeyi okuyun, ayrıştırılmış bir kopyayı değil - yeniden seri hale getirme imzayı bozar.
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", 200Webhook secret, webhook'u oluşturduğunuzda veya döndürdüğünüzde (webhooks.rotateSecret) bir kez geri döndürülür ve handler'ınız bunu BLOCKCHAIN0X_WEBHOOK_SECRET üzerinden okur. Döndürme işlemi eski secret'ı geçersiz kılar, bu yüzden rollout'u koordine edin: yeni secret'ı server'ın env'ine ekleyin, deploy edin, sonra rotate edin. Sunulan event'ler payment.received, payment.sent, wallet.deployed ve webhook.test'tir - event type'a göre dallanın, geri kalanını yok sayın.
Güvenli bir şekilde yeniden deneyin. API iki kez ödeme yapmayacaktır.
Ajan kodu yeniden denemeleri. Ağlar bağlantıları kesiyor. LLM'ler aracı iki kez çağırmaya karar veriyor. Bunu güvenli hale getirmek için bir Idempotency-Key POST üzerindeki başlık. SDK'daki payments.create sizin için otomatik olarak kararlı bir tane oluşturur, böylece tekrar edilen bir çağrı, iki kez ödeme yapmak yerine tek bir zincir üzerindeki gönderime düşer. Aynı mantıksal işlemi süreçler arasında dedupe etmek istediğinizde kendi anahtarınızla geçersiz kılın.
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" }'- İlk çağrı: ödemeyi gönderir, işlemi döndürür.
- Aynı anahtarla yeniden deneyin: iki kez ödeme yapmak yerine tek bir on-chain submission'a dönüşür.
- SDK bunu halleder: payments.create otomatik olarak sabit bir Idempotency-Key üretir, bu nedenle yeniden denenen çağrı varsayılan olarak güvenlidir.
- Bunu geçersiz kıl: aynı mantıksal işlemi süreçler arasında deduplikasyonla tekilleştirmek istediğinizde kendi anahtarınızı iletin.
Tavsiye edilen desen, ajans kodunuzda her mantıksal işlem için bir UUID oluşturmaktır (örneğin, "X tedarikçisine Y siparişi için ödeme yap" başına bir UUID) ve işlem başarılı olana kadar yeniden denemelerde bunu yeniden kullanmaktır. Resmi SDK'lar, bunu belirtmezseniz payments.create için otomatik olarak bir tane oluşturur.
Limitinizi yanıttan okuyun, bir tablodan değil.
Limitler, planınızla birlikte ölçeklenir. Kaymalar olan sayıları sert kodlamak yerine, her yanıt size nerede olduğunuzu söyler ve SDK'lar geri çekilmeyi sizin için halleder.
Her başarılı yanıtta başlıklar
X-RateLimit-Limit: planınızın sabit oranıX-RateLimit-Remaining: bu pencerede ne kadar çağrı kaldıX-RateLimit-Reset: pencere sıfırlandığında unix saniyeleri
Kapağı vurduğunuzda (HTTP 429)
- Yanıt şunları içerir:
Retry-Aftersaniye içinde - Resmi SDK'lar, 429 ve 5xx durum kodlarında, Retry-After'ı dikkate alarak üstel geri çekilme ile yeniden dener.
- Çoğu kod, SDK zaten yaptığı için 429'u elle işlemez
x402'yi akıcı bir şekilde konuşur. Onun olmadan da çalışır.
x402, HTTP yerel ödemeleri için açık bir protokoldür. Premis: 402 Ödeme Gereklidir döndüren herhangi bir API, yanıtta ödeme gereksinimlerini duyurabilir ve spesifikasyonu anlayan herhangi bir istemci ödeme yapabilir ve yeniden deneyebilir - kayıt yok, API anahtarı yok, dış müzakere yok. Blockchain0x, gerçek x402 paketleri gönderir: bir ödeme tarafı istemcisi ve alma tarafı sunucu adaptörleri. Bugün tek şema, Base'de exact-usdc'dir.
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" }
]
}Ajan çağrıcısı ne yapar
- 402 gövdesini okur: version 1, resource ve payment requirements için boş olmayan bir accepts[] (scheme exact-usdc, Base için network eip155:8453).
- Bir ödeme oluşturur ve isteği X-Payment: exact-usdc:<base64(json)> başlığıyla yeniden gönderir.
- Ödeme tarafında, @blockchain0x/x402 içindeki createX402Client({ sdk }) bunu sizin için yapar - 402'lere otomatik yanıt verir.
- Sunucunuz X-Payment başlığını doğrular ve orijinal isteği yerine getirir.
Her iki taraf, gerçek paketler
Ödeme tarafında, createX402Client({ sdk }) from @blockchain0x/x402 fetch'i sarar ve otomatik olarak 402'lere yanıt verir. Alım tarafında, createX402Plugin (Fastify) ve createX402Middleware (Express) kendi uç noktalarınızı oluşturun. Ya da x402'yi atlayın ve REST API'yi doğrudan kullanın - ikisi bir araya gelir, bu yüzden hazır olduğunuzda x402'yi ekleyebilirsiniz.