跳轉到主要內容
Ace Data Cloud X402 目前圍繞 USDC 結算,支援 EVM 和 Solana 兩類鏈。不同網路的簽名方式、資產地址、gas 行為和適用場景不同,接入前需要先選好網路。

網路標識使用 CAIP-2

x402 v2 的 accepts[].network 是 CAIP-2 標識,不是 base、solana 這類簡稱。客戶端比對網路時必須按 CAIP-2 字串比較:

支援矩陣

upto 目前只在 Base 上提供。實際可用項以 API 傳回的 accepts 為準。你也可以查看 Facilitator:
Facilitator /supported 的傳回:
結果說明:
  • Base 和 Solana 的 exact 是固定金額支付路徑。
  • 只有 Base 提供 upto 後置計量路徑,依賴 Permit2 approve。
  • upto 條目裡的 extra.facilitatorAddress 是客戶端簽名時要寫入 witness 的地址,必須和伺服器端傳回值一致。

Base

Base 使用官方 USDC 合約:
exact 方案中,客戶端簽署 EIP-712 TransferWithAuthorization。簽名內容包括:
  • from:付款錢包地址
  • to:Ace Data Cloud 收款地址
  • value:本次支付金額
  • validAfter / validBefore:簽名有效時間視窗
  • nonce:32 位元組隨機 nonce
Facilitator 驗證簽名後,會在鏈上呼叫 USDC 的 transferWithAuthorization 完成轉帳。 Base 是最推薦的正式接入網路,尤其適合 upto 後置計量,因為 Permit2、USDC 和錢包生態都更成熟。 Base exact 驗證結果範例:
結果說明:
  • API paid retry 傳回模型內容 ADC_BASE_E2E_OK。
  • 鏈上交易已在 BaseScan 可查,區塊號是 46726299。
  • 95215 atomic USDC 對應 0.095215 USDC,是這次 API 呼叫的實際結算金額。
訂單支付 Base exact 的程式執行結果:
結果說明:
  • 平台訂單最終狀態是 Finished。
  • 訂單 pay_id 寫入同一個 Base 交易雜湊。
  • 1200000 atomic USDC 對應 1.2 USDC,是舊政策下該筆 10 Credits 訂單的歷史實付金額;新訂單不再額外享受 X402 支付方式折扣,具體簽名金額以本次 402 回應為準。

Solana

Solana 使用 SPL USDC TransferChecked。客戶端會建構一筆轉帳交易,簽名並提交,之後把交易簽名或序列化交易放入 PAYMENT-SIGNATURE envelope。 Solana 的特點:
  • 使用 Solana wallet adapter 或 base58 secret key;
  • 資產是 Solana USDC mint;
  • 目前只支援 exact;
  • Facilitator 會校驗 transfer instruction 的 mint、destination、authority 和 amount。
如果使用錢包 fee payer 模式,錢包會直接提交交易,Facilitator 負責確認交易並傳回 settlement 結果。 Solana exact 驗證結果範例:
結果說明:
  • paid retry 已經傳回 HTTP 200,並且模型輸出 ADC_SOLANA_E2E_OK。
  • 公開 RPC 查詢鏈上 signature 時可能遇到限流。
  • 因為公開 RPC 查詢可能限流,這裡不寫 Solana explorer。需要嚴格對帳時,請使用自有 Solana RPC 或平台端結算記錄確認交易簽名。

如何選擇

無論選擇哪條鏈,都不要在客戶端硬編碼價格。價格由伺服器傳回的 accepts[].maxAmountRequired 決定。

新增 EVM 網路

以下網路的原生 USDC 固定金額支付已提供程式碼支援,依網路逐一開放。 是否可用以訂單或 API 回傳的 accepts 為準;不代表所有網路已在正式環境啟用。 這些網路僅支援 exact,幣種精度為 6。不要使用同名的橋接 USDC。 使用官方 TypeScript/Python X402 Client 時,可以傳入表中的簡稱或 CAIP-2 識別碼。 用戶端使用目標鏈 ID 建構簽章;錢包必須支援目標網路。 Phantom 擴充功能錢包的官方支援表列出了 Arbitrum 和 Polygon;Optimism、Avalanche 目前未列入該表,可使用支援目標鏈的 Rabby 或 MetaMask。EVM 位址可以在不同鏈上相同, 但餘額彼此獨立,Solana 位址不適用於 EVM USDC。 請參閱 Phantom 錢包支援表。

新網路灰度入口

新鏈入口預設隱藏。存取控制台或 Studio 時,可使用 ?features=x402-arbitrum 開啟對應鏈,多個 flag 以逗號分隔。關閉單鏈使用 ?features=-x402-arbitrum, 清除本機覆寫使用 ?features=none。每個網域分別儲存開關。 訂單報價和付款重試使用相同開關,伺服器端會獨立驗證;既有付款紀錄仍可查看。 僅開啟頁面 flag 不會啟用尚未設定的鏈,具體可支付網路仍以即時 accepts 為準。