AIエージェントコード用に設計された支払いAPI。
小さなREST API。署名されたWebhook。5つの言語の公式SDK。あなたのエージェントがUSDCを送信し、決済し、数行のコードで支払いを確認できるように構築されています。

Blockchain0x APIは故意に小さく設計されています。最初の支払いを行うために1時間もドキュメントを読む必要はありません。スニペットをコピーし、APIキーを貼り付けて実行してほしいのです。
エージェントコードのために構築された小さなサーフェス。
支払い形状のルートは以下の通りです。Webhook、APIキー、および読み取り専用の支出権限が表面を補完し、SDKがそれをすべてラップします。
/v1/paymentsエージェントウォレットからUSDC支払いを送信します/v1/transactions/{id}トランザクションの状態とハッシュを取得します/v1/payment-requests/{id}/settleオンチェーン証明で請求書を決済します/v1/agents/{id}エージェントウォレットを取得します/v1/agentsエージェントウォレットを作成するすべてHMAC-SHA256で署名されています。
署名は次の通りです:X-Blockchain0x-Signatureヘッダー。リプレイウィンドウは5分です。すべてのPOSTに冪等性キーがあります。
payment.receivedUSDCがあなたのエージェントウォレットの1つに着地しました。
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 networkTypeScriptとPythonのための型付きクライアント。
npm install @blockchain0x/nodeNode 18+で動作します。ネイティブTypeScript型。
pip install blockchain0xPython 3.9+. 同期および非同期クライアント。
SDKがラップするリクエストボディ。
これらは各ルートの確認済みの入力です。ここでは応答が短く表示されますが、完全な型付きシェイプはSDKおよびAPIリファレンスにあります。金額はUSDCの基本単位(6桁の小数)です。
/v1/paymentsUSDC支払いを送信します(payments.create)。amountWeiはUSDCの基本単位(6桁)です。チェーンアダプターが接続されるまで503を返すことがあります。
{
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000",
"metadata": { "reason": "Research report" }
}{
"txHash": "0xff5...e12"
}/v1/payment-requests/{id}/settleダッシュボードで作成された支払いリクエスト(請求書)を、オンチェーン証明(paymentRequests.settle)で決済します。作成ルートはありません - 決済のみです。
{
"txHash": "0xff5...e12",
"payerAddress": "0xBuyer...",
"amountUsdcVerified": "0.10"
}{
"txHash": "0xff5...e12"
}/v1/transactions/{id}IDによる単一トランザクションを取得します (transactions.get)。
(no body){
"id": "tx_01J9...",
"txHash": "0xff5...e12"
}/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"
}/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にPOSTできます。署名がそのイベントが実際に私たちから来たことを証明します。
すべての配信には X-Blockchain0x-Signature ヘッダー (t=<unix>,v1=<hex>) - `${t}.${rawBody}`という文字列に対してHMAC-SHA256を使用し、あなたのWebhookシークレットを使います。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");
});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 は webhook を作成または rotation したときに 1 回だけ返されます (webhooks.rotateSecret)。handler は BLOCKCHAIN0X_WEBHOOK_SECRET からそれを読み取ります。rotation すると旧 secret は無効になるため、ロールアウトは順番に行ってください。新しい secret を server の env に設定してデプロイし、その後で rotate します。出荷済みの event は payment.received, payment.sent, wallet.deployed, webhook.test です - event type で分岐し、それ以外は無視してください。
安全に再試行します。APIは二重に支払いを行いません。
エージェントコードが再試行します。ネットワークが接続を切断します。LLMがツールを2回呼び出すことを決定します。これを安全にするために、次を送信します:Idempotency-Key POSTのヘッダー。SDKのpayments.createは自動的に安定したものを生成するので、再試行された呼び出しは二重に支払うのではなく、単一のオンチェーン提出に収束します。同じ論理操作をプロセス間で重複しないようにしたい場合は、自分のキーで上書きしてください。
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" }'- 最初の呼び出し: 支払いを提出し、トランザクションを返します。
- 同じキーで再試行: 二重支払いを避けるために、1つのオンチェーン提出に収束します。
- SDKが処理します: payments.createは安定したIdempotency-Keyを自動生成するため、再試行された呼び出しは初めから安全です。
- オーバーライドする: プロセス間で同じ論理操作を重複排除したい場合は、自分のキーを渡してください。
推奨されるパターンは、エージェントコード内の論理操作ごとにUUIDを生成し(例:"注文YのためにベンダーXに支払う"ごとに1つのUUID)、操作が成功するまで再試行の間に再利用することです。公式SDKは、指定しない場合、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はHTTPネイティブ支払いのためのオープンプロトコルです。前提:402 Payment Requiredを返す任意のAPIは、応答で支払い要件を広告でき、仕様を理解する任意のクライアントは支払いと再試行ができます - サインアップ不要、APIキー不要、バンド外の交渉不要。Blockchain0xは実際のx402パッケージを提供します:支払い側クライアントと受信側サーバーアダプター。今日の唯一のスキームはBase上のexact-usdcです。
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" }
]
}エージェントコーラーが行うこと
- 402 body を読み取ります: version 1、resource、および空でない accepts[] の支払い要件(scheme exact-usdc、network は Base の eip155:8453)。
- 支払いを作成し、X-Payment: exact-usdc:<base64(json)> ヘッダーを付けてリクエストを再送します。
- 支払い側では、@blockchain0x/x402 の createX402Client({ sdk }) がこれを代行します - 402に自動応答します。
- サーバーが X-Payment ヘッダーを検証し、元のリクエストを実行します。
両側とも、実際のパッケージ
支払い側では、createX402Client({ sdk }) @blockchain0x/x402からのもので、fetchをラップし、自動的に402に応答します。受信側では、createX402Plugin (Fastify) と createX402Middleware (Express) 自分のエンドポイントをゲートします。もしくはx402をスキップしてREST APIを直接使用してください - 2つは組み合わせ可能なので、準備ができたらx402を追加できます。