accepts には何があるのか、そして PAYMENT-SIGNATURE はどのようにして同じ API リクエストを支払い済みリクエストに変えるのか。
準備
以下を準備する必要があります:
X402 で Ace Data Cloud API を呼び出す際に API Token は不要です。SDK の最初のリクエストには
Authorization が含まれず、Gateway は 402 Payment Required と支払い要件を返します;SDK は署名後に自動で再試行します。
SDK のインストール
ソースコードとパッケージのアドレス:- SDK リポジトリ:https://github.com/AceDataCloud/SDK
- X402 Client リポジトリ:https://github.com/AceDataCloud/X402Client
- npm:
@acedatacloud/sdk、@acedatacloud/x402-client - PyPI:
acedatacloud、acedatacloud-x402
acedatacloud-x402 に含まれています。
クリーンな一時環境でのインストールおよびインポート確認の出力:
- npm パッケージと PyPI パッケージはいずれも実際に公開されているパッケージであり、ドキュメント内のプレースホルダー名ではありません。
acedatacloud-x402[cli]は CLI をインストールし、approve-permit2サブコマンドはuptoシナリオでの Permit2 承認に使用できます。
最初のリクエストは 402 を返します
まずcurl を使って、未払いリクエストが何を返すか確認できます。以下の例では PAYMENT-SIGNATURE を含めていないため、課金は発生しません:
accepts 配列が含まれ、一般的な構造は以下のとおりです:
PAYMENT-REQUIRED レスポンスヘッダーに格納され、クライアントが body を解析せずに支払い要件を読み取れるようになっています。
本番 API の未払いリクエストに対するプログラム出力の要約は以下のとおりです:
- 最初のリクエストには
AuthorizationまたはPAYMENT-SIGNATUREが含まれていないため、HTTP 402 が返され、課金は発生しません。 acceptsは今回のリクエストにおける唯一信頼できる署名の根拠であり、選択可能なネットワーク、scheme、金額上限、受取先アドレス、および資産アドレスを含みます。networkは CAIP-2 識別子であり、クライアントはネットワークを選択する際に CAIP-2 文字列で一致させる必要があります。- 今回の
gpt-4o-miniの最小チャットリクエストの上限金額は95215atomic USDC、つまり0.095215USDC です。 - 毎回のリクエストでその時の 402 レスポンスを読み取るべきであり、サンプル金額を業務コードにハードコードしないでください。
SDK を使用して支払い再試行を完了する
以下は最小の TypeScript の例です。network: 'base' を指定しており、handler は今回の 402 レスポンスから Base の payment requirement を選択します;実際の金額と受取先アドレスは引き続き accepts に従います:
- SDK は、
Authorizationを付けずに通常の API リクエストを送信します。 - Gateway は
402 Payment Requiredとacceptsを返します。 createX402PaymentHandlerはnetwork = 'base'の payment requirement を選択し、PAYMENT-SIGNATUREを署名します。- SDK は同じリクエストボディで再試行し、Gateway は Facilitator を呼び出して検証と決済を行った後、対象 API へのアクセスを許可します。
Facilitator のサポート機能を確認する
X402 API はリソースディレクトリに依存しません。クライアントは既知の API を直接呼び出し、そのリクエストによってリアルタイムで返される402 Payment Required と accepts を唯一の価格および署名の根拠とします。
Facilitator の機能宣言は以下にあります:
/supported、/verify、/settle および現在有効な支払いネットワークのみを説明しており、API リソースは列挙しません。
Ace Data Cloud の本番 Facilitator アドレスは以下です:
kinds には、Facilitator がサポートするネットワークと scheme が列挙されます。実際の呼び出し時には、引き続き API が返す accepts を基準とします。
Facilitator の /supported 出力:
/supportedは、Facilitator がこれらのネットワークと scheme の検証・決済機能を備えていることを示します。- Base と Solana はどちらも
exactをサポートしています。uptoは現在 Base でのみ提供されています。 - 特定の API があるネットワークを許可するかどうかは、引き続きその API の 402
acceptsを基準とします。

