Skip to main content
X402 は HTTP 402 Payment Required に基づくオンチェーン支払いプロトコルです。Ace Data Cloud の X402 機能を通じて、呼び出し元は API トークンを作成せず、アカウントの残高を事前にチャージすることなく、毎回の API リクエストで直接 USDC を使用してオンチェーン支払いを行うことができます。 このドキュメントは、実際の接続順序に従って整理されています：まず最小リクエストを通して、次に SDK を接続し、その後ネットワーク、料金プラン、注文支払い、Facilitator を理解します。以下の表に従って上から下へ読むことをお勧めします。

​
推奨接続パス

Ace Data Cloud API を呼び出したいだけの場合は、公式 SDK を優先して使用してください：
  • TypeScript：@acedatacloud/sdk + @acedatacloud/x402-client
  • Python：acedatacloud + acedatacloud-x402
公開ソースコードとパッケージのアドレス： SDK は最初の認証なしリクエスト、402 Payment Required の解析、支払いハンドラーの呼び出し、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、SKALE、Solana の利用可能な支払い方法が含まれています。
  • accepts[].network は CAIP-2 識別子であり、クライアントがネットワークを選択する際には CAIP-2 文字列に基づいて一致させる必要があります。
  • TypeScript SDK と Python SDK はどちらも 402 を自動的に処理し、支払いの再試行を完了します。
  • Base exact、SKALE exact、Base upto および注文支払いには公開可能なエクスプローラーのアドレスがあります。
  • Base upto の署名上限は 95215 atomic USDC であり、実際の決済は 3 atomic USDC で、後置計量が実際の使用量に基づいて決済される特性を示しています。
  • Solana exact は HTTP 402 -> HTTP 200 とモデル出力を検証しました。公開 RPC クエリが制限される可能性があるため、厳密な照合を行う際には独自の Solana RPC またはプラットフォーム側の決済記録を使用して取引署名を確認することをお勧めします。

​
接続時の注意事項

開発者が接続する際は、ドキュメント内のサンプル金額やアドレスをコピーするのではなく、現在のリクエストが返すリアルタイムの支払い要件に優先的に注意してください：
  • accepts[].maxAmountRequired は現在のリクエストで署名可能な最大金額です。
  • accepts[].asset は今回のリクエストで使用する USDC コントラクトまたはミントです。
  • accepts[].extra.chainId、accepts[].extra.facilitatorAddress および accepts[].extra.verifyingContract は EVM タイプデータの署名に関与します。
  • upto では、ウォレットが最初にターゲットチェーンの USDC に対して Permit2 を承認する必要があります。未承認の場合は PERMIT2_ALLOWANCE_REQUIRED が返されます。
  • 明示的に後置計量を使用したい場合は、TypeScript SDK に preferScheme: 'upto' を渡してください。そうでない場合、SDK はそのネットワークでサーバーが返した最初の利用可能な要件を選択します。

​
公開検証可能な範囲

接続前にこれらの公開エンドポイントと SDK の動作を検証できます：
  • Authorization または PAYMENT-SIGNATURE を持たない API リクエストは 402 Payment Required を返し、レスポンス内の accepts は今回のリクエストの唯一の署名根拠です。
  • TypeScript SDK と Python SDK はどちらも支払いハンドラーを提供し、SDK のトランスポート層は 402 を受け取るとハンドラーを呼び出し、再試行を行います。
  • https://facilitator.acedata.cloud/.well-known/x402：ファシリテーターがサポートするネットワーク、スキーム、およびプロトコルエンドポイントを返します。API 価格は依然としてターゲットリクエストがリアルタイムで返す 402 に基づきます。
  • https://facilitator.acedata.cloud/supported：ファシリテーターがサポートするネットワークとスキームを返します。
  • X402Client リポジトリには、高度なチェーン上検証ツールが含まれており、署名、再試行、および決済動作を確認するために使用できます。ツールの出力はオンライン API が返す accepts を代替するものではありません。
upto は後置計量決済に属し、チャット補完、モデル呼び出しなど、実際の使用量が応答後にのみわかる API に適しています。現在、Base のみが upto を提供しています。署名検証が失敗した場合は、チェーン ID、ファシリテーターアドレス、支出者、USDC コントラクト、および Permit2 アローワンスが 402 レスポンスと一致しているか確認してください。