મુખ્ય સામગ્રી પર જાઓ
ચુકવણી API

AI એજન્ટ કોડ માટે ડિઝાઇન કરેલ ચુકવણી API.

એક નાનું REST API. સહી કરેલ વેબહુક. પાંચ ભાષાઓમાં અધિકૃત SDKs. બનાવવામાં આવ્યું છે જેથી તમારા એજન્ટ USDC મોકલી શકે અને સમાપ્ત કરી શકે અને થોડા કોડની લાઇનમાં ચુકવણીઓની પુષ્ટિ કરી શકે.

ટ્રાન્ઝેક્શન દૃશ્ય: બેસ પર પુષ્ટિ થયેલ આવતી 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 મિનિટની પુનરાવર્તન વિન્ડો. દરેક પોસ્ટ પર આઈડેમ્પોટન્સી કી.

payment.received

USDC તમારા એક એજન્ટ વૉલેટમાં આવી ગયું

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 network
અધિકૃત SDKs

TypeScript અને Python માટે ટાઇપ કરેલા ક્લાયન્ટ.

ટાઇપસ્ક્રિપ્ટ
npm install @blockchain0x/node

Node 18+ સાથે કાર્ય કરે છે. નેટિવ TypeScript પ્રકાર.

પાયથન
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 પર પોસ્ટ કરી શકે છે. સહી એ છે જે સાબિત કરે છે કે ઘટના ખરેખર અમારો પાસેથી આવી છે.

દરેક ડિલિવરીમાં એક X-Blockchain0x-Signature header (t=<unix>,v1=<hex>) - HMAC-SHA256 `${t}.${rawBody}` સ્ટ્રિંગ પર તમારા વેબહુક ગુપ્ત સાથે, 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");
});
પાયથન (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), અને BLOCKCHAIN0X_WEBHOOK_SECRETમાંથી તમારો handler તેને વાંચે છે. Rotate કરવાથી જૂનું secret અમાન્ય બને છે, એટલે rolloutનું સંકલન કરો: નવું secret તમારા serverના envમાં સેટ કરો, deploy કરો, પછી rotate કરો. shipped events payment.received, payment.sent, wallet.deployed, અને webhook.test છે - event type મુજબ branch કરો, બાકીનું અવગણો.

IDEMPOTENCY

સુરક્ષિત રીતે પુનરાવર્તન કરો. API બે વખત ચૂકવણી નહીં કરે.

એજન્ટ કોડ પુનરાવૃત્તિ કરે છે. નેટવર્ક કનેક્શન છોડે છે. LLMs ટૂલને બે વાર બોલાવવા માટે નક્કી કરે છે. આને સલામત બનાવવા માટે, એક મોકલો 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 એક સ્થિર 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 ને માન્યતા આપે છે
  • જ્યાં સુધી SDK પહેલેથી જ કરે છે ત્યાં સુધી મોટાભાગનું કોડ ક્યારેય 429ને હાથથી સંભાળતું નથી
X402 સુસંગતતા

x402 ધારીને બોલે છે. તે વિના પણ કામ કરે છે.

x402 HTTP-મૂળભૂત ચુકવણી માટેનું ખુલ્લું પ્રોટોકોલ છે. ધ્યેય: કોઈપણ API જે 402 ચુકવણી જરૂરી પાછું આપે છે તે જવાબમાં ચુકવણીની જરૂરિયાતોને જાહેરાત આપી શકે છે, અને કોઈપણ ક્લાયન્ટ જે સ્પષ્ટીકરણને સમજે છે તે ચૂકવણી કરી શકે છે અને પુનઃપ્રયાસ કરી શકે છે - કોઈ સાઇનઅપ, કોઈ API કી, કોઈ બાહ્ય વાટાઘાટ નથી. Blockchain0x વાસ્તવિક x402 પેકેજો મોકલે છે: એક ચૂકવણી-પક્ષ ક્લાયન્ટ અને પ્રાપ્ત-પક્ષ સર્વર એડેપ્ટર્સ. આજના માટે એકમાત્ર યોજના છે exact-usdc, on Base.

જ્યારે એક કૉલર ચૂકવણી નથી કરી ત્યારે સર્વર 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, network eip155:8453 for Base).
  2. એક payment build કરે છે અને 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 નો ઉપયોગ કરી શકું છું?

હા. SDKઓ બેરર-ટોકન ઓથ સાથે HTTPS પર માનક JSON આસપાસ પાતળા રેપર્સ છે. જે કંઈપણ HTTP બોલી શકે છે અને HMAC-SHA256 APIને સીધા ઉપયોગ કરી શકે છે. SDKઓ આરામદાયક ટાઇપિંગ, પુનરાવૃત્તિઓ, અને આઇડેમ્પોટન્સી-કી જનરેશન માટે અસ્તિત્વમાં છે; તે સુવિધાજનક છે, જરૂરી નથી. અમે નોડ, પાયથન, રૂબી, ગો, અને JVM માટે ક્લાયન્ટ મોકલીએ છીએ; અન્ય કોઈપણ ભાષામાં, કાચા APIને કોલ કરો.

જો જ્યારે ઘટના ફાયર થાય ત્યારે મારી વેબહૂક એન્ડપોઈન્ટ ડાઉન હોય તો શું થાય છે?

ડિલિવરીઓ બેકઓફ સાથે ફરીથી પ્રયાસ કરે છે અને દરેક પ્રયાસને તેના HTTP પ્રતિસાદ કોડ સાથે ડેશબોર્ડમાં નોંધવામાં આવે છે. જો તમે એક ઇવેન્ટ ચૂકી જાઓ, તો તમે APIમાંથી સમજૂતી કરી શકો છો - GET /v1/transactions/{id} સાથે id દ્વારા ટ્રાન્ઝેક્શન મેળવો - ફક્ત વેબહૂક પર આધાર રાખવા બદલે. તેને વિશ્વસનીય બનાવ્યા પહેલા દરેક ડિલિવરીને webhooks.verify (અથવા દસ્તાવેજિત HMAC) સાથે માન્ય કરો, અને ધીમા હેન્ડલર ફેઇલર તરીકે ન દેખાય તે માટે ઝડપથી 2xx પ્રતિસાદ આપો.

જો મારી એજન્ટ નેટવર્ક ભૂલ પર પુનરાવર્તન કરે છે તો હું ડુપ્લિકેટ ચુકવણીઓથી કેવી રીતે રોકું?

POST પર Idempotency-Key હેડર મોકલો. SDKમાં payments.create તમારા માટે એક સ્થિર બનાવે છે, તેથી પુનરાવર્તિત કોલ એક જ ઓન-ચેન સબમિશનમાં ઘટે છે, બન્ને વખત ચૂકવણી કરતા. જ્યારે તમે પ્રક્રિયાઓમાં સમાન તર્કાત્મક કાર્યને ડ્યુપ્લિકેટ કરવા માંગો ત્યારે તેને તમારા પોતાના કીથી ઓવરરાઇડ કરો. કી એ સુરક્ષા જાળ છે તે ચોક્કસ કેસ માટે જ્યાં તમારો એજન્ટ અથવા નેટવર્ક મધ્યમાં પુનરાવર્તિત કરે છે.

શું દર મર્યાદા છે?

હા, અને તે તમારી યોજના સાથે સ્કેલ કરે છે. સંખ્યાઓને કઠોર-કોડ કરવા બદલે જે ખસે છે, તેમને પ્રતિસાદમાંથી વાંચો: દરેક કોલ X-RateLimit-Limit, X-RateLimit-Remaining, અને X-RateLimit-Reset પાછું આપે છે, અને 429 માં Retry-After સેકન્ડમાં સમાવેશ થાય છે. અધિકૃત SDKs પહેલેથી જ 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નો ઉપયોગ કરી શકો છો.

તમારી પ્રથમ પેમેન્ટ મોકલો.

શરૂ કરવા માટે મફત. તમારા પ્રથમ USDC ટ્રાન્સફર માટે API કીથી થોડા લાઇન.