AI एजेंट कोड के लिए डिज़ाइन किया गया एक भुगतान API।
एक छोटा REST API। साइन किए गए वेबहुक। पांच भाषाओं में आधिकारिक SDKs। बनाया गया ताकि आपका एजेंट USDC भेज सके और सेटल कर सके और कुछ पंक्तियों के कोड में भुगतान सत्यापित कर सके।
Blockchain0x API जानबूझकर छोटी है। हम नहीं चाहते कि आप अपना पहला भुगतान करने के लिए एक घंटे तक दस्तावेज़ पढ़ें। हम चाहते हैं कि आप एक स्निपेट कॉपी करें, अपनी API कुंजी पेस्ट करें, और इसे चलाएँ।
एक छोटा सतह, एजेंट कोड के लिए बनाया गया।
भुगतान-आकार के मार्ग नीचे हैं। वेबहुक, api-keys, और केवल-पढ़ने योग्य व्यय-अनुमतियाँ सतह को पूरा करती हैं; SDK इसका सभी लपेटता है।
/v1/paymentsएक एजेंट वॉलेट से USDC भुगतान भेजें/v1/transactions/{id}एक लेनदेन की स्थिति और हैश लाएँ/v1/payment-requests/{id}/settleऑन-चेन प्रमाण के साथ एक चालान का निपटान करें/v1/agents/{id}एक एजेंट वॉलेट लाएँ/v1/agentsएजेंट वॉलेट बनाएंसभी HMAC-SHA256 के साथ हस्ताक्षरित हैं।
हस्ताक्षर में X-Blockchain0x-Signature हेडर। 5 मिनट की पुनःप्रसारण विंडो। हर POST पर Idempotency कुंजी।
payment.receivedUSDC आपके एक एजेंट वॉलेट में पहुँच गया
payment.sentआपके एजेंट से एक आउटबाउंड भुगतान चेन पर निपट गया
wallet.deployedएक एजेंट का स्मार्ट वॉलेट तैनात किया गया था
webhook.testएक परीक्षण डिलीवरी जिसे आपने डैशबोर्ड से सक्रिय किया
अपने एजेंट के वॉलेट से USDC भेजें।
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 और Python के लिए टाइप किए गए क्लाइंट।
npm install @blockchain0x/nodeNode 18+ के साथ काम करता है। स्वदेशी TypeScript प्रकार।
pip install blockchain0xPython 3.9+. समकालिक और असमकालिक ग्राहक।
अनुरोध निकाय जिन्हें SDK लपेटता है।
ये प्रत्येक मार्ग के लिए सत्यापित इनपुट हैं। प्रतिक्रियाएँ यहाँ संक्षिप्त में दिखाई गई हैं; पूर्ण टाइप किए गए आकार SDK और API संदर्भ में रहते हैं। राशि USDC बेस यूनिट (6 दशमलव) हैं।
/v1/paymentsएक USDC भुगतान भेजें (payments.create)। amountWei USDC मूल इकाइयाँ हैं (6 दशमलव)। चेन एडेप्टर के वायर होने तक 503 का उत्तर दे सकता है।
{
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000",
"metadata": { "reason": "Research report" }
}{
"txHash": "0xff5...e12"
}/v1/payment-requests/{id}/settleडैशबोर्ड में बनाई गई एक भुगतान अनुरोध (चालान) को निपटाएं, ऑन-चेन प्रमाण (paymentRequests.settle) के साथ। कोई निर्माण मार्ग नहीं है - केवल निपटान।
{
"txHash": "0xff5...e12",
"payerAddress": "0xBuyer...",
"amountUsdcVerified": "0.10"
}{
"txHash": "0xff5...e12"
}/v1/transactions/{id}आईडी द्वारा एकल लेनदेन लाएँ (transactions.get)।
(no body){
"id": "tx_01J9...",
"txHash": "0xff5...e12"
}/v1/agents/{id}एक एजेंट वॉलेट लाएँ (agents.get)। इसका सार्वजनिक पृष्ठ 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-permissionsएक एजेंट के खर्च अनुमतियों को पढ़ें। API के माध्यम से केवल पढ़ने के लिए - निर्माण और परिवर्तन केवल डैशबोर्ड पर हैं।
(no body){
"allowance_wei": "5000000",
"per_tx_wei": "1000000",
"period_seconds": 86400,
"start_at": "2026-05-15T00:00:00Z",
"revoked_at": null
}हमेशा पेलोड पर भरोसा करने से पहले हस्ताक्षर की पुष्टि करें।
कोई भी आपके कॉलबैक URL पर POST कर सकता है। हस्ताक्षर यह साबित करता है कि घटना वास्तव में हमसे आई थी।
हर डिलीवरी में एक X-Blockchain0x-Signature हेडर (t=<unix>,v1=<hex>) - एक HMAC-SHA256 स्ट्रिंग `${t}.${rawBody}` पर आपके वेबहुक सीक्रेट के साथ, 5-मिनट के पुनःप्रसारण विंडो के भीतर। Node में, @blockchain0x/node से webhooks.verify इसे करता है और एक विभेदित संघ लौटाता है जिस पर आप शाखा करते हैं। अन्य भाषाओं में, वही HMAC की गणना करें और स्थायी समय में तुलना करें। RAW बॉडी पढ़ें, न कि एक पार्स की गई प्रति - पुनः-सीरियलाइजिंग सिग्नेचर को तोड़ देती है।
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 create या rotate करते हैं (webhooks.rotateSecret), और आपका handler इसे BLOCKCHAIN0X_WEBHOOK_SECRET से पढ़ता है। rotate करने पर पुराना secret invalid हो जाता है, इसलिए rollout को coordinate करें: अपने server के env में नया secret सेट करें, deploy करें, फिर rotate करें। shipped events payment.received, payment.sent, wallet.deployed, और webhook.test हैं - event type पर branch करें, बाकी को ignore करें।
सुरक्षित रूप से पुनः प्रयास करें। API दो बार भुगतान नहीं करेगा।
एजेंट कोड पुनः प्रयास करता है। नेटवर्क कनेक्शन छोड़ देते हैं। LLMs उपकरण को दो बार कॉल करने का निर्णय लेते हैं। इसे सुरक्षित बनाने के लिए, भेजें एक Idempotency-Key POST पर हेडर। SDK में payments.create आपके लिए एक स्थिर को स्वचालित रूप से मिंट करता है, इसलिए एक पुनः प्रयास किया गया कॉल एक ही ऑन-चेन सबमिशन में समाहित हो जाता है बजाय इसके कि दो बार भुगतान किया जाए। जब आप प्रक्रियाओं के बीच एक ही तार्किक ऑपरेशन को डेडुप्लिकेट करना चाहते हैं तो इसे अपनी खुद की कुंजी से ओवरराइड करें।
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" }'- पहली कॉल: भुगतान प्रस्तुत करता है, लेनदेन लौटाता है।
- समान कुंजी के साथ पुनः प्रयास करें: दो बार भुगतान करने के बजाय एक ऑन-चेन सबमिशन में समाहित होता है।
- SDK इसे संभालता है: payments.create एक स्थिर Idempotency-Key को स्वचालित रूप से बनाता है, इसलिए एक पुनः प्रयास किया गया कॉल बॉक्स से बाहर सुरक्षित है।
- इसे ओवरराइड करें: जब आप प्रक्रियाओं के बीच एक ही तार्किक ऑपरेशन को डिडुप्लिकेट करना चाहते हैं, तो अपनी कुंजी पास करें।
अनुशंसित पैटर्न यह है कि आपके एजेंट कोड में प्रत्येक तार्किक संचालन के लिए एक UUID उत्पन्न करें (जैसे, "आदेश Y के लिए विक्रेता X को भुगतान करें" के लिए एक UUID) और इसे पुनः प्रयासों में पुन: उपयोग करें जब तक संचालन सफल न हो। यदि आप इसे निर्दिष्ट नहीं करते हैं तो आधिकारिक SDK भुगतान.create के लिए एक स्वचालित रूप से उत्पन्न करता है।
अपनी सीमा को प्रतिक्रिया से पढ़ें, तालिका से नहीं।
सीमाएँ आपके योजना के साथ स्केल करती हैं। संख्या को हार्ड-कोड करने के बजाय जो भटकती हैं, हर प्रतिक्रिया आपको बताती है कि आप कहां खड़े हैं और SDKs आपके लिए बैकऑफ संभालते हैं।
हर सफलता प्रतिक्रिया पर हेडर
X-RateLimit-Limit: आपकी योजना की स्थिर दरX-RateLimit-Remaining: इस विंडो में कितनी कॉल बची हैंX-RateLimit-Reset: जब विंडो रीसेट होती है तो यूनिक्स सेकंड
जब आप कैप पर पहुँचते हैं (HTTP 429)
- प्रतिक्रिया में शामिल है
Retry-Afterसेकंड में - आधिकारिक SDK 429 और 5xx पर पुनः प्रयास करते हैं जिसमें वृद्धि की गई बैकऑफ होती है, Retry-After का सम्मान करते हैं
- अधिकांश कोड 429 को हाथ से नहीं संभालता क्योंकि SDK पहले से ही ऐसा करता है
x402 धाराप्रवाह बोलता है। इसके बिना भी काम करता है।
x402 HTTP-देशी भुगतानों के लिए खुला प्रोटोकॉल है। परिकल्पना: कोई भी API जो 402 भुगतान आवश्यक लौटाता है, प्रतिक्रिया में भुगतान आवश्यकताओं का विज्ञापन कर सकता है, और कोई भी क्लाइंट जो विनिर्देश को समझता है, वह भुगतान कर सकता है और पुनः प्रयास कर सकता है - कोई साइनअप नहीं, कोई API कुंजी नहीं, कोई आउट-ऑफ-बैंड बातचीत नहीं। Blockchain0x वास्तविक x402 पैकेज भेजता है: एक भुगतान-पक्ष क्लाइंट और प्राप्त-पक्ष सर्वर एडेप्टर। आज का एकमात्र स्कीम exact-usdc है, जो 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" }
]
}एजेंट कॉलर क्या करता है
- 402 body पढ़ता है: version 1, resource, और payment requirements का non-empty accepts[] (scheme exact-usdc, Base के लिए network eip155:8453)।
- एक payment बनाता है और request को X-Payment: exact-usdc:<base64(json)> header के साथ दोबारा भेजता है।
- Pay side पर, @blockchain0x/x402 से createX402Client({ sdk }) यह आपके लिए करता है - यह 402s का अपने आप जवाब देता है।
- आपका server X-Payment header verify करता है और original request पूरा करता है.
दोनों पक्ष, असली पैकेज
भुगतान पक्ष पर, createX402Client({ sdk }) @blockchain0x/x402 से फेच को लपेटता है और स्वचालित रूप से 402s का उत्तर देता है। प्राप्त पक्ष पर, createX402Plugin (Fastify) और createX402Middleware (Express) अपने खुद के एंडपॉइंट्स को गेट करें। या x402 को छोड़ दें और सीधे REST API का उपयोग करें - दोनों एक साथ काम करते हैं, इसलिए आप जब तैयार हों तो x402 जोड़ सकते हैं।