メインコンテンツへスキップ
このチュートリアルでは、最小限の API リクエストを使って Ace Data Cloud X402 の完全なフローを説明します。目的は先に複雑なコードを書くことではなく、まず理解することです:なぜ最初のリクエストは 402 を返すのか、accepts には何があるのか、そして PAYMENT-SIGNATURE はどのようにして同じ API リクエストを支払い済みリクエストに変えるのか。

準備

以下を準備する必要があります: X402 で Ace Data Cloud API を呼び出す際に API Token は不要です。SDK の最初のリクエストには Authorization が含まれず、Gateway は 402 Payment Required と支払い要件を返します;SDK は署名後に自動で再試行します。

SDK のインストール

ソースコードとパッケージのアドレス: TypeScript:
Python:
Solana を使用する場合は、対応する依存関係もインストールする必要があります:
Python バージョンの Solana signer 依存関係はすでに acedatacloud-x402 に含まれています。 クリーンな一時環境でのインストールおよびインポート確認の出力:
結果の説明:
  • npm パッケージと PyPI パッケージはいずれも実際に公開されているパッケージであり、ドキュメント内のプレースホルダー名ではありません。
  • acedatacloud-x402[cli] は CLI をインストールし、approve-permit2 サブコマンドは upto シナリオでの Permit2 承認に使用できます。

最初のリクエストは 402 を返します

まず curl を使って、未払いリクエストが何を返すか確認できます。以下の例では PAYMENT-SIGNATURE を含めていないため、課金は発生しません:
レスポンスボディには accepts 配列が含まれ、一般的な構造は以下のとおりです:
同じチャレンジ内容は base64 形式でも PAYMENT-REQUIRED レスポンスヘッダーに格納され、クライアントが body を解析せずに支払い要件を読み取れるようになっています。 本番 API の未払いリクエストに対するプログラム出力の要約は以下のとおりです:
結果の説明:
  • 最初のリクエストには Authorization または PAYMENT-SIGNATURE が含まれていないため、HTTP 402 が返され、課金は発生しません。
  • accepts は今回のリクエストにおける唯一信頼できる署名の根拠であり、選択可能なネットワーク、scheme、金額上限、受取先アドレス、および資産アドレスを含みます。
  • network は CAIP-2 識別子であり、クライアントはネットワークを選択する際に CAIP-2 文字列で一致させる必要があります。
  • 今回の gpt-4o-mini の最小チャットリクエストの上限金額は 95215 atomic USDC、つまり 0.095215 USDC です。
  • 毎回のリクエストでその時の 402 レスポンスを読み取るべきであり、サンプル金額を業務コードにハードコードしないでください。
フィールドの意味:

SDK を使用して支払い再試行を完了する

以下は最小の TypeScript の例です。network: 'base' を指定しており、handler は今回の 402 レスポンスから Base の payment requirement を選択します;実際の金額と受取先アドレスは引き続き accepts に従います:
このコードの背後では、4つのステップが発生します:
  1. SDK は、Authorization を付けずに通常の API リクエストを送信します。
  2. Gateway は 402 Payment Required と accepts を返します。
  3. createX402PaymentHandler は network = 'base' の payment requirement を選択し、PAYMENT-SIGNATURE を署名します。
  4. SDK は同じリクエストボディで再試行し、Gateway は Facilitator を呼び出して検証と決済を行った後、対象 API へのアクセスを許可します。

Facilitator のサポート機能を確認する

X402 API はリソースディレクトリに依存しません。クライアントは既知の API を直接呼び出し、そのリクエストによってリアルタイムで返される 402 Payment Required と accepts を唯一の価格および署名の根拠とします。 Facilitator の機能宣言は以下にあります:
これは /supported、/verify、/settle および現在有効な支払いネットワークのみを説明しており、API リソースは列挙しません。 Ace Data Cloud の本番 Facilitator アドレスは以下です:
サポートしているネットワークと scheme は以下で確認できます:
返される kinds には、Facilitator がサポートするネットワークと scheme が列挙されます。実際の呼び出し時には、引き続き API が返す accepts を基準とします。 Facilitator の /supported 出力:
結果の説明:
  • /supported は、Facilitator がこれらのネットワークと scheme の検証・決済機能を備えていることを示します。
  • Base と Solana はどちらも exact をサポートしています。upto は現在 Base でのみ提供されています。
  • 特定の API があるネットワークを許可するかどうかは、引き続きその API の 402 accepts を基準とします。