/verify 和 /settle。
Ace Data Cloud 的生產 Facilitator 位址為:
v2 wire 約定
Ace Data Cloud 的 X402 鏈路已全面使用官方 x402 v2,不再接受 v1 的X-Payment 請求標頭。接入時需要注意三點:
- 請求標頭是
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。
請求 body:
paymentRequirements 欄位是 scheme、network、asset、amount、payTo、maxTimeoutSeconds 和 extra,金額欄位是 amount。API 402 回應的 accepts[] 中還會額外回傳 maxAmountRequired 供用戶端讀取上限,但它不屬於 Facilitator 請求 body 的欄位。
成功回應:
PAYMENT-RESPONSE 回應標頭解碼後包含 settlement 結果。Base 訂單支付的程式執行結果:
success=True表示 Facilitator settlement 成功。transaction是鏈上交易雜湊,訂單的pay_id也寫入相同的值。- explorer 上可以看到
1200000atomic USDC 的 Base USDC 轉帳。 errorReason=None表示這次 settlement 沒有回傳業務錯誤。
isValid 為 false。業務端應該讀取 invalidReason,而不是只看 HTTP 狀態碼。
POST /settle
將已經驗證過的授權結算到鏈上。
請求 body 與 /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,可以按照這個結構實作:- 為每個付費介面準備
paymentRequirements,包含網路、金額、收款地址、資產地址和簽名 domain。 - 如果請求沒有
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 呼叫。

