公開エンドポイントを確認する
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)
X402Client 高度検証ツールを実行する
X402Client リポジトリは高度検証ツールを提供しており、402 レスポンスの選択、署名生成、paid retry、オンチェーン settlement の確認に使用できます。これらには funded wallet、RPC、秘密鍵、開発依存関係が必要です。通常のビジネス統合では、まず TypeScript または Python SDK を使用することを推奨します。署名またはオンチェーン決済の問題を特定する必要がある場合にのみ、これらのツールを実行してください。 リポジトリアドレス:https://github.com/AceDataCloud/X402Client- 最初のリクエストの 402 レスポンス。
- 選択された payment requirement。
- 署名後の
PAYMENT-SIGNATURE要約。 - リトライ後の HTTP ステータスとレスポンスボディ。
- オンチェーン settlement transaction、または失敗時の Facilitator エラー原因。
PAYMENT-SIGNATURE をログシステムやチケットに送信しないでください。
公開 API 検証結果の例:
- Base
exact、Solanaexact、Baseuptoはすべて HTTP 402 から HTTP 200 への paid retry を完了しました。 - Base
exactのオンチェーン取引は BaseScan で確認でき、決済額は95215atomic USDC です。 - Base
uptoの署名上限は95215atomic USDC ですが、実際のオンチェーン settlement は3atomic USDC であり、後払い計量が実使用量に基づいて課金されることを示しています。 - Solana パスでは paid retry とモデル出力が確認されています。公開 RPC はレート制限される可能性があります。厳密なオンチェーン照合が必要な場合は、自前の Solana RPC またはプラットフォーム側の決済記録を使用して取引署名を確認してください。
SDK smoke test
高度検証ツールは署名とオンチェーン決済の確認に使用します。ビジネス側でも SDK smoke test を実行し、アプリケーションコードが payment handler を通じて 402 を自動的に処理できることを確認する必要があります。以下ではコア部分のみを示します。完全なコードでは、ウォレット、provider、import を補完する必要があります。 TypeScript: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には Baseexactと Solanaexactがあり、金額はいずれも1200000atomic USDC です。 - Base
PAYMENT-SIGNATUREを付けて再試行した後、HTTP 200 が返され、注文状態はFinishedに変わり、pay_wayはX402です。 PAYMENT-RESPONSEをデコードすると、success=True、network=baseが表示され、同一のトランザクションハッシュが提供されます。- BaseScan 上のトランザクション状態は
1で、転送額は1200000atomic USDC、つまり1.2USDC です。 - 作成価格
1.26は旧 X402 支払い優遇ポリシー期間中に支払われ、最終的な署名および決済金額は1.2USDC です。
Authorization: Bearer {platform_token} がない場合、または注文が現在のアカウントに属していない場合は、プラットフォーム権限レイヤーで失敗します。これは x402.acedata.cloud のアカウント不要な X402 API を直接呼び出す場合とは異なります。
よくあるエラー
Base upto チェックリスト
upto は現在 Base 上でのみ提供されています(eip155:8453)。upto 署名はより多くの EVM typed data パラメータにバインドされるため、統合時には 402 レスポンス内のリアルタイムフィールドとクライアント署名が完全に一致していることを特に確認してください。
upto が invalid_upto_evm_payload_invalid_signature を返す場合、優先して以下を確認してください:
- API が返す
eip155:8453+uptoエントリ内のextra.chainId(8453である必要があります)。 - API が返す
extra.facilitatorAddress。 https://facilitator.acedata.cloud/supportedが返す Baseuptofacilitator アドレス。- Permit2 domain、spender、USDC コントラクト、および署名アカウント。
- ウォレットがすでに 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として扱い、カスタマーサポートが検索できるよう公開技術コードを保持してください。

