ప్రధాన కంటెంట్‌కు దాటవేయండి
చెల్లింపు API

AI ఏజెంట్ కోడ్ కోసం రూపొందించిన చెల్లింపు API.

ఒక చిన్న REST API. సంతకం చేయబడిన వెబ్‌హుక్‌లు. ఐదు భాషలలో అధికారిక SDKలు. మీ ఏజెంట్ USDCను పంపించడానికి మరియు సర్దుబాటు చేయడానికి మరియు కొన్ని కోడ్ పంక్తుల్లో చెల్లింపులను నిర్ధారించడానికి నిర్మించబడింది.

లావాదేవీలు వీక్షణ: Baseలో నిర్ధారించబడిన వచ్చిన USDC చెల్లింపులు

Blockchain0x API ఉద్దేశపూర్వకంగా చిన్నది. మీ మొదటి చెల్లింపు చేయడానికి మీరు ఒక గంట పాటు డాక్యుమెంటేషన్ చదవాలని మేము కోరడం లేదు. మీరు ఒక కోడ్‌ను కాపీ చేసి, మీ API కీని పేస్ట్ చేసి, దాన్ని నడపాలని మేము కోరుకుంటున్నాము.

CORE ENDPOINTS

ఏజెంట్ కోడ్ కోసం నిర్మించబడిన ఒక చిన్న ఉపరితల.

payment-shaped routes కింద ఉన్నాయి. Webhooks, api-keys, మరియు read-only spend-permissions ఈ surface ను పూర్తి చేస్తాయి; SDK ఇవన్నీ wrap చేస్తుంది.

POST/v1/paymentsఏజెంట్ వాలెట్ నుండి USDC చెల్లింపును పంపండి
GET/v1/transactions/{id}ఒక లావాదేవీ యొక్క స్థితి మరియు హాష్‌ను పొందండి
POST/v1/payment-requests/{id}/settleచైన్‌పై సాక్ష్యంతో ఒక ఇన్వాయిస్‌ను కుదించండి
GET/v1/agents/{id}ఒక ఏజెంట్ వాలెట్‌ను పొందండి
POST/v1/agentsఏజెంట్ వాలెట్‌ను సృష్టించండి
SHIPPED WEBHOOK EVENTS

అన్నీ HMAC-SHA256తో సంతకం చేయబడ్డాయి.

సంతకం లో X-Blockchain0x-Signature హెడ్డర్. 5 నిమిషాల రీప్లే విండో. ప్రతి POSTలో Idempotency కీలు.

payment.received

USDC మీ ఏజెంట్ వాలెట్‌లలో ఒకదానిలో చేరింది

payment.sent

మీ ఏజెంట్ నుండి ఒక అవుట్‌బౌండ్ చెల్లింపు చైన్‌పై స్థిరమైనది

wallet.deployed

ఒక ఏజెంట్ యొక్క స్మార్ట్ వాలెట్ అమలు చేయబడింది

webhook.test

మీరు డాష్‌బోర్డులో ప్రారంభించిన ఒక పరీక్ష డెలివరీ

కొన్ని పంక్తులు

మీ ఏజెంట్ యొక్క వాలెట్ నుండి 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
అధికారిక SDKలు

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}

ఐడీ ద్వారా ఒకే లావాదేవీని పొందండి (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
}
వెబ్‌హుక్ సంతకం నిర్ధారణ

పేగును నమ్మకానికి ముందు సంతకాన్ని ఎల్లప్పుడూ ధృవీకరించండి.

ఎవరైనా మీ కallback URLకి POST చేయవచ్చు. ఈ సంతకం ఈ సంఘటన నిజంగా మాకు వచ్చినదని నిరూపిస్తుంది.

ప్రతి డెలివరీకి ఒక X-Blockchain0x-Signature హెడ్డర్ (t=<unix>,v1=<hex>) - మీ వెబ్‌హుక్ సీక్రెట్‌తో `${t}.${rawBody}` స్ట్రింగ్‌పై HMAC-SHA256, 5 నిమిషాల రీప్లే విండోలో. నోడ్‌లో, @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 ను create లేదా rotate చేసినప్పుడు webhook secret ఒక్కసారి మాత్రమే తిరిగి వస్తుంది (webhooks.rotateSecret), మరియు మీ handler దానిని BLOCKCHAIN0X_WEBHOOK_SECRET నుండి చదువుతుంది. rotate చేయడం పాత secret ను invalid చేస్తుంది, కాబట్టి rollout ను సమన్వయం చేయండి: కొత్త secret ను మీ server env లో set చేయండి, deploy చేయండి, ఆపై rotate చేయండి. పంపబడే events ఇవి payment.received, payment.sent, wallet.deployed, మరియు webhook.test - event type ఆధారంగా branch చేయండి, మిగతావన్నీ ignore చేయండి.

IDEMPOTENCY

సురక్షితంగా మళ్లీ ప్రయత్నించండి. API రెండుసార్లు చెల్లించదు.

ఏజెంట్ కోడ్ మళ్లీ ప్రయత్నాలు చేస్తుంది. నెట్‌వర్క్‌లు కనెక్షన్లను విడిచిపెడతాయి. LLMలు సాధనాన్ని రెండుసార్లు పిలవాలని నిర్ణయిస్తాయి. దీన్ని సురక్షితంగా చేయడానికి, పంపండి ఒక Idempotency-Key POSTలో హెడ్డర్. SDKలో payments.create మీ కోసం ఒక స్థిరమైనది ఆటో-మింట్ చేస్తుంది, కాబట్టి పునరావృత కాల్ రెండు సార్లు చెల్లించకుండా ఒకే ఒక on-chain సమర్పణకు కూలుతుంది. మీరు ప్రక్రియల మధ్య ఒకే తార్కిక కార్యకలాపాన్ని డూప్ చేయాలనుకుంటే, మీ స్వంత కీతో దాన్ని ఓవర్‌రైడ్ చేయండి.

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 ఒక స్థిరమైన ఐడెంపోటెన్సీ-కీని ఆటో-మింట్ చేస్తుంది, కాబట్టి పునరావృత కాల్ బాక్స్ నుండి సురక్షితంగా ఉంటుంది.
  • దాన్ని అధిగమించండి: మీరు ప్రక్రియల మధ్య ఒకే తార్కిక ఆపరేషన్‌ను డిడ్యూప్ చేయాలనుకుంటే మీ స్వంత కీని పాస్ చేయండి.

సిఫార్సు చేయబడిన నమూనా మీ ఏజెంట్ కోడ్‌లో ప్రతి తార్కిక కార్యకలాపానికి UUIDని రూపొందించడం (ఉదా: "ఆర్డర్ Y కోసం విక్రేత Xకు చెల్లించు" కోసం ఒక UUID) మరియు ఆ కార్యకలాపం విజయవంతం అయ్యే వరకు మళ్లీ ప్రయత్నాల ద్వారా దానిని పునరుపయోగించడం. మీరు దానిని స్పష్టంగా పేర్కొనకపోతే అధికారిక SDKలు payments.create కోసం ఒకటి ఆటో-జనరేట్ చేస్తాయి.

రేటు పరిమితులు

మీ పరిమితిని ప్రతిస్పందన నుండి చదవండి, పట్టిక నుండి కాదు.

మీ ప్రణాళికతో పరిమితులు స్కేల్. తారుమారయ్యే సంఖ్యలను కఠినంగా కోడ్ చేయడం కంటే, ప్రతి స్పందన మీ స్థితిని చెబుతుంది మరియు SDKలు మీ కోసం బ్యాక్ఫ్‌ను నిర్వహిస్తాయి.

ప్రతి విజయవంతమైన స్పందనపై హెడర్లు

  • X-RateLimit-Limit: మీ ప్రణాళిక యొక్క స్థిరమైన రేటు
  • X-RateLimit-Remaining: ఈ విండోలో ఎంత కాల్స్ మిగిలి ఉన్నాయి
  • X-RateLimit-Reset: విండో పునఃసెట్ అయినప్పుడు యూనిక్స్ సెకన్లు

మీరు కాప్‌ను తాకినప్పుడు (HTTP 429)

  • ప్రతిస్పందనలో ఉంది Retry-After సెకండ్లలో
  • ప్రాధమిక SDKలు 429 మరియు 5xx పై పునరావృతం చేస్తాయి, Retry-After ను గౌరవిస్తూ ఎక్స్‌పోనెన్షియల్ బ్యాక్‌ఆఫ్‌తో.
  • చాలా కోడ్ 429ని చేతితో నిర్వహించదు ఎందుకంటే SDK ఇప్పటికే చేస్తుంది
X402 అనుకూలత

x402ని నిష్కర్షంగా మాట్లాడుతుంది. ఇది లేకుండా కూడా పనిచేస్తుంది.

x402 అనేది HTTP-నేటివ్ చెల్లింపులకు ఓపెన్ ప్రోటోకాల్. ప్రాథమికం: 402 చెల్లింపు అవసరం తిరిగి ఇచ్చే ఏదైనా API స్పందనలో చెల్లింపు అవసరాలను ప్రచారం చేయవచ్చు, మరియు స్పెక్స్‌ను అర్థం చేసుకునే ఏ క్లయింట్ చెల్లించవచ్చు మరియు మళ్లీ ప్రయత్నించవచ్చు - సైన్ అప్ లేదు, API కీ లేదు, అవుట్-ఆఫ్-బ్యాండ్ చర్చ లేదు. Blockchain0x నిజమైన x402 ప్యాకేజీలను పంపిస్తుంది: చెల్లింపు-వైపు క్లయింట్ మరియు స్వీకరణ-వైపు సర్వర్ అడాప్టర్లు. ఈ రోజు ఉన్న ఏకైక స్కీం exact-usdc, Base పై ఉంది.

CALLER చెల్లించనిప్పుడు సర్వర్ 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 ను నిర్మించి, X-Payment: exact-usdc:<base64(json)> header తో request ను మళ్లీ పంపిస్తుంది.
  3. Pay sideలో, @blockchain0x/x402 నుండి createX402Client({ sdk }) మీ కోసం ఇదే చేస్తుంది - అది 402లకు ఆటోమేటిక్‌గా స్పందిస్తుంది.
  4. మీ server X-Payment header ను verify చేసి original request ను పూర్తి చేస్తుంది.

రెండు వైపులా, నిజమైన ప్యాకేజీలు

చెల్లింపు పక్కన, createX402Client({ sdk }) @blockchain0x/x402 నుండి ఫెచ్‌ను కప్పి 402లను ఆటోమేటిక్‌గా సమాధానం ఇస్తుంది. అందుకోగానే, createX402Plugin (Fastify) మరియు createX402Middleware (Express) మీ స్వంత ఎండ్ పాయింట్లను గేట్ చేయండి. లేదా x402ని దాటించి REST APIని నేరుగా ఉపయోగించండి - రెండూ కలుస్తాయి, కాబట్టి మీరు సిద్ధమైనప్పుడు x402ని జోడించవచ్చు.

సాధారణంగా అడిగే

డెవలపర్లు మొదట అడిగే ఐదు API ప్రశ్నలు.

నేను SDK లేకుండా APIని ఉపయోగించగలనా?

అవును. SDKలు బేరర్-టోకెన్ ఆథ్‌తో HTTPS పై ప్రామాణిక JSON చుట్టూ ఉన్న సన్నని రాపర్లు. HTTP మరియు HMAC-SHA256ని మాట్లాడగలిగే ఏదైనా APIని నేరుగా ఉపయోగించవచ్చు. SDKలు ఎర్గోనామిక్ టైపింగ్, పునరావృతాలు మరియు ఐడెంపోటెన్సీ-కీ ఉత్పత్తి కోసం ఉన్నాయి; అవి సౌకర్యవంతమైనవి, అవసరమైనవి కాదు. మేము Node, Python, Ruby, Go మరియు JVM కోసం క్లయింట్లను పంపిస్తాము; ఇతర భాషలో, కచ్చితమైన APIని పిలవండి.

ఒక సంఘటన జరగడానికి వెబ్‌హుక్ ఎండ్‌పాయింట్ డౌన్ అయితే ఏమి జరుగుతుంది?

డెలివరీలు బ్యాకాఫ్‌తో పునరుద్ధరించబడతాయి మరియు ప్రతి ప్రయత్నం డాష్‌బోర్డ్‌లో దాని HTTP ప్రతిస్పందన కోడ్‌తో నమోదు చేయబడుతుంది. మీరు ఒక ఈవెంట్‌ను మిస్ అయితే, మీరు API నుండి పునరుద్ధరించవచ్చు - GET /v1/transactions/{id} తో ఐడీ ద్వారా లావాదేవీని పొందండి - వెబ్‌హుక్‌పై మాత్రమే ఆధారపడకుండా. దాన్ని నమ్మే ముందు webhooks.verify (లేదా డాక్యుమెంటెడ్ HMAC) తో ప్రతి డెలివరీని నిర్ధారించండి, మరియు ఒక నెమ్మదిగా హ్యాండ్లర్ విఫలమవ్వడం వంటి కనిపించకుండా త్వరగా 2xx కు స్పందించండి.

నా ఏజెంట్ నెట్‌వర్క్ లోపాలపై పునరావృతం అయితే డూప్లికేట్ చెల్లింపులను ఎలా నివారించాలి?

POST పై Idempotency-Key హెడ్డర్‌ను పంపండి. SDKలో payments.create మీ కోసం స్థిరమైనది ఆటో-మింట్ చేస్తుంది, కాబట్టి మళ్లీ ప్రయత్నించిన కాల్ రెండుసార్లు చెల్లించకుండా ఒకే ఆన్-చైన్ సమర్పణకు కూలుతుంది. మీరు ప్రక్రియల మధ్య అదే తార్కిక కార్యకలాపాన్ని డీడూప్ చేయాలనుకుంటే మీ స్వంత కీతో దాన్ని ఓవర్‌రైడ్ చేయండి. కీ మీ ఏజెంట్ లేదా నెట్‌వర్క్ మధ్య-ఫ్లైట్‌లో మళ్లీ ప్రయత్నించిన సందర్భంలో ఖచ్చితంగా సురక్షిత నెట్.

ఒక రేటు పరిమితి ఉందా?

అవును, మరియు ఇది మీ ప్రణాళికతో స్కేల్ చేస్తుంది. కదిలే సంఖ్యలను కఠినంగా కోడ్ చేయడానికి బదులు, ప్రతిస్పందన నుండి వాటిని చదవండి: ప్రతి కాల్ X-RateLimit-Limit, X-RateLimit-Remaining, మరియు X-RateLimit-Reset ను తిరిగి ఇస్తుంది, మరియు 429 సెకండ్లలో Retry-After ను కలిగి ఉంటుంది. అధికారిక SDK లు ఇప్పటికే 429 మరియు 5xx పై తిరిగి ప్రయత్నిస్తాయి మరియు Retry-After ను గౌరవిస్తాయి, కాబట్టి ఎక్కువ భాగం కోడ్ ఈ విషయం చేతితో నిర్వహించాల్సిన అవసరం లేదు.

ఇది x402-సరిపోయేలా ఉందా?

అవును. x402 ప్యాకేజీలు నిజమైనవి: createX402Client({ sdk }) @blockchain0x/x402 నుండి చెల్లింపు వైపు 402 సవాళ్లకు సమాధానం ఇస్తుంది, మరియు createX402Plugin (Fastify) / createX402Middleware (Express) మీ స్వంత ఎండ్పాయింట్లను స్వీకరించే వైపు గేట్ చేస్తుంది. ఈ రోజు ఉన్న ఏకైక పథం exact-usdc, మరియు వైర్ ఫార్మాట్ X-Payment: exact-usdc:<base64(json)> అభ్యర్థన హెడ్డర్ 402 కు వ్యతిరేకంగా ఉంది, దాని శరీరం వెర్షన్ 1ని ప్రకటన చేస్తుంది మరియు accepts[] జాబితా. మీరు x402ని నిర్లక్ష్యం చేసి కేవలం REST APIని నేరుగా ఉపయోగించవచ్చు.

మీ మొదటి చెల్లింపును పంపండి.

ప్రారంభించడానికి ఉచితం. API కీ నుండి మీ మొదటి USDC బదిలీకి కొన్ని పంక్తులు.