Payment API

API การชำระเงินที่ออกแบบมาสำหรับโค้ดตัวแทน AI.

API REST ขนาดเล็ก Webhook ที่ลงนาม SDK อย่างเป็นทางการในห้าภาษา สร้างขึ้นเพื่อให้ตัวแทนของคุณสามารถส่งและชำระ USDC และตรวจสอบการชำระเงินในไม่กี่บรรทัดของโค้ด.

มุมมองธุรกรรม: การชำระเงิน USDC ที่เข้ามายืนยันบน Base

API ของ Blockchain0x มีขนาดเล็กโดยตั้งใจ เราไม่ต้องการให้คุณอ่านเอกสารเป็นเวลาหนึ่งชั่วโมงเพื่อทำการชำระเงินครั้งแรก เราต้องการให้คุณคัดลอกโค้ดวางกุญแจ API ของคุณและรันมัน

จุดสิ้นสุดหลัก

พื้นผิวขนาดเล็ก สร้างขึ้นสำหรับโค้ดตัวแทน.

เส้นทางที่มีลักษณะการชำระเงินอยู่ด้านล่าง Webhooks, api-keys และการอนุญาตการใช้จ่ายแบบอ่านอย่างเดียวจะทำให้พื้นผิวสมบูรณ์; SDK จะห่อหุ้มทั้งหมด.

POST/v1/paymentsส่งการชำระเงิน USDC จากกระเป๋าเงินของตัวแทน

GET/v1/transactions/{id}ดึงสถานะและแฮชของธุรกรรม

POST/v1/payment-requests/{id}/settleชำระใบแจ้งหนี้ด้วยหลักฐานบนเครือข่าย

GET/v1/agents/{id}ดึงกระเป๋าเงินของเอเจนต์

POST/v1/agentsสร้างกระเป๋าเงินเอเจนต์

เหตุการณ์ webhook ที่ส่ง

ทั้งหมดลงนามด้วย HMAC-SHA256.

ลายเซ็นใน X-Blockchain0x-Signature header. หน้าต่างการเล่นซ้ำ 5 นาที คีย์ idempotency ในทุก POST.

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.

TYPESCRIPT

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
}

การตรวจสอบลายเซ็นเว็บฮุก

ตรวจสอบลายเซ็นเสมอก่อนที่จะเชื่อถือข้อมูล payload.

ใครก็สามารถ POST ไปยัง URL การเรียกกลับของคุณได้. ลายเซ็นคือสิ่งที่พิสูจน์ว่าเหตุการณ์นั้นมาจากเรา.

ทุกการจัดส่งมี X-Blockchain0x-Signature header (t=<unix>,v1=<hex>) - HMAC-SHA256 บนสตริง `${t}.${rawBody}` ด้วย webhook secret ของคุณ ภายในหน้าต่างกัน replay 5 นาที ใน Node, webhooks.verify จาก @blockchain0x/node จะทำสิ่งนี้ให้และคืนค่า discriminated union ที่คุณใช้แยกทางการทำงานได้ ในภาษาอื่น ให้คำนวณ HMAC เดียวกันและเปรียบเทียบแบบ constant time ให้อ่าน RAW body ไม่ใช่สำเนาที่ parse แล้ว - การ serialize ใหม่จะทำให้ signature ใช้งานไม่ได้

TYPESCRIPT (NODE + EXPRESS)

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 secret จะถูกส่งกลับมาเพียงครั้งเดียวเมื่อคุณสร้างหรือหมุนเวียน webhook (webhooks.rotateSecret) และ BLOCKCHAIN0X_WEBHOOK_SECRET คือที่ handler ของคุณอ่านค่าจากนั้น การหมุนเวียนจะทำให้ secret เดิมใช้ไม่ได้ ดังนั้นต้องประสานการ rollout ให้ดี: ตั้งค่า secret ใหม่ใน env ของเซิร์ฟเวอร์ deploy แล้วค่อยหมุนเวียน อีเวนต์ที่ส่งมาคือ payment.received, payment.sent, wallet.deployed, และ webhook.test - ให้แยกทำงานตามชนิดอีเวนต์ ส่วนที่เหลือให้ละทิ้งไป

IDEMPOTENCY

ลองใหม่อย่างปลอดภัย API จะไม่ชำระเงินสองครั้ง.

การเรียกใช้โค้ดของตัวแทนซ้ำ. เครือข่ายตัดการเชื่อมต่อ. LLMs ตัดสินใจที่จะเรียกเครื่องมือสองครั้ง. เพื่อให้ปลอดภัย, ส่ง Idempotency-Key header บน POST. payments.create ใน SDK จะสร้างเหรียญที่มั่นคงให้คุณโดยอัตโนมัติ ดังนั้นการเรียกซ้ำจึงลดลงเป็นการส่งข้อมูลบน-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 ต่อการดำเนินการเชิงตรรกะในโค้ดของตัวแทนของคุณ (เช่น UUID หนึ่งตัวต่อ "จ่ายผู้ขาย X สำหรับคำสั่ง Y") และนำกลับมาใช้ใหม่ในการลองใหม่จนกว่าการดำเนินการจะสำเร็จ SDK อย่างเป็นทางการจะสร้าง UUID อัตโนมัติสำหรับ payments.create หากคุณไม่ระบุ.

ขีดจำกัดอัตรา

อ่านขีดจำกัดของคุณจากการตอบสนอง ไม่ใช่จากตาราง.

ข้อจำกัดขนาดตามแผนของคุณ แทนที่จะเข้ารหัสหมายเลขที่ลอยตัว ทุกการตอบสนองบอกคุณว่าคุณอยู่ที่ไหนและ SDK จะจัดการการถอยให้คุณ

ส่วนหัวในทุกการตอบสนองที่สำเร็จ

X-RateLimit-Limit: อัตราคงที่ของแผนของคุณ
X-RateLimit-Remaining: ยังเหลือการเรียกกี่ครั้งในหน้าต่างนี้
X-RateLimit-Reset: วินาที unix เมื่อหน้าต่างรีเซ็ต

เมื่อคุณถึงขีดจำกัด (HTTP 429)

การตอบสนองรวมถึง Retry-After ในวินาที
SDK อย่างเป็นทางการลองใหม่ใน 429 และ 5xx ด้วยการถอยกลับแบบเอ็กซ์โพเนนเชียล ให้เกียรติ Retry-After
โค้ดส่วนใหญ่ไม่เคยจัดการ 429 ด้วยมือเพราะ SDK ทำอยู่แล้ว

ความเข้ากันได้ของ X402

พูด x402 ได้อย่างคล่องแคล่ว ทำงานได้โดยไม่ต้องใช้มันเช่นกัน.

x402 เป็นโปรโตคอลเปิดสำหรับการชำระเงินที่เป็น HTTP-native หลักการ: API ใด ๆ ที่ส่งคืน 402 Payment Required สามารถโฆษณาข้อกำหนดการชำระเงินในคำตอบ และลูกค้าใด ๆ ที่เข้าใจสเปคสามารถชำระเงินและลองใหม่ได้ - ไม่ต้องลงทะเบียน ไม่ต้องใช้คีย์ 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" }
  ]
}

ตัวเรียกตัวแทนทำอะไร

อ่าน body ของ 402: version 1, resource, และ accepts[] ของข้อกำหนดการชำระเงินที่ไม่ว่าง (scheme exact-usdc, network eip155:8453 สำหรับ Base)
สร้างการชำระเงินแล้วส่งคำขออีกครั้งด้วย header X-Payment: exact-usdc:<base64(json)>
ฝั่งการจ่าย createX402Client({ sdk }) จาก @blockchain0x/x402 ทำสิ่งนี้ให้คุณ - มันตอบ 402s ให้อัตโนมัติ
เซิร์ฟเวอร์ของคุณตรวจสอบส่วนหัว X-Payment และดำเนินการตามคำขอเดิมให้สำเร็จ

ทั้งสองด้าน แพ็คเกจจริง

ในด้านการชำระเงิน, createX402Client({ sdk }) จาก @blockchain0x/x402 ห่อหุ้ม fetch และตอบสนอง 402s โดยอัตโนมัติ ในด้านการรับ, createX402Plugin (Fastify) และ createX402Middleware (Express) กำหนดการเข้าถึง endpoint ของคุณเอง หรือข้าม x402 และใช้ REST API โดยตรง - ทั้งสองส่วนทำงานร่วมกันได้ ดังนั้นคุณสามารถเพิ่ม x402 เมื่อพร้อม

คำถามที่พบบ่อย

ห้าคำถาม API ที่นักพัฒนาถามเป็นอันดับแรก

ฉันสามารถใช้ API โดยไม่ต้องใช้ SDK ได้หรือไม่?

ใช่ SDKs เป็นการห่อหุ้มที่บางรอบรอบ JSON มาตรฐานผ่าน HTTPS ด้วยการตรวจสอบสิทธิ์แบบโทเค็นผู้ถือ สิ่งใดก็ตามที่สามารถพูด HTTP และ HMAC-SHA256 สามารถใช้ API ได้โดยตรง SDK มีอยู่เพื่อการพิมพ์ที่สะดวก การลองใหม่ และการสร้างคีย์ที่ไม่เปลี่ยนแปลง; พวกเขาสะดวก ไม่ใช่สิ่งที่จำเป็น เราส่งลูกค้าสำหรับ Node, Python, Ruby, Go และ JVM; ในภาษาอื่นๆ ให้เรียก API ดิบ

เกิดอะไรขึ้นถ้าจุดสิ้นสุด webhook ของฉันล่มเมื่อเกิดเหตุการณ์?

การจัดส่งลองใหม่ด้วยการถอยกลับและแต่ละความพยายามจะถูกบันทึกในแดชบอร์ดพร้อมรหัสการตอบสนอง HTTP หากคุณพลาดเหตุการณ์ คุณสามารถปรับยอดจาก API - ดึงธุรกรรมโดยใช้ id ด้วย GET /v1/transactions/{id} - แทนที่จะพึ่งพา webhook เพียงอย่างเดียว ตรวจสอบการจัดส่งทุกครั้งด้วย webhooks.verify (หรือ HMAC ที่บันทึกไว้) ก่อนที่จะเชื่อถือ และตอบกลับ 2xx อย่างรวดเร็วเพื่อไม่ให้ตัวจัดการที่ช้าแสดงให้เห็นถึงความล้มเหลว.

ฉันจะป้องกันการชำระเงินซ้ำได้อย่างไรหากเอเจนต์ของฉันลองใหม่เมื่อเกิดข้อผิดพลาดในเครือข่าย?

ส่งส่วนหัว Idempotency-Key ใน POST payments.create ใน SDK จะสร้างหนึ่งที่เสถียรให้คุณโดยอัตโนมัติ ดังนั้นการเรียกซ้ำจึงรวมเป็นการส่งข้อมูลบนเครือข่ายเดียวแทนที่จะจ่ายสองครั้ง ให้เขียนทับด้วยกุญแจของคุณเองเมื่อคุณต้องการลบการทำซ้ำของการดำเนินการเชิงตรรกะเดียวกันในกระบวนการ กุญแจเป็นตาข่ายความปลอดภัยสำหรับกรณีที่ตัวแทนของคุณหรือเครือข่ายทำการลองใหม่ระหว่างการบิน

มีการจำกัดอัตราหรือไม่?

ใช่ และมันขยายตามแผนของคุณ แทนที่จะเข้ารหัสหมายเลขที่ลอยไป ลองอ่านจากการตอบกลับ: การเรียกแต่ละครั้งจะส่งคืน 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 key ถึงการโอน USDC ครั้งแรกของคุณบน Base.