402 Payment Required に基づくオンチェーン決済プロトコルです。Ace Data Cloud の X402 機能を通じて、呼び出し側は API Token を作成したり、アカウント残高を事前チャージしたりすることなく、各 API リクエストで直接 USDC を使用してオンチェーン決済できます。
このドキュメント群は実際の統合順序に従って構成されています。まず最小リクエストを一度実行し、次に SDK を統合し、その後ネットワーク、料金プラン、注文決済、Facilitator を理解します。以下の表を上から下へ読むことを推奨します。
推奨統合パス
Ace Data Cloud API を呼び出すだけの場合は、公式 SDK を優先して使用してください。- TypeScript:
@acedatacloud/sdk+@acedatacloud/x402-client - Python:
acedatacloud+acedatacloud-x402
SDK は、最初の認証なしリクエスト、
402 Payment Required の解析、payment handler の呼び出し、PAYMENT-SIGNATURE を付与した再試行というステップを自動的に完了します。USDC を保有するウォレットを用意し、使用したいネットワークを選択するだけです。
独自の API でも X402 受取をサポートしたい場合は、Facilitator ドキュメントを読み、paymentRequirements、paymentPayload、/verify、/settle の関係を理解する必要があります。
サポート状況
Ace Data Cloud X402 は、公開 API、公式 SDK、Facilitator、およびオンチェーン決済フローで検証を完了しています。以下の表は、開発者が統合時に最もよく使用する機能の観点から現在の状況をまとめたものです。
以下の出力は、検証済みフローのレスポンス形式を説明するためだけに使用されます。実際の統合時には、常に現在の API が返す
accepts を基準にしてください。
- npm と PyPI パッケージはいずれもクリーンな環境でインストールされ、インポートに成功しています。
- 未払いの API リクエストは 402 を返し、
acceptsには Base と Solana の利用可能な支払い方法が含まれています。 accepts[].networkは CAIP-2 識別子であり、クライアントがネットワークを選択する際は CAIP-2 文字列に従って一致させる必要があります。- TypeScript SDK と Python SDK はいずれも 402 を自動処理し、paid retry を完了できます。
- Base
exact、Baseupto、および注文支払いにはすべて公開して開ける explorer アドレスがあります。 - Base
uptoの署名上限は95215atomic USDC で、実際の settlement は3atomic USDC であり、後払い計量が実際の使用量に基づいて決済される特性を示しています。 - Solana
exactでは HTTP 402 -> HTTP 200 とモデル出力が検証されています。公開 RPC クエリはレート制限される可能性があるため、厳密な照合を行う際は自前の Solana RPC またはプラットフォーム側の決済記録を使用してトランザクション署名を確認することを推奨します。
統合時の注意事項
開発者が統合する際は、ドキュメント内のサンプル金額やアドレスをコピーするのではなく、現在のリクエストが返すリアルタイムの支払い要件を優先して確認してください:accepts[].maxAmountRequiredは、現在のリクエストで署名可能な最大金額です。accepts[].assetは、今回のリクエストで使用する USDC コントラクトまたは mint です。accepts[].extra.chainId、accepts[].extra.facilitatorAddress、およびaccepts[].extra.verifyingContractは EVM typed data 署名に関与します。uptoでは、ウォレットがまず対象チェーンの USDC を Permit2 に承認する必要があります。未承認の場合はPERMIT2_ALLOWANCE_REQUIREDが返されます。- 後払い計量を明示的に使用したい場合は、TypeScript SDK で
preferScheme: 'upto'を渡してください。そうしない場合、SDK はそのネットワークでサーバーが返した最初の利用可能な requirement を選択します。
公開検証できる範囲
統合前に、これらの公開エントリポイントと SDK の動作を先に検証できます:AuthorizationまたはPAYMENT-SIGNATUREを付与しない API リクエストは402 Payment Requiredを返し、レスポンス内のacceptsが今回のリクエストにおける唯一の署名根拠です。- TypeScript SDK と Python SDK はいずれも payment handler を提供しており、SDK のトランスポート層は 402 を受信すると handler を呼び出して一度再試行します。
https://facilitator.acedata.cloud/.well-known/x402:Facilitator がサポートするネットワーク、scheme、プロトコルエンドポイントを返します。API の価格は引き続き対象リクエストがリアルタイムで返す 402 に従います。https://facilitator.acedata.cloud/supported:Facilitator がサポートするネットワークと scheme を返します。- X402Client リポジトリには高度なオンチェーン検証ツールが含まれており、署名、再試行、settlement の動作を確認するために使用できます。ツールの出力はオンライン API が返す
acceptsの代わりにはなりません。
upto は後払い計量決済に属し、チャット補完、モデル呼び出しなど、実際の使用量がレスポンス後に判明する API に適しています。現在 upto を提供しているのは Base のみです。署名検証に失敗した場合は、chain id、facilitator アドレス、spender、USDC コントラクト、および Permit2 allowance が 402 レスポンスと一致しているか確認してください。
