Một API thanh toán được thiết kế cho mã tác nhân AI.
Một API REST nhỏ. Webhook đã ký. SDK chính thức trong năm ngôn ngữ. Được xây dựng để đại lý của bạn có thể gửi và giải quyết USDC và xác minh thanh toán trong vài dòng mã.
API Blockchain0x được thiết kế nhỏ gọn. Chúng tôi không muốn bạn phải đọc tài liệu trong một giờ để thực hiện khoản thanh toán đầu tiên. Chúng tôi muốn bạn sao chép một đoạn mã, dán khóa API của bạn và chạy nó.
Một bề mặt nhỏ, được xây dựng cho mã đại lý.
Các tuyến đường hình dạng thanh toán nằm bên dưới. Webhooks, api-keys và quyền chi tiêu chỉ đọc hoàn thiện bề mặt; SDK bọc tất cả.
/v1/paymentsGửi một khoản thanh toán USDC từ ví của tác nhân/v1/transactions/{id}Lấy trạng thái và băm của một giao dịch/v1/payment-requests/{id}/settleGiải quyết một hóa đơn với bằng chứng trên chuỗi/v1/agents/{id}Lấy ví của một tác nhân/v1/agentsTạo một ví tác nhânTất cả đều được ký bằng HMAC-SHA256.
Chữ ký trong X-Blockchain0x-Signature tiêu đề. Cửa sổ phát lại 5 phút. Các khóa idempotency trên mỗi POST.
payment.receivedUSDC đã đến trong một trong những ví của đại lý của bạn
payment.sentmột khoản thanh toán outbound từ agent của bạn đã được xác nhận trên chain
wallet.deployedsmart wallet của một agent đã được triển khai
webhook.testmột lần gửi thử do bạn kích hoạt từ dashboard
Gửi USDC từ ví của tác nhân của bạn.
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 networkCác khách hàng kiểu cho TypeScript và Python.
npm install @blockchain0x/nodeHoạt động với Node 18+. Các kiểu TypeScript gốc.
pip install blockchain0xPython 3.9+. Khách hàng đồng bộ và không đồng bộ.
Các thân yêu cầu mà SDK bọc.
Đây là các đầu vào đã được xác minh cho mỗi tuyến đường. Các phản hồi được hiển thị ngắn gọn ở đây; các hình dạng đầy đủ được gõ sống trong SDK và tài liệu tham khảo API. Các khoản là đơn vị cơ sở USDC (6 chữ số thập phân).
/v1/paymentsGửi một khoản thanh toán USDC (payments.create). amountWei là đơn vị cơ bản của USDC (6 chữ số thập phân). Có thể trả về 503 cho đến khi bộ chuyển đổi chuỗi được kết nối.
{
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000",
"metadata": { "reason": "Research report" }
}{
"txHash": "0xff5...e12"
}/v1/payment-requests/{id}/settleGiải quyết một yêu cầu thanh toán (hóa đơn) được tạo trong bảng điều khiển, với bằng chứng trên chuỗi (paymentRequests.settle). Không có đường tạo - chỉ giải quyết.
{
"txHash": "0xff5...e12",
"payerAddress": "0xBuyer...",
"amountUsdcVerified": "0.10"
}{
"txHash": "0xff5...e12"
}/v1/transactions/{id}Lấy một giao dịch duy nhất theo id (transactions.get).
(no body){
"id": "tx_01J9...",
"txHash": "0xff5...e12"
}/v1/agents/{id}Lấy ví của một tác nhân (agents.get). Trang công khai của nó nằm tại wallet.blockchain0x.com/a/{slug}.
(no body){
"id": "agt_01J9QKE...",
"name": "research-bot",
"public_url": "https://wallet.blockchain0x.com/a/research-bot"
}/v1/agents/{id}/spend-permissionsĐọc quyền chi tiêu của một tác nhân. CHỈ ĐỌC qua API - việc tạo và thay đổi chỉ có trong bảng điều khiển.
(no body){
"allowance_wei": "5000000",
"per_tx_wei": "1000000",
"period_seconds": 86400,
"start_at": "2026-05-15T00:00:00Z",
"revoked_at": null
}Luôn xác minh chữ ký trước khi tin tưởng vào payload.
Bất kỳ ai cũng có thể POST đến URL callback của bạn. Chữ ký là điều chứng minh sự kiện thực sự đến từ chúng tôi.
Mỗi lần giao hàng mang theo một X-Blockchain0x-Signature tiêu đề (t=<unix>,v1=<hex>) - một HMAC-SHA256 trên chuỗi `${t}.${rawBody}` với bí mật webhook của bạn, trong một khoảng thời gian phát lại 5 phút. Trong Node, webhooks.verify từ @blockchain0x/node thực hiện điều này và trả về một union phân biệt mà bạn phân nhánh. Trong các ngôn ngữ khác, tính toán cùng một HMAC và so sánh trong thời gian không đổi. Đọc thân RAW, không phải bản sao đã phân tích - việc tái tuần tự hóa sẽ phá vỡ chữ ký.
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");
});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", 200Webhook secret chỉ được trả về một lần khi bạn tạo hoặc xoay webhook (webhooks.rotateSecret), và BLOCKCHAIN0X_WEBHOOK_SECRET là nơi handler của bạn đọc nó. Việc xoay secret sẽ làm vô hiệu hóa secret cũ, vì vậy hãy phối hợp rollout: đặt secret mới vào env của server, deploy, rồi mới xoay. Các event đã phát hành là payment.received, payment.sent, wallet.deployed và webhook.test - hãy phân nhánh theo loại event, bỏ qua phần còn lại.
Thử lại một cách an toàn. API sẽ không thanh toán hai lần.
Mã đại lý thử lại. Mạng bị mất kết nối. LLM quyết định gọi công cụ hai lần. Để đảm bảo an toàn, gửi một Idempotency-Key tiêu đề trên POST. payments.create trong SDK tự động tạo một cái ổn định cho bạn, vì vậy một cuộc gọi thử lại sẽ gộp lại thành một lần gửi trên chuỗi thay vì trả tiền hai lần. Ghi đè nó bằng khóa của riêng bạn khi bạn muốn loại bỏ các hoạt động logic giống nhau giữa các quy trình.
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" }'- Cuộc gọi đầu tiên: gửi thanh toán, trả về giao dịch.
- Thử lại với cùng một khóa: gộp lại thành một lần gửi on-chain thay vì thanh toán hai lần.
- SDK xử lý nó: payments.create tự động tạo một Idempotency-Key ổn định, nên lệnh gọi được thử lại sẽ an toàn ngay từ đầu.
- Ghi đè nó: hãy truyền key của riêng bạn khi bạn muốn khử trùng lặp cùng một thao tác logic giữa các process.
Mô hình được khuyến nghị là tạo một UUID cho mỗi hoạt động logic trong mã tác nhân của bạn (ví dụ: một UUID cho "thanh toán nhà cung cấp X cho đơn hàng Y") và tái sử dụng nó qua các lần thử lại cho đến khi hoạt động thành công. Các SDK chính thức tự động tạo một UUID cho payments.create nếu bạn không chỉ định.
Đọc giới hạn của bạn từ phản hồi, không phải từ bảng.
Giới hạn quy mô với kế hoạch của bạn. Thay vì mã hóa cứng các số liệu có thể thay đổi, mỗi phản hồi cho bạn biết bạn đang ở đâu và các SDK xử lý việc giảm tốc cho bạn.
Tiêu đề trên mỗi phản hồi thành công
X-RateLimit-Limit: tỷ lệ ổn định của kế hoạch của bạnX-RateLimit-Remaining: còn bao nhiêu cuộc gọi trong cửa sổ nàyX-RateLimit-Reset: giây unix khi cửa sổ được đặt lại
Khi bạn chạm vào giới hạn (HTTP 429)
- Phản hồi bao gồm
Retry-Aftertrong giây - Các SDK chính thức thử lại trên 429 và 5xx với sự quay lại theo cấp số nhân, tôn trọng Retry-After
- Hầu hết mã không bao giờ xử lý 429 bằng tay vì SDK đã làm điều đó.
Nói x402 một cách trôi chảy. Cũng hoạt động mà không cần nó.
x402 là giao thức mở cho các khoản thanh toán gốc HTTP. Giả thuyết: bất kỳ API nào trả về 402 Payment Required có thể quảng bá các yêu cầu thanh toán trong phản hồi, và bất kỳ máy khách nào hiểu đặc tả đều có thể thanh toán và thử lại - không cần đăng ký, không cần khóa API, không cần thương lượng ngoài băng. Blockchain0x cung cấp các gói x402 thực: một máy khách phía thanh toán và bộ chuyển đổi máy chủ phía nhận. Chương trình duy nhất hiện nay là exact-usdc, trên Base.
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" }
]
}Những gì trình gọi đại lý thực hiện
- Đọc phần body 402: version 1, resource, và một accepts[] không rỗng của các yêu cầu thanh toán (scheme exact-usdc, network eip155:8453 cho Base).
- Tạo một khoản thanh toán và gửi lại request với header X-Payment: exact-usdc:<base64(json)>.
- Ở phía thanh toán, createX402Client({ sdk }) từ @blockchain0x/x402 sẽ làm điều này cho bạn - nó tự động xử lý các phản hồi 402.
- Server của bạn xác minh header X-Payment và thực thi yêu cầu gốc.
Cả hai bên, gói thực
Về phía thanh toán, createX402Client({ sdk }) từ @blockchain0x/x402 bao bọc fetch và tự động trả lời 402. Ở phía nhận, createX402Plugin (Fastify) và createX402Middleware (Express) tự định nghĩa các điểm cuối của bạn. Hoặc bỏ qua x402 và sử dụng REST API trực tiếp - hai cái này kết hợp với nhau, vì vậy bạn có thể thêm x402 khi bạn đã sẵn sàng.