মূল বিষয়বস্তুতে যান
পেমেন্ট API

AI এজেন্ট কোডের জন্য ডিজাইন করা একটি পেমেন্ট API।

একটি ছোট REST API। স্বাক্ষরিত ওয়েবহুক। পাঁচটি ভাষায় অফিসিয়াল 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

আপনার এজেন্ট থেকে একটি আউটবাউন্ড পেমেন্ট চেইনে সেটেল হয়েছে

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+ এর সাথে কাজ করে। নেটিভ টাইপস্ক্রিপ্ট টাইপ।

পাইথন
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 এর মাধ্যমে READ-ONLY - সৃষ্টি এবং পরিবর্তন শুধুমাত্র ড্যাশবোর্ডে।

অনুরোধ
(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 মিনিটের পুনরায় খেলার উইন্ডোর মধ্যে। নোডে, @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

ওয়েবহুক গোপনীয়তা একবার ফেরত দেওয়া হয় যখন আপনি ওয়েবহুক তৈরি বা রোটেট করেন (webhooks.rotateSecret), এবং BLOCKCHAIN0X_WEBHOOK_SECRET হল যেখানে আপনার হ্যান্ডলার এটি পড়ে। রোটেটিং পুরানো গোপনীয়তা বাতিল করে, তাই রোলআউটটি সমন্বয় করুন: আপনার সার্ভারের env তে নতুন গোপনীয়তা সেট করুন, ডিপ্লয় করুন, তারপর রোটেট করুন। শিপ করা ইভেন্টগুলি হল payment.received, payment.sent, wallet.deployed, এবং webhook.test - ইভেন্টের প্রকারে শাখা করুন, বাকি উপেক্ষা করুন।

আইডেমপোটেন্সি

নিরাপদে পুনরায় চেষ্টা করুন। 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) এবং অপারেশন সফল না হওয়া পর্যন্ত পুনরায় চেষ্টা করার সময় এটি পুনরায় ব্যবহার করুন। অফিসিয়াল 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-নেটিভ পেমেন্টের জন্য খোলা প্রোটোকল। ধারণা: যে কোনও API যা 402 পেমেন্ট প্রয়োজন ফেরত দেয় তা প্রতিক্রিয়াতে পেমেন্টের প্রয়োজনীয়তা বিজ্ঞাপন দিতে পারে, এবং যে কোনও ক্লায়েন্ট যা স্পেসিফিকেশন বোঝে তা পেমেন্ট করতে এবং পুনরায় চেষ্টা করতে পারে - কোন সাইনআপ, কোন API কী, কোন আউট-অফ-ব্যান্ড আলোচনা নেই। Blockchain0x বাস্তব x402 প্যাকেজগুলি পাঠায়: একটি পে-সাইড ক্লায়েন্ট এবং রিসিভ-সাইড সার্ভার অ্যাডাপ্টার। আজকের একমাত্র স্কিম হল 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, এবং 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 }) আপনার জন্য এটি করে - এটি 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 ব্যবহার করতে পারি?

হ্যাঁ। SDKs হল বেয়ারার-টোকেন অথরাইজেশন সহ HTTPS-এর উপর স্ট্যান্ডার্ড JSON-এর চারপাশে পাতলা র‍্যাপার। যা কিছু HTTP এবং HMAC-SHA256 বলতে পারে তা API সরাসরি ব্যবহার করতে পারে। SDKs আরামদায়ক টাইপিং, পুনরায় চেষ্টা এবং idempotency-key উৎপাদনের জন্য বিদ্যমান; এগুলি সুবিধাজনক, প্রয়োজনীয় নয়। আমরা 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 অন্তর্ভুক্ত করে। অফিসিয়াল 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 ব্যবহার করতে পারেন।

আপনার প্রথম পেমেন্ট পাঠান।

শুরু করতে ফ্রি। API কী থেকে আপনার প্রথম USDC স্থানান্তরের জন্য কয়েকটি লাইন।