メインコンテンツへスキップ
X402 は Coinbase が提案した「HTTP 402 による課金」のオンチェーン決済プロトコルです:サーバーは token のないリクエストに対して 402 Payment Required を返し、受け入れ可能なチェーン / 資産 / 価格を列挙する accepts: [...] フィールドを付加します;クライアントはローカルで承認に署名し(EVM では Permit2 / EIP-712、Solana では SPL token transfer 承認)、base64 化した envelope を PAYMENT-SIGNATURE ヘッダーに入れて再送します。サーバーは検証後に実際にオンチェーンで決済し、その後ビジネス結果を返します。
Ace Data Cloud の X402 クライアントはターゲット API を直接呼び出し、そのリクエストでリアルタイムに返される 402 Payment Required と accepts を価格および署名の根拠として使用します。Facilitator の決済機能は /.well-known/x402 で検証できます。
@acedatacloud/sdk と acedatacloud はどちらも paymentHandler フックを公開しています:SDK 自身が発行したリクエストが 402 を受け取った場合、注入した handler を呼び出して PAYMENT-SIGNATURE ヘッダーを取得し、その後元のリクエストを再送します。@acedatacloud/x402-client / acedatacloud-x402 を SDK と組み合わせると、プロセス全体がビジネスコードに対して完全に透過的になります——必要なのは client.openai.chat.completions.create(...) だけで、見た目は token モードとまったく同じですが、内部では呼び出しごとの支払いであり、事前チャージは不要です。 本文:
  • TS 側の「token なし + X402 handler 注入」フローを実際に一通り接続した(T12 検証)
  • EVM / Solana の 2 種類の署名フローの違いを列挙した
  • viem 秘密鍵モード、ブラウザウォレットモード、Python EVMAccountSigner モードの 3 種類の適応方法を示す
  • 落とし穴になりやすい preferScheme / prefer_scheme フィールドを明確にする

一、プロトコル概要(必読)

成功する 1 回の X402 呼び出しには 3 回の HTTP RTT が関与します:
X402 envelope は JSON の一部であり、base64 化された後に PAYMENT-SIGNATURE ヘッダーへ格納されます。構造(抜粋):
envelope の最上位には x402Version: 2 があり、accepted オブジェクトを使用して今回選択した scheme と network(CAIP-2 識別子)を宣言します。 preferScheme / prefer_scheme は、サーバーが複数の scheme を同時に提供している場合に優先するものを選択するために使用します。サーバーが exact しか公開していない場合、このフィールドは無視されます;upto を設定していてもサーバーが公開していない場合、最初の一致項目にフォールバックします。

二、TypeScript:ブラウザウォレット + サーバー側 viem の 2 種類の使い方

インストール

実測したバージョン番号:

createX402PaymentHandler の完全なシグネチャ

戻り値は (ctx) => Promise&lt;{ headers: Record<string, string> }> であり、SDK の paymentHandler フックシグネチャとちょうど一致します。

使用法 1:ブラウザ(MetaMask / WalletConnect)

初回の呼び出しでは、ブラウザに2 回の署名プロンプトが表示されます:1 回目は USDC に対する Permit2 の一度きりの approve(金額は MaxUint256、オンチェーンに書き込まれる)です;2 回目は X402 envelope の EIP-712 署名(オンチェーンには書き込まれず、facilitator による検証のためだけのもの)です。以降の呼び出しでは 2 回目の署名だけが必要であり、体験としては「1 回署名をクリック → 結果を取得」です。

使用法 2:Node サーバー側 + viem 秘密鍵(バックエンド / CLI 向け)

TS 側の @acedatacloud/x402-client はEIP-1193 provider のみを受け付けます——秘密鍵を直接扱いません。Node / CLI シナリオでは、標準的な方法は viem を使用して秘密鍵を WalletClient としてラップし、その後 @ethereumjs/util または viem 内部の EIP-1193 アダプターを利用することです。
viem の EIP-1193 適合性が十分に安定していないと感じる場合は、より低レベルの signEVMUptoPayment を使用し、自分で accepts → signed envelope → PAYMENT-SIGNATURE header の経路をつなぎ、SDK フックをスキップすることもできます。ただし、プロトコルのアップグレードを自分で管理しなくて済むよう、やはりまずは createX402PaymentHandler を推奨します。

使用方法 3:Solana

Solana チェーン上では現在**exact scheme のみ公開**されているため、preferScheme は Solana では機能しません。

三、Python:秘密鍵モード

Python の acedatacloud-x402 は、秘密鍵を直接使用して署名する方式です(EIP-1193 抽象化はありません)。サーバーサイド / タスク実行器により適しています。

インストール

検証済みバージョン番号:

EVM(Base)

Solana

一度限りの approve(EVM 初回のみ)

EVM Base 上の X402 は Permit2 を使用するため、ウォレットは USDC について Permit2 コントラクトに一度 MaxUint256 の approve を行う必要があります。acedatacloud-x402 には approve_permit2 が組み込まれています:
このトランザクションは一度だけ送信すればよく、その後のすべての X402 EVM 支払いではこの認可を使用します。Solana では不要です。

四、実際の実行検証

テスト目標:TS SDK に token を渡さず、X402 handler を注入して、正常に構築およびリクエスト送信できること(実際のオンチェーン USDC を消費しない軽量な検証)。
出力:
結果の説明:
  • apiToken を渡していなくても、SDK の構築でエラーにならないため、X402 モードが実際に token の有効な代替手段であることが証明されます。
  • createX402PaymentHandler が返すのは関数(フック)であり、SDK はそれを受け取った後、402 を受信した場合にのみ呼び出します。
  • 実際のオンチェーン支払いが成功するエンドツーエンドテストは、実際の USDC 引き落としを伴うため、本チュートリアルには含めていません。X402 統合ガイド の e2e サンプルを参照できます。
Python 側の create_x402_payment_handler でも同じ検証を行っています —— 関数の戻り値は callable であり、payment_handler=... を注入した場合に AceDataCloud(...) の構築でエラーは発生しません。両者のセマンティクスは一致しています。

五、「Bearer token モード」との比較

六、よくある落とし穴

  1. chat 系は必ず preferScheme=upto:exact を使用すると、facilitator は実際の使用量ではなく maxAmountRequired に基づいて USDC を差し引きます。
  2. Node 側で裸の秘密鍵を createX402PaymentHandler に渡さないでください:TS パッケージは { privateKey } を受け付けず、EIP-1193 provider(viem の WalletClient を推奨)でラップする必要があります。
  3. 初回呼び出しは二重署名です:最初に Permit2 approve に署名します(オンチェーン、gas が必要)。次に X402 envelope に署名します(オンチェーンではありません)。後続の呼び出しでは 2 回目のみになります。
  4. Solana には Permit2 の概念がありません:SPL token transfer 認可に直接署名するため、approve は不要です。ただし、現在 Solana チェーン上では exact のみサポートされています。
  5. ビジネスエラーと支払いエラーを区別する:402 → handler の失敗は X402SignError をスローします(具体的な型はチェーンによって異なります)。その後の再送後、ビジネス API のエラー(401 / 422 / 5xx)は引き続き通常の SDK 例外として分類されます。
  6. viem への最も安定した適配方法:evmProvider: walletClient as any は型チェックを失いますが、互換性が最も高いです。型を保持したい場合は、viem の .transport.request を使用して { request } オブジェクトを別途 1 層ラップして渡してください。

詳細はこちら