मुख्य सामग्रीकडे जा
पेमेंट API

AI एजंट कोडसाठी डिझाइन केलेले एक पेमेंट API.

एक लहान REST API. साइन केलेले वेबहुक. पाच भाषांमध्ये अधिकृत SDKs. तुमचा एजंट USDC पाठवू आणि सेटल करू शकेल आणि काही ओळींच्या कोडमध्ये पैसे सत्यापित करू शकेल म्हणून तयार केलेले.

व्यवहार दृश्य: Base वर पुष्टी केलेले येणारे USDC भरणे

Blockchain0x API हेतुपुरस्सर लहान आहे. आम्हाला तुमच्यासाठी तुमचे पहिले देयक करण्यासाठी एक तास दस्तऐवज वाचण्याची इच्छा नाही. आम्हाला तुम्हाला एक स्निपेट कॉपी करायचे आहे, तुमची API की पेस्ट करायची आहे, आणि ते चालवायचे आहे.

मुख्य एंडपॉइंट्स

एक लहान पृष्ठभाग, एजंट कोडसाठी तयार केलेले.

खर्च-आकाराचे मार्ग खाली आहेत. वेबहुक्स, api-की, आणि वाचन-फक्त खर्च-परवानग्या पृष्ठभाग पूर्ण करतात; SDK याला सर्व लपवते.

POST/v1/paymentsएजंट वॉलेटमधून USDC पेमेंट पाठवा
GET/v1/transactions/{id}व्यवहाराची स्थिती आणि हॅश मिळवा
POST/v1/payment-requests/{id}/settleऑन-चेन पुराव्यासह इनव्हॉइस निपटारा
GET/v1/agents/{id}एजंट वॉलेट मिळवा
POST/v1/agentsएजंट वॉलेट तयार करा
शिप केलेले वेबहुक इव्हेंट्स

सर्व HMAC-SHA256 सह स्वाक्षरी केलेले आहेत.

स्वाक्षरी येथे X-Blockchain0x-Signature हेडर. 5 मिनिटांचा पुनरुत्पादन विंडो. प्रत्येक POST वर आयडेम्पोटेंसी की.

payment.received

USDC तुमच्या एका एजंट वॉलेटमध्ये आले.

payment.sent

तुमच्या एजंटकडून एक बाह्य पेमेंट चेनवर निपजले

wallet.deployed

एजंटचा स्मार्ट वॉलेट तैनात करण्यात आला

webhook.test

dashboard मधून तुम्ही सुरू केलेली test delivery

काही ओळी

तुमच्या एजंटच्या वॉलेटमधून USDC पाठवा.

PYTHON
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 network
आधिकारिक SDKs

TypeScript आणि Python साठी प्रकारित क्लायंट.

टाइपस्क्रिप्ट
npm install @blockchain0x/node

Node 18+ सह कार्य करते. स्थानिक TypeScript प्रकार.

PYTHON
pip install blockchain0x

Python 3.9+. सिंक आणि असिंक्रोनस क्लायंट.

पूर्ण API संदर्भ
पूर्ण एंडपॉइंट स्कीम

SDK लपवलेले विनंती शरीर.

प्रत्येक मार्गासाठी हे सत्यापित इनपुट आहेत. प्रतिसाद येथे संक्षिप्त दाखवले आहेत; पूर्ण प्रकारचे आकार SDK आणि API संदर्भात आहेत. रक्कम USDC बेस युनिट्स आहेत (6 दशमलव).

POST/v1/payments

USDC पेमेंट पाठवा (payments.create). amountWei हे USDC बेस युनिट्स (6 दशांश) आहे. चेन अडॅप्टर वायर्ड होईपर्यंत 503 परत येऊ शकते.

विनंती
{
  "agentId": "agt_123",
  "to": "0xRecipient",
  "amountWei": "10000",
  "metadata": { "reason": "Research report" }
}
प्रतिसाद
{
  "txHash": "0xff5...e12"
}
POST/v1/payment-requests/{id}/settle

डॅशबोर्डमध्ये तयार केलेल्या पेमेंट विनंती (इनव्हॉइस) ला निपटारा द्या, ऑन-चेन पुराव्यासह (paymentRequests.settle). तयार करण्याचा मार्ग नाही - फक्त निपटारा.

विनंती
{
  "txHash": "0xff5...e12",
  "payerAddress": "0xBuyer...",
  "amountUsdcVerified": "0.10"
}
प्रतिसाद
{
  "txHash": "0xff5...e12"
}
GET/v1/transactions/{id}

id द्वारे एकल व्यवहार मिळवा (transactions.get).

विनंती
(no body)
प्रतिसाद
{
  "id": "tx_01J9...",
  "txHash": "0xff5...e12"
}
GET/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"
}
GET/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 header (t=<unix>,v1=<hex>) - `${t}.${rawBody}` या स्ट्रिंगवर तुमच्या वेबहुक गुप्तसह HMAC-SHA256, 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");
});
PYTHON (FLASK)
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", 200

Webhook तयार करताना किंवा rotate करताना secret एकदाच परत मिळतो (webhooks.rotateSecret), आणि तुमचा handler तो BLOCKCHAIN0X_WEBHOOK_SECRET मधून वाचतो. Rotate केल्याने जुना secret अवैध होतो, त्यामुळे rollout समन्वयाने करा: server च्या env मध्ये नवीन secret set करा, deploy करा, मग rotate करा. दिलेले events म्हणजे payment.received, payment.sent, wallet.deployed, आणि webhook.test - event type नुसार branch करा, बाकीचे ignore करा.

IDEMPOTENCY

सुरक्षितपणे पुन्हा प्रयत्न करा. API दोनदा पैसे देणार नाही.

एजंट कोड पुन्हा प्रयत्न करतो. नेटवर्क कनेक्शन गमावतात. LLMs साधनाला दोन वेळा कॉल करण्याचा निर्णय घेतात. हे सुरक्षित करण्यासाठी, एक पाठवा Idempotency-Key POST वर हेडर. SDK मधील payments.create तुमच्यासाठी एक स्थिर एक ऑटो-मिंट करते, त्यामुळे पुन्हा केलेल्या कॉलमुळे दोन वेळा पैसे न देता एकच ऑन-चेन सबमिशन होते. प्रक्रिया दरम्यान समान तार्किक ऑपरेशन डेडुप करण्यासाठी तुम्हाला हवे असल्यास तुमच्या स्वतःच्या कीसह ते ओव्हरराईड करा.

BASH
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) आणि ऑपरेशन यशस्वी होईपर्यंत पुनःप्रयत्नांमध्ये त्याचा पुनर्वापर करणे. जर तुम्ही ते निर्दिष्ट केले नाहीत तर अधिकृत SDKs payments.create साठी एक स्वयंचलितपणे तयार करतात.

रेट मर्यादा

तुमची मर्यादा प्रतिसादातून वाचा, टेबलमधून नाही.

तुमच्या योजनेनुसार मर्यादा वाढवा. संख्यांना हार्ड-कोड करण्याऐवजी, प्रत्येक प्रतिसाद तुम्हाला तुमची स्थिती सांगतो आणि SDKs तुमच्यासाठी बॅकऑफ हाताळतात.

प्रत्येक यशस्वी प्रतिसादावर हेडर्स

  • X-RateLimit-Limit: तुमच्या योजनेचा स्थिर दर
  • X-RateLimit-Remaining: या विंडोमध्ये किती कॉल बाकी आहेत
  • X-RateLimit-Reset: विंडो रीसेट झाल्यावर युनिक्स सेकंद

जेव्हा तुम्ही कॅपवर हिट करता (HTTP 429)

  • प्रतिसादामध्ये समाविष्ट आहे Retry-After सेकंदात
  • अधिकृत SDKs 429 आणि 5xx वर पुनःप्रयत्न करतात, एक्स्पोनेंशियल बॅकऑफसह, Retry-After चा आदर करतात
  • अधिकांश कोड कधीही 429 हाताने हाताळत नाही कारण SDK आधीच करते
X402 सुसंगतता

x402 धाराप्रवाह बोलतो. त्याशिवाय काम करतो.

x402 HTTP-नैतिक पेमेंटसाठी ओपन प्रोटोकॉल आहे. पूर्वधारणा: कोणतीही API जी 402 पेमेंट आवश्यक परत करते ती प्रतिसादात भरणा आवश्यकता जाहिर करू शकते, आणि कोणताही क्लायंट जो स्पेक समजतो तो भरणा करू शकतो आणि पुनःप्रयत्न करू शकतो - कोणतीही साइन अप, कोणतीही API की, कोणतीही बाह्य चर्चा नाही. Blockchain0x वास्तविक x402 पॅकेजेस पाठवते: एक पे-साइड क्लायंट आणि रिसीव-साइड सर्व्हर अडॅप्टर्स. आजचा एकटा योजना exact-usdc आहे, बेसवर.

जेव्हा कॉलरने पैसे दिले नाही तेव्हा सर्व्हर 402 परत करतो
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" }
  ]
}

एजंट कॉलर काय करतो

  1. 402 body वाचतो: version 1, resource, आणि payment requirements चा non-empty accepts[] (scheme exact-usdc, Base साठी network eip155:8453).
  2. एक payment तयार करते आणि request ला X-Payment: exact-usdc:<base64(json)> header सह पुन्हा पाठवते.
  3. pay side वर, @blockchain0x/x402 मधील createX402Client({ sdk }) हे तुमच्यासाठी करते - ते 402s ला आपोआप उत्तर देते.
  4. तुमचा server X-Payment header verify करतो आणि मूळ request पूर्ण करतो.

दोन्ही बाजू, वास्तविक पॅकेजेस

पेमेंटच्या बाजूवर, createX402Client({ sdk }) @blockchain0x/x402 fetch ला लपेटतो आणि आपोआप 402s ला उत्तर देतो. प्राप्तीच्या बाजूला, createX402Plugin (Fastify) आणि createX402Middleware (Express) तुमचे स्वतःचे एंडपॉइंट गेट करा. किंवा x402 वगळा आणि थेट REST API वापरा - दोन्ही एकत्रित आहेत, त्यामुळे तुम्ही तयार झाल्यावर x402 जोडू शकता.

वारंवार विचारले जाते

पाच API प्रश्न जे विकासक प्रथम विचारतात.

मी SDK शिवाय API वापरू शकतो का?

होय. SDKs ही standard JSON over HTTPS वरच्या bearer-token auth भोवतीची हलकी wrappers आहेत. जे काही HTTP आणि HMAC-SHA256 बोलू शकते, ते API थेट वापरू शकते. SDKs ergonomic typing, retries, आणि idempotency-key generation साठी आहेत; त्या सोयीच्या आहेत, अनिवार्य नाहीत. आम्ही Node, Python, Ruby, Go, आणि JVM साठी clients देतो; इतर कोणत्याही भाषेत raw API ला call करा.

जर माझा वेबहुक एंडपॉइंट डाउन असेल तर इव्हेंट फायर झाल्यावर काय होते?

डिलिव्हरी बॅकऑफसह पुन्हा प्रयत्न करतात आणि प्रत्येक प्रयत्न डॅशबोर्डमध्ये त्याच्या HTTP प्रतिसाद कोडसह लॉग केला जातो. जर तुम्ही एखादी इव्हेंट चुकवली, तर तुम्ही API कडून समेट करू शकता - GET /v1/transactions/{id} सह आयडीद्वारे व्यवहार मिळवा - फक्त वेबहुकवर अवलंबून न राहता. प्रत्येक डिलिव्हरीची पुष्टी webhooks.verify (किंवा दस्तऐवजीकरण केलेला HMAC) सह करा, त्यावर विश्वास ठेवण्यापूर्वी, आणि 2xx लवकर प्रतिसाद द्या जेणेकरून एक मंद हँडलर अपयशासारखा दिसत नाही.

जर माझा एजंट नेटवर्क त्रुटींवर पुन्हा प्रयत्न करतो तर मी डुप्लिकेट पेमेंट कसे टाळू?

POST वर Idempotency-Key हेडर पाठवा. SDK मध्ये payments.create तुमच्यासाठी एक स्थिर एक ऑटो-मिंट करते, त्यामुळे पुन्हा प्रयत्न केलेला कॉल दोनदा पैसे देण्याऐवजी एकच ऑन-चेन सादरीकरणात संकुचित होतो. प्रक्रियांमध्ये समान तार्किक ऑपरेशन डेडुप करण्यासाठी तुम्ही तुमच्या स्वतःच्या कीसह ते ओव्हरराइड करा. की तुमच्या एजंट किंवा नेटवर्कने उड्डाणाच्या मध्यभागी पुन्हा प्रयत्न केल्यास तंतोतंत त्या प्रकरणासाठी सुरक्षा जाळे आहे.

एक दर मर्यादा आहे का?

हो, आणि ते तुमच्या plan नुसार scale होते. बदलणारी संख्या hard-code करण्याऐवजी response मधून वाचा: प्रत्येक call X-RateLimit-Limit, X-RateLimit-Remaining, आणि X-RateLimit-Reset परत करते, आणि 429 मध्ये Retry-After seconds मध्ये असते. अधिकृत SDKs आधीच 429 आणि 5xx वर exponential backoff सह retry करतात आणि Retry-After पाळतात, त्यामुळे बहुतांश code ला हे हाताने हाताळावे लागत नाही.

हे x402-संगत आहे का?

होय. x402 packages खरी आहेत: @blockchain0x/x402 मधील createX402Client({ sdk }) pay side वर 402 challenges ला उत्तर देतो, आणि createX402Plugin (Fastify) / createX402Middleware (Express) receive side वर तुमची स्वतःची endpoints gate करतात. सध्या एकमेव scheme exact-usdc आहे, आणि wire format हा X-Payment: exact-usdc:<base64(json)> request header असा असतो, 402 विरुद्ध ज्याच्या body मध्ये version 1 आणि accepts[] list जाहिर केली जाते. तुम्ही x402 पूर्णपणे दुर्लक्ष करून REST API थेट देखील वापरू शकता.

तुमचे पहिले पेमेंट शिप करा.

सुरू करण्यासाठी मोफत. API कीपासून तुमच्या पहिल्या USDC हस्तांतरणासाठी काही ओळी.