跳轉到主要內容
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 請求標頭。接入時需要注意三點:
  • 請求標頭是 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。 請求 body:
v2 的 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 上可以看到 1200000 atomic USDC 的 Base USDC 轉帳。
  • errorReason=None 表示這次 settlement 沒有回傳業務錯誤。
驗證失敗通常也會回傳 HTTP 200,但 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 的鏈路如下:
  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. 為每個付費介面準備 paymentRequirements,包含網路、金額、收款地址、資產地址和簽名 domain。
  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 呼叫。

常見錯誤