/verify と /settle を呼び出します。
Ace Data Cloud の本番 Facilitator アドレス:
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のような略称は使用できません。
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 を満たしているかを検証します。
リクエストボディ:
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 では
1200000atomic USDC の Base USDC 転送を確認できます。 errorReason=Noneは、この settlement で業務エラーが返されなかったことを示します。
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 のフローは以下のとおりです:- クライアントは初回の API リクエスト時に、
AuthorizationとPAYMENT-SIGNATUREを付与しません。 - Gateway はリクエストの見積価格を計算し、402 と
acceptsを返します。 - クライアントは署名後、
PAYMENT-SIGNATUREを付与して再試行します。 - Gateway は
PAYMENT-SIGNATUREをデコードし、一致する payment requirement を選択します。 - Gateway は Facilitator
/verifyを呼び出します。 /verifyの成功後、Gateway はリクエストを対象 API に通過させます。- 対象 API が返した後、Gateway は
/record段階で Facilitator/settleを呼び出します。 - Gateway はオンチェーンのトランザクションハッシュを使用記録の metadata に書き込みます。
exact はステップ 7 で署名金額を決済します;upto はステップ 7 で実際の使用量に基づいて amount を書き込み、その後実際の金額を決済します。
独自の API を統合する方法
独自の API で X402 をサポートさせたい場合は、この構造に従って実装できます:- 各有料エンドポイント用に、ネットワーク、金額、受取先アドレス、資産アドレス、署名 domain を含む
paymentRequirementsを準備します。 - リクエストに
PAYMENT-SIGNATUREがない場合、HTTP 402 とacceptsを返します。 - リクエストに
PAYMENT-SIGNATUREがある場合、Base64 デコードしてpaymentPayloadを取得します。 - Facilitator
/verifyを呼び出します。 - 検証成功後、ビジネスロジックを実行します。
- ビジネス成功後、Facilitator
/settleを呼び出します。 - 照合のために
payer、transaction、amount、networkを保存します。
paymentRequirements を使って /verify と /settle を呼び出す必要があり、クライアントから返された金額、受取先アドレス、または資産アドレスを信頼してはいけません。
リプレイ保護
Facilitator は nonce を記録します。同じ nonce の認可は繰り返し検証および決済できません。 これは次を意味します:- クライアントはリクエストごとに新しい envelope に署名する必要があります;
/settleがトランザクションを送信済みであるものの一時的に未確認の場合、同じ nonce を使用して/settleを再試行し、冪等な照合を行えます;- 同じ
PAYMENT-SIGNATUREをキャッシュして複数の API 呼び出しに使用しないでください。

