メインコンテンツにスキップ
PAYMENT API

AIエージェントコード用に設計された支払いAPI。

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

トランザクションビュー:Baseで確認された入金USDC支払い

Blockchain0x APIは故意に小さく設計されています。最初の支払いを行うために1時間もドキュメントを読む必要はありません。スニペットをコピーし、APIキーを貼り付けて実行してほしいのです。

コアエンドポイント

エージェントコードのために構築された小さなサーフェス。

支払い形状のルートは以下の通りです。Webhook、APIキー、および読み取り専用の支出権限が表面を補完し、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ヘッダー。リプレイウィンドウは5分です。すべてのPOSTに冪等性キーがあります。

payment.received

USDCがあなたのエージェントウォレットの1つに着地しました。

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+. 同期および非同期クライアント。

完全なエンドポイントスキーマ

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
}
ウェブフック署名確認

ペイロードを信頼する前に、常に署名を確認してください。

誰でもあなたのコールバックURLにPOSTできます。署名がそのイベントが実際に私たちから来たことを証明します。

すべての配信には X-Blockchain0x-Signature ヘッダー (t=<unix>,v1=<hex>) - `${t}.${rawBody}`という文字列に対してHMAC-SHA256を使用し、あなたのWebhookシークレットを使います。5分のリプレイウィンドウ内で。Nodeでは、@blockchain0x/nodeのwebhooks.verifyがこれを行い、分岐するための識別されたユニオンを返します。他の言語では、同じHMACを計算し、定数時間で比較します。RAWボディを読み取ってください、解析されたコピーではなく - 再シリアライズは署名を壊します。

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 を作成または 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は自動的に安定したものを生成するので、再試行された呼び出しは二重に支払うのではなく、単一のオンチェーン提出に収束します。同じ論理操作をプロセス間で重複しないようにしたい場合は、自分のキーで上書きしてください。

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" }'
  • 最初の呼び出し: 支払いを提出し、トランザクションを返します。
  • 同じキーで再試行: 二重支払いを避けるために、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を流暢に話します。それなしでも機能します。

x402はHTTPネイティブ支払いのためのオープンプロトコルです。前提:402 Payment Requiredを返す任意のAPIは、応答で支払い要件を広告でき、仕様を理解する任意のクライアントは支払いと再試行ができます - サインアップ不要、APIキー不要、バンド外の交渉不要。Blockchain0xは実際のx402パッケージを提供します:支払い側クライアントと受信側サーバーアダプター。今日の唯一のスキームはBase上のexact-usdcです。

支払いが行われていない場合、サーバーは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[] の支払い要件(scheme exact-usdc、network は Base の eip155:8453)。
  2. 支払いを作成し、X-Payment: exact-usdc:<base64(json)> ヘッダーを付けてリクエストを再送します。
  3. 支払い側では、@blockchain0x/x402 の createX402Client({ sdk }) がこれを代行します - 402に自動応答します。
  4. サーバーが X-Payment ヘッダーを検証し、元のリクエストを実行します。

両側とも、実際のパッケージ

支払い側では、createX402Client({ sdk }) @blockchain0x/x402からのもので、fetchをラップし、自動的に402に応答します。受信側では、createX402Plugin (Fastify) と createX402Middleware (Express) 自分のエンドポイントをゲートします。もしくはx402をスキップしてREST APIを直接使用してください - 2つは組み合わせ可能なので、準備ができたらx402を追加できます。

よくある質問

開発者が最初に尋ねる5つのAPIに関する質問。

SDKなしでAPIを使用できますか?

はい。SDKは、ベアラートークン認証を使用したHTTPS上の標準JSONの薄いラッパーです。HTTPとHMAC-SHA256を話せるものは何でもAPIを直接使用できます。SDKは、エルゴノミックな型付け、再試行、および冪等キー生成のために存在します。便利ですが必須ではありません。Node、Python、Ruby、Go、JVM用のクライアントを提供します。他の言語では、RAW APIを呼び出してください。

イベントが発生したときにウェブフックエンドポイントがダウンしている場合はどうなりますか?

配信はバックオフで再試行し、各試行はHTTPレスポンスコードとともにダッシュボードに記録されます。イベントを見逃した場合、APIから調整できます - GET /v1/transactions/{id}でIDでトランザクションを取得します - ウェブフックだけに依存するのではなく。信頼する前に、webhooks.verify(または文書化されたHMAC)で各配信を確認し、遅いハンドラが失敗のように見えないように迅速に2xxで応答します。

エージェントがネットワークエラーで再試行する場合、重複支払いを防ぐにはどうすればよいですか?

POSTでIdempotency-Keyヘッダーを送信します。SDKのpayments.createは、あなたのために安定したものを自動生成するため、再試行された呼び出しは二重に支払うのではなく、単一のオンチェーン提出に収束します。同じ論理操作をプロセス間で重複しないようにするために、自分のキーで上書きします。このキーは、エージェントまたはネットワークが途中で再試行する場合の安全ネットです。

レート制限はありますか?

はい、そしてそれはあなたのプランに応じてスケールします。漂流する数値をハードコーディングするのではなく、レスポンスから読み取ります:すべての呼び出しは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とaccepts[]リストを宣伝します。x402を無視してREST APIを直接使用することもできます。

最初の支払いを出荷します。

無料で始められます。APIキーからBaseでの最初のUSDC転送まで数行です。