網路標識使用 CAIP-2
x402 v2 的accepts[].network 是 CAIP-2 標識,不是 base、solana 這類簡稱。客戶端比對網路時必須按 CAIP-2 字串比較:
支援矩陣
upto 目前只在 Base 上提供。實際可用項以 API 傳回的 accepts 為準。你也可以查看 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
transferWithAuthorization 完成轉帳。
Base 是最推薦的正式接入網路,尤其適合 upto 後置計量,因為 Permit2、USDC 和錢包生態都更成熟。
Base exact 驗證結果範例:
- API paid retry 傳回模型內容
ADC_BASE_E2E_OK。 - 鏈上交易已在 BaseScan 可查,區塊號是
46726299。 95215atomic USDC 對應0.095215USDC,是這次 API 呼叫的實際結算金額。
exact 的程式執行結果:
- 平台訂單最終狀態是
Finished。 - 訂單
pay_id寫入同一個 Base 交易雜湊。 1200000atomic USDC 對應1.2USDC,是舊政策下該筆 10 Credits 訂單的歷史實付金額;新訂單不再額外享受 X402 支付方式折扣,具體簽名金額以本次 402 回應為準。
Solana
Solana 使用 SPL USDCTransferChecked。客戶端會建構一筆轉帳交易,簽名並提交,之後把交易簽名或序列化交易放入 PAYMENT-SIGNATURE envelope。
Solana 的特點:
- 使用 Solana wallet adapter 或 base58 secret key;
- 資產是 Solana USDC mint;
- 目前只支援
exact; - Facilitator 會校驗 transfer instruction 的 mint、destination、authority 和 amount。
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 為準。
