முக்கிய உள்ளடக்கத்திற்கு தவிர்க்கவும்
கட்டண API

AI முகவர் குறியீட்டிற்கான கட்டண API.

ஒரு சிறிய REST API. கையொப்பமிடப்பட்ட webhook கள். ஐந்து மொழிகளில் அதிகாரப்பூர்வ SDK கள். உங்கள் முகவர் சில வரிகளில் 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 இலும் idempotency விசைகள்.

payment.received

USDC உங்கள் முகவர் பணப்பைகளில் ஒன்றில் இறங்கியது

payment.sent

உங்கள் agent-இலிருந்து வெளியே சென்ற payment on chain-இல் settle ஆனது

wallet.deployed

ஒரு agent-இன் smart wallet deploy செய்யப்பட்டது

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
அதிகாரப்பூர்வ 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}

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
}
WEBHOOK கையொப்ப உறுதிப்படுத்தல்

பேலோட்டை நம்புவதற்கு முன் கையொப்பத்தை எப்போதும் சரிபார்க்கவும்.

யாரும் உங்கள் கால் திருப்பும் URL க்கு POST செய்யலாம். கையொப்பம் நிகழ்வு உண்மையில் எங்களிடமிருந்து வந்தது என்பதை நிரூபிக்கிறது.

ஒவ்வொரு வழங்கலும் ஒரு X-Blockchain0x-Signature header (t=<unix>,v1=<hex>) - உங்கள் webhook ரகசியத்துடன் `${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-ஐ create அல்லது rotate செய்யும் போது (webhooks.rotateSecret) webhook secret ஒருமுறை மட்டுமே திரும்ப வழங்கப்படுகிறது, மேலும் உங்கள் handler அதை BLOCKCHAIN0X_WEBHOOK_SECRET-இலிருந்து படிக்கிறது. Rotate செய்வது பழைய secret-ஐ செல்லாததாக மாற்றும், எனவே rollout-ஐ ஒத்திசைக்கவும்: புதிய secret-ஐ உங்கள் server-இன் env-இல் அமைத்து, deploy செய்து, பின்னர் rotate செய்யவும். வழங்கப்படும் events: payment.received, payment.sent, wallet.deployed, மற்றும் webhook.test - event type-ஐ வைத்து branch செய்யவும், மற்றவற்றை புறக்கணிக்கவும்.

IDEMPOTENCY

புதுப்பிக்கவும் பாதுகாப்பாக. API இரண்டு முறை பணம் செலுத்தாது.

ஏஜென்ட் குறியீடு மீண்டும் முயற்சிக்கிறது. நெட்வொர்க்கள் இணைப்புகளை இழக்கின்றன. LLMகள் கருவியை இரண்டு முறை அழைக்க முடிவு செய்கின்றன. இதை பாதுகாப்பாக செய்ய, அனுப்பவும் Idempotency-Key POST இல் header. 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" }'
  • முதல் அழைப்பு: payment-ஐ submit செய்கிறது, transaction-ஐ return செய்கிறது.
  • அதே விசையுடன் மீண்டும் முயற்சிக்கவும்: இரண்டு முறை செலுத்துவதற்குப் பதிலாக ஒரே on-chain submission-ஆக சுருங்குகிறது.
  • SDK இதை கையாள்கிறது: payments.create தானாகவே ஒரு stable Idempotency-Key-ஐ உருவாக்குகிறது, அதனால் retried call out of the box-இல் பாதுகாப்பானது.
  • அதை மீறவும்: ஒரே தர்க்கரீதியான operation-ஐ பல processes across dedupe செய்ய வேண்டும் என்றால், உங்கள் சொந்த key-ஐ pass செய்யவும்.

எனது பரிந்துரைக்கப்பட்ட மாதிரி உங்கள் முகவர் குறியீட்டில் ஒவ்வொரு தரவியல் செயல்பாட்டிற்கும் UUID ஐ உருவாக்குவது (எடுத்துக்காட்டாக, "விற்பனையாளர் X க்கு கட்டணம் செலுத்தவும் Y" க்கு ஒரு 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-native payments-க்கான open protocol. இதன் அடிப்படை: 402 Payment Required return செய்யும் எந்த API-யும் response-இல் payment requirements-ஐ advertise செய்யலாம், மற்றும் spec-ஐ புரிந்துகொள்ளும் எந்த client-உம் pay செய்து retry செய்யலாம் - signup இல்லை, API key இல்லை, out-of-band negotiation இல்லை. Blockchain0x உண்மையான x402 packages-ஐ வழங்குகிறது: ஒரு pay-side client மற்றும் receive-side server adapters. இன்று உள்ள ஒரே scheme exact-usdc, 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, மற்றும் காலியாக இல்லாத accepts[] payment requirements (scheme exact-usdc, network eip155:8453 for Base).
  2. ஒரு payment-ஐ உருவாக்கி, request-ஐ X-Payment: exact-usdc:<base64(json)> header உடன் மீண்டும் அனுப்புகிறது.
  3. Pay side-ல், @blockchain0x/x402-இல் உள்ள createX402Client({ sdk }) இதை உங்களுக்காக செய்கிறது - அது 402s-க்கு தானாக பதிலளிக்கிறது.
  4. உங்கள் server X-Payment header-ஐ verify செய்து, original request-ஐ நிறைவேற்றுகிறது.

இரு பக்கங்களும், உண்மையான தொகுப்புகள்

செலுத்தும் பக்கம், createX402Client({ sdk }) @blockchain0x/x402 இருந்து fetch ஐ மூடியது மற்றும் 402 க்கு தானாகவே பதிலளிக்கிறது. பெறும் பக்கம், createX402Plugin (Fastify) மற்றும் createX402Middleware (Express) உங்கள் சொந்த எண்ட்பாயிண்ட்களை திறக்கவும். அல்லது x402 ஐ தவிர்த்து நேரடியாக REST API ஐ பயன்படுத்தவும் - இரண்டும் இணைக்கப்படுகின்றன, எனவே நீங்கள் தயாராக இருக்கும் போது x402 ஐ சேர்க்கலாம்.

அடிக்கடி கேட்கப்படும்

முதலில் developers கேட்கும் ஐந்து API கேள்விகள்.

நான் SDK இன் இல்லாமல் API ஐ பயன்படுத்த முடியுமா?

ஆம். SDK கள் பேயர்-டோக்கன் அங்கீகாரத்துடன் HTTPS இல் தரவுத்தொகுப்பின் சுற்றுப்புறமாக உள்ளன. HTTP மற்றும் HMAC-SHA256 ஐ பேசக்கூடிய எதுவும் API ஐ நேரடியாகப் பயன்படுத்தலாம். SDK கள் எர்கோனோமிக் தட்டச்சு, மீண்டும் முயற்சிகள் மற்றும் idempotency-key உருவாக்கத்திற்காக உள்ளன; அவை வசதியாக உள்ளன, தேவை இல்லை. நாங்கள் Node, Python, Ruby, Go, மற்றும் JVM க்கான கிளையன்ட்களை அனுப்புகிறோம்; எந்த மற்ற மொழியிலும், மூல API ஐ அழைக்கவும்.

ஒரு நிகழ்வு செயல்படும்போது என் webhook முடிவில் பிணைப்பு இல்லையெனில் என்ன நடக்கிறது?

வழங்கல்கள் பின்வாங்கியுடன் மீண்டும் முயற்சிக்கின்றன மற்றும் ஒவ்வொரு முயற்சியும் HTTP பதில்குறியீடு உடன் டாஷ்போர்டில் பதிவு செய்யப்படுகிறது. நீங்கள் ஒரு நிகழ்வை தவறவிட்டால், API இல் இருந்து சமரசம் செய்யலாம் - GET /v1/transactions/{id} உடன் அடையாளத்தால் பரிவர்த்தனையை பெறவும் - webhook மட்டுமே நம்புவதற்கு பதிலாக. அதை நம்புவதற்கு முன் webhooks.verify (அல்லது ஆவணமான HMAC) உடன் ஒவ்வொரு வழங்கலையும் உறுதிப்படுத்தவும், மற்றும் மெதுவான கையாளி தோல்வியாகத் தோன்றாமல் 2xx இல் விரைவாக பதிலளிக்கவும்.

எப்படி நான் என் எஜெண்ட் நெட்வொர்க் பிழைகளில் மறுபடியும் முயற்சிக்கும் போது மறு செலுத்தல்களைத் தவிர்க்க வேண்டும்?

POST இல் Idempotency-Key தலைப்பை அனுப்பவும். SDK இல் payments.create உங்களுக்கு ஒரு நிலையான ஒன்றை தானாகவே உருவாக்குகிறது, எனவே மீண்டும் முயற்சிக்கப்படும் அழைப்பு இரண்டு முறை பணம் செலுத்துவதற்கு பதிலாக ஒரு தனி on-chain சமர்ப்பிப்பாக மாறுகிறது. செயல்முறைகள் முழுவதும் ஒரே منطقي செயல்பாட்டை குறைக்க நீங்கள் உங்கள் சொந்த விசையுடன் அதை மீறவும். உங்கள் எஜெண்ட் அல்லது நெட்வொர்க் நடுவில் மீண்டும் முயற்சிக்கும் சந்தர்ப்பத்தில், விசை பாதுகாப்பு நெட்வொர்க் ஆக இருக்கும்.

ஒரு விகித வரம்பு உள்ளதா?

ஆம், இது உங்கள் திட்டத்துடன் அளவிடுகிறது. மிதக்கும் எண்களை கடுமையாகக் குறிக்கவில்லையா, பதிலில் இருந்து அவற்றைப் படிக்கவும்: ஒவ்வொரு அழைப்பும் X-RateLimit-Limit, X-RateLimit-Remaining, மற்றும் X-RateLimit-Reset ஐ திருப்புகிறது, மற்றும் 429 இல் Retry-After விநாடிகளில் உள்ளன. அதிகாரப்பூர்வ SDK கள் ஏற்கனவே 429 மற்றும் 5xx இல் மீண்டும் முயற்சிக்கின்றன, மேலும் Retry-After ஐ மதிக்கின்றன, எனவே பெரும்பாலான குறியீடு இதை கைமுறையாக கையாள வேண்டியதில்லை.

இது x402-இன் பொருந்துமா?

ஆம். x402 தொகுப்புகள் உண்மையானவை: @blockchain0x/x402 இல் இருந்து createX402Client({ sdk }) செலுத்தும் பக்கம் 402 சவால்களைப் பதிலளிக்கிறது, மற்றும் createX402Plugin (Fastify) / createX402Middleware (Express) உங்கள் பெறும் பக்கம் உங்கள் சொந்த முடிவுகளை திறக்கிறது. இன்று ஒரே திட்டம் exact-usdc ஆகும், மற்றும் வயர் வடிவம் X-Payment ஆகும்: exact-usdc:<base64(json)> கோரிக்கை தலைப்பு 1 பதிப்பை விளம்பரம் செய்கிற 402 உடலுக்கு எதிராக. நீங்கள் x402 ஐ தவிர்க்கவும், நேரடியாக REST API ஐப் பயன்படுத்தலாம்.

உங்கள் முதல் கட்டணத்தை அனுப்பவும்.

தொடங்குவதற்கு இலவசம். API விசையிலிருந்து உங்கள் முதல் USDC பரிமாற்றத்திற்கு சில வரிகள்.