メインコンテンツへスキップ
Facilitator は X402 フローにおけるサーバー側の決済コンポーネントです。クライアントは署名を担当し、Gateway またはあなたのサーバー側は Facilitator の /verify と /settle を呼び出します。 Ace Data Cloud の本番 Facilitator アドレス:
ソースコードリポジトリ:https://github.com/AceDataCloud/FacilitatorX402

v2 wire 規約

Ace Data Cloud の X402 フローはすべて公式の x402 v2 を使用しており、v1 の X-Payment リクエストヘッダーは受け付けなくなりました。統合時には以下の3点に注意が必要です:
  • リクエストヘッダーは PAYMENT-SIGNATURE であり、値は base64 エンコードされた JSON envelope です。
  • envelope のトップレベルは必ず x402Version: 2 であり、accepted オブジェクトを使用して今回選択した scheme と network を宣言します。
  • network は CAIP-2 識別子(例:eip155:8453)を使用し、base のような略称は使用できません。
envelope 構造:
402 レスポンスには JSON body に加え、PAYMENT-REQUIRED レスポンスヘッダーも含まれます。値は同じチャレンジ内容を base64 エンコードしたもので、クライアントが body を解析せずに支払い要件を読み取れるようにします。

コアインターフェース

GET /supported

サポートされているネットワークと scheme を確認します:
レスポンス例:
結果の説明:
  • network は CAIP-2 識別子を使用し、base、solana のような略称ではありません。
  • /supported は、Facilitator が対応する検証および決済能力を備えていることを示します。
  • Base と Solana はどちらも exact をサポートしています;upto は現在 Base でのみ提供されています。
  • signers は Facilitator が決済トランザクションを送信するために使用するアドレスです。
  • 特定の API がこれらのオプションを許可するかどうかは、引き続きその API の 402 accepts に従います。

POST /verify

クライアントから送信された PAYMENT-SIGNATURE が特定の payment requirement を満たしているかを検証します。 リクエストボディ:
v2 の paymentRequirements フィールドは scheme、network、asset、amount、payTo、maxTimeoutSeconds、および extra であり、金額フィールドは amount です。API の 402 レスポンスの accepts[] には、クライアントが上限を読み取れるよう maxAmountRequired も追加で返されますが、これは Facilitator のリクエストボディのフィールドには含まれません。 成功レスポンス:
本番注文支払いの PAYMENT-RESPONSE レスポンスヘッダーをデコードすると、settlement の結果が含まれます。Base 注文支払いのプログラム実行結果:
結果の説明:
  • success=True は Facilitator settlement が成功したことを示します。
  • transaction はオンチェーンのトランザクションハッシュであり、注文の pay_id にも同じ値が書き込まれます。
  • explorer では 1200000 atomic USDC の Base USDC 転送を確認できます。
  • errorReason=None は、この settlement で業務エラーが返されなかったことを示します。
検証失敗時も通常は HTTP 200 が返されますが、isValid は false です。業務側は HTTP ステータスコードだけを見るのではなく、invalidReason を読み取るべきです。

POST /settle

すでに検証済みの認可をオンチェーンに決済します。 リクエストボディは /verify とほぼ同じです。upto の違いは、paymentRequirements.amount が settle 時に実際の決済金額へ書き換えられることです;署名上限は Facilitator が verify 段階で記録し、settle 時に実際の金額がその上限を超えないことを検証します。 成功レスポンス:
upto の実際の金額が 0 の場合、transaction は空文字列になることがあり、オンチェーンのトランザクションを送信する必要がないことを示します。

Ace Data Cloud Gateway による Facilitator の使用方法

Ace Data Cloud API Gateway のフローは以下のとおりです:
  1. クライアントは初回の API リクエスト時に、Authorization と PAYMENT-SIGNATURE を付与しません。
  2. Gateway はリクエストの見積価格を計算し、402 と accepts を返します。
  3. クライアントは署名後、PAYMENT-SIGNATURE を付与して再試行します。
  4. Gateway は PAYMENT-SIGNATURE をデコードし、一致する payment requirement を選択します。
  5. Gateway は Facilitator /verify を呼び出します。
  6. /verify の成功後、Gateway はリクエストを対象 API に通過させます。
  7. 対象 API が返した後、Gateway は /record 段階で Facilitator /settle を呼び出します。
  8. Gateway はオンチェーンのトランザクションハッシュを使用記録の metadata に書き込みます。
exact はステップ 7 で署名金額を決済します;upto はステップ 7 で実際の使用量に基づいて amount を書き込み、その後実際の金額を決済します。

独自の API を統合する方法

独自の API で X402 をサポートさせたい場合は、この構造に従って実装できます:
  1. 各有料エンドポイント用に、ネットワーク、金額、受取先アドレス、資産アドレス、署名 domain を含む paymentRequirements を準備します。
  2. リクエストに PAYMENT-SIGNATURE がない場合、HTTP 402 と accepts を返します。
  3. リクエストに PAYMENT-SIGNATURE がある場合、Base64 デコードして paymentPayload を取得します。
  4. Facilitator /verify を呼び出します。
  5. 検証成功後、ビジネスロジックを実行します。
  6. ビジネス成功後、Facilitator /settle を呼び出します。
  7. 照合のために payer、transaction、amount、network を保存します。
サーバーは自ら生成した paymentRequirements を使って /verify と /settle を呼び出す必要があり、クライアントから返された金額、受取先アドレス、または資産アドレスを信頼してはいけません。

リプレイ保護

Facilitator は nonce を記録します。同じ nonce の認可は繰り返し検証および決済できません。 これは次を意味します:
  • クライアントはリクエストごとに新しい envelope に署名する必要があります;
  • /settle がトランザクションを送信済みであるものの一時的に未確認の場合、同じ nonce を使用して /settle を再試行し、冪等な照合を行えます;
  • 同じ PAYMENT-SIGNATURE をキャッシュして複数の API 呼び出しに使用しないでください。

よくあるエラー