メインコンテンツへスキップ
X402 には HTTP、SDK、署名、Facilitator、オンチェーン取引が関係します。署名または決済の問題を調査する際は、「公開エンドポイント -> 402 レスポンス -> SDK payment handler -> オンチェーン settlement」の順序で層ごとに確認することを推奨します。本チュートリアルでは、各層の確認方法を説明し、よくあるエラーを列挙します。

公開エンドポイントを確認する

Facilitator の機能宣言:
facilitator、supportedKinds、およびプロトコルエンドポイントが返される場合、機能メタデータは正常です。API リソースディスカバリーは廃止されました。対象 API を直接呼び出し、リアルタイムの 402 レスポンスを基準にしてください。 Facilitator がサポートする機能:
kinds が返される場合、Facilitator エンドポイントは正常です。

402 accepts を確認する

課金されない未認証リクエストを送信します:
返された accepts に、使用したいネットワークが含まれているか確認してください。network は CAIP-2 識別子です:
  • eip155:8453 + exact(Base)
  • eip155:8453 + upto(Base、後払い計量)
  • solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp + exact(Solana)
対象ネットワークがない場合、その API または現在の環境には対応する X402 受取方法が設定されていません。

X402Client 高度検証ツールを実行する

X402Client リポジトリは高度検証ツールを提供しており、402 レスポンスの選択、署名生成、paid retry、オンチェーン settlement の確認に使用できます。これらには funded wallet、RPC、秘密鍵、開発依存関係が必要です。通常のビジネス統合では、まず TypeScript または Python SDK を使用することを推奨します。署名またはオンチェーン決済の問題を特定する必要がある場合にのみ、これらのツールを実行してください。 リポジトリアドレス:https://github.com/AceDataCloud/X402Client
Base:
Solana:
検証ツールは通常、以下を出力します:
  1. 最初のリクエストの 402 レスポンス。
  2. 選択された payment requirement。
  3. 署名後の PAYMENT-SIGNATURE 要約。
  4. リトライ後の HTTP ステータスとレスポンスボディ。
  5. オンチェーン settlement transaction、または失敗時の Facilitator エラー原因。
秘密鍵または完全な PAYMENT-SIGNATURE をログシステムやチケットに送信しないでください。 公開 API 検証結果の例:
説明:
  • Base exact、Solana exact、Base upto はすべて HTTP 402 から HTTP 200 への paid retry を完了しました。
  • Base exact のオンチェーン取引は BaseScan で確認でき、決済額は 95215 atomic USDC です。
  • Base upto の署名上限は 95215 atomic USDC ですが、実際のオンチェーン settlement は 3 atomic USDC であり、後払い計量が実使用量に基づいて課金されることを示しています。
  • Solana パスでは paid retry とモデル出力が確認されています。公開 RPC はレート制限される可能性があります。厳密なオンチェーン照合が必要な場合は、自前の Solana RPC またはプラットフォーム側の決済記録を使用して取引署名を確認してください。

SDK smoke test

高度検証ツールは署名とオンチェーン決済の確認に使用します。ビジネス側でも SDK smoke test を実行し、アプリケーションコードが payment handler を通じて 402 を自動的に処理できることを確認する必要があります。以下ではコア部分のみを示します。完全なコードでは、ウォレット、provider、import を補完する必要があります。 TypeScript:
Python:
モデルが指定どおり固定文字列を返す場合、SDK、payment handler、Gateway、Facilitator、対象 API が連携されていることを示します。 上記 2 つの smoke test は Base exact を使用し、402 見積もりの固定金額で決済します。チャット補完は token 単位で計量されるシナリオに属するため、本番統合時には preferScheme: 'upto'(Python では prefer_scheme="upto")を渡し、実使用量に基づいて決済することを推奨します。 Python SDK の戻り値オブジェクトは dict であり、res["choices"][0]["message"]["content"] を使用して内容を読み取れます。

注文支払い E2E

注文支払いでは platform.acedata.cloud のプラットフォーム API を使用し、プラットフォームアカウントトークンが必要です。完全なフローは次のとおりです:Pending 注文を作成し、POST /api/v1/orders/{order_id}/pay/ で 402 をトリガーし、その後 PAYMENT-SIGNATURE を付与してリトライします。 少額注文支払いの検証結果の例:
以下の取引記録は旧ポリシー下での過去の実測サンプルであり、金額と取引ハッシュはそのまま保持されています。新しい X402 注文には支払い方法の割引は適用されません。今回の 402 レスポンスの amount を署名および支払いの基準にしてください。
結果の説明:
  • 注文作成後、注文状態は Pending で、価格は 1.26 です。
  • 最初の pay/ リクエストは HTTP 402 を返し、accepts には Base exact と Solana exact があり、金額はいずれも 1200000 atomic USDC です。
  • Base PAYMENT-SIGNATURE を付けて再試行した後、HTTP 200 が返され、注文状態は Finished に変わり、pay_way は X402 です。
  • PAYMENT-RESPONSE をデコードすると、success=True、network=base が表示され、同一のトランザクションハッシュが提供されます。
  • BaseScan 上のトランザクション状態は 1 で、転送額は 1200000 atomic USDC、つまり 1.2 USDC です。
  • 作成価格 1.26 は旧 X402 支払い優遇ポリシー期間中に支払われ、最終的な署名および決済金額は 1.2 USDC です。
注文の支払いに Authorization: Bearer {platform_token} がない場合、または注文が現在のアカウントに属していない場合は、プラットフォーム権限レイヤーで失敗します。これは x402.acedata.cloud のアカウント不要な X402 API を直接呼び出す場合とは異なります。

よくあるエラー

Base upto チェックリスト

upto は現在 Base 上でのみ提供されています(eip155:8453)。upto 署名はより多くの EVM typed data パラメータにバインドされるため、統合時には 402 レスポンス内のリアルタイムフィールドとクライアント署名が完全に一致していることを特に確認してください。
Base upto が invalid_upto_evm_payload_invalid_signature を返す場合、優先して以下を確認してください:
  1. API が返す eip155:8453 + upto エントリ内の extra.chainId(8453 である必要があります)。
  2. API が返す extra.facilitatorAddress。
  3. https://facilitator.acedata.cloud/supported が返す Base upto facilitator アドレス。
  4. Permit2 domain、spender、USDC コントラクト、および署名アカウント。
  5. ウォレットがすでに Base USDC に対して Permit2 を approve しているかどうか。
upto の署名 digest は、Permit2 domain、chain ID、spender、受取アドレス、facilitator アドレス、および validAfter に同時にバインドされます。いずれか 1 つでも一致しない場合、Facilitator は誤った signer を復元し、invalid signature を返します。これらがすべて一致していても 402 が返される場合、次に Permit2 allowance を確認してください。未承認の場合は PERMIT2_ALLOWANCE_REQUIRED が返されます。

検証情報の保存

完全な検証では、少なくとも以下を保存してください:
  • API path とリクエスト本文の要約;
  • 選択した network と scheme;
  • maxAmountRequired;
  • payer ウォレットアドレス;
  • HTTP の最終ステータス;
  • レスポンス内のモデル出力またはタスク ID;
  • settlement transaction リンク;
  • Gateway trace ID またはプラットフォーム利用記録 ID。
秘密鍵、完全な PAYMENT-SIGNATURE、完全な EIP-712 signature、またはニーモニックは保存しないでください。

構造化された支払いエラー

署名後の X402 失敗では、extensions.acedatacloud.paymentError に安定した code、安全な挿入パラメータ、フェーズ、および再試行可能フラグが返されます。この構造を優先して調査し、最上位の英語 error を解析したり、ユーザーにウォレット署名やオンチェーンシミュレーション原文の提供を求めたりしないでください。
  • charged: false:決済前に検証で明確に拒否されており、今回は課金されていません。
  • charged を含まない:結果は不明、またはすでに決済段階に入っています。まず注文とオンチェーン状態を確認し、直接再支払いすることは禁止です。
  • settlement_pending:まだ再支払いせず、まず注文を更新するかサポートに連絡してください。
  • 未認識の code:payment_failed として扱い、カスタマーサポートが検索できるよう公開技術コードを保持してください。