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秘密鍵モード、ブラウザウォレットモード、PythonEVMAccountSignerモードの 3 種類の適応方法を示す- 落とし穴になりやすい
preferScheme/prefer_schemeフィールドを明確にする
一、プロトコル概要(必読)
成功する 1 回の X402 呼び出しには 3 回の HTTP RTT が関与します:PAYMENT-SIGNATURE ヘッダーへ格納されます。構造(抜粋):
x402Version: 2 があり、accepted オブジェクトを使用して今回選択した scheme と network(CAIP-2 識別子)を宣言します。
preferScheme / prefer_scheme は、サーバーが複数の scheme を同時に提供している場合に優先するものを選択するために使用します。サーバーが exact しか公開していない場合、このフィールドは無視されます;upto を設定していてもサーバーが公開していない場合、最初の一致項目にフォールバックします。
二、TypeScript:ブラウザウォレット + サーバー側 viem の 2 種類の使い方
インストール
createX402PaymentHandler の完全なシグネチャ
(ctx) => Promise<{ headers: Record<string, string> }> であり、SDK の paymentHandler フックシグネチャとちょうど一致します。
使用法 1:ブラウザ(MetaMask / WalletConnect)
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
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 が組み込まれています:
四、実際の実行検証
テスト目標: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 モード」との比較
六、よくある落とし穴
- chat 系は必ず
preferScheme=upto:exactを使用すると、facilitator は実際の使用量ではなくmaxAmountRequiredに基づいて USDC を差し引きます。 - Node 側で裸の秘密鍵を
createX402PaymentHandlerに渡さないでください:TS パッケージは{ privateKey }を受け付けず、EIP-1193 provider(viem のWalletClientを推奨)でラップする必要があります。 - 初回呼び出しは二重署名です:最初に Permit2 approve に署名します(オンチェーン、gas が必要)。次に X402 envelope に署名します(オンチェーンではありません)。後続の呼び出しでは 2 回目のみになります。
- Solana には Permit2 の概念がありません:SPL token transfer 認可に直接署名するため、approve は不要です。ただし、現在 Solana チェーン上では
exactのみサポートされています。 - ビジネスエラーと支払いエラーを区別する:402 → handler の失敗は
X402SignErrorをスローします(具体的な型はチェーンによって異なります)。その後の再送後、ビジネス API のエラー(401 / 422 / 5xx)は引き続き通常の SDK 例外として分類されます。 viemへの最も安定した適配方法:evmProvider: walletClient as anyは型チェックを失いますが、互換性が最も高いです。型を保持したい場合は、viem の.transport.requestを使用して{ request }オブジェクトを別途 1 層ラップして渡してください。

