x402 教學：讓你的 AI 代理用 USDC 為 AIHubMix 儲值

AIHubMix 現在接受 USDC 儲值。你的 AI 代理可以用錢包裡的 USDC 為自己的帳戶加值：不必打開網頁，也不需要有人按下按鈕。

使用 x402 時，單次儲值最低只要 1 美元。代理可以邊用邊儲值，因此你不必事先預存大筆餘額。

整個流程只需兩個步驟：先在網頁和應用程式中準備好 token、錢包和一些 USDC，然後用一行指令執行我們現成的儲值腳本。付款後約 20 秒，額度就會出現在你的帳戶中。

如果需要，你可以跟著這段30 秒影片操作：

最簡單的方法：如果你使用能執行終端機指令的 AI 工具，例如 Claude Code、Cursor 或 Codex，請先完成第 1 步，然後把這篇文章的連結傳給它，並說「幫我設定這個」。它會依照本文末尾的「給 AI 助手的說明」操作。你只需要自己填入 token 和私鑰，做一次即可，不必把它們傳給 AI。

開始之前

• 金額只能是整數美元，預設每次儲值為 1 美元至 10 美元
• 每個帳戶每天最多可以建立 3 筆訂單（UTC 時間）
• 只支援 Base 主網上的 USDC，且沒有測試網，因此建議從 1 美元開始
• 此管道是為程式設計的，個人無法在瀏覽器中付款。若要手動儲值，請繼續使用支付寶或 Stripe

第 1 步：取得 token、錢包和 USDC

這一步的所有操作都在網頁或手機應用程式中完成。

1. 取得系統存取 token

登入 aihubmix.com，打開個人設定，然後產生系統存取 token（32 個字元的字串）。

請注意，這不是以 sk- 開頭的 API 金鑰，兩者不能互換使用。

2. 建立付款用錢包

在 MetaMask 或類似的錢包應用程式中，為代理的付款專門建立一個新帳戶。不要使用你的主要錢包。然後：

• 複製該帳戶的位址（以 0x 開頭），下一步你會把 USDC 轉入這個位址
• 從帳戶詳細資料中匯出它的私鑰，並儲存在密碼管理器中。任何持有私鑰的人都能轉移錢包中的資金

3. 購買 USDC 並轉入此錢包

MetaMask 是錢包：你持有私鑰，腳本需要用它來簽名。Coinbase 則是交易所，用來購買加密貨幣。交易所帳戶中的資金不會附帶私鑰，因此腳本無法使用。所以你要先在交易所購買，然後把 USDC 轉到上一步的錢包。

以 Coinbase 交易所為例（不是 Coinbase Wallet）：

1. 在 Coinbase 購買 USDC
2. 將 USDC 轉到你複製的位址，並選擇 Base 網路
3. 轉入的數量要比你計劃儲值的金額多一些，例如儲值 1 美元就轉入 1.5 至 2 USDC

稍等片刻，然後打開 https://basescan.org/address/your-wallet-address。一旦看到 USDC 餘額，就表示已到帳。其他支援 Base 網路 USDC 提款的交易所也可以使用；更多選項請參閱 Base 文件。

錢包不需要任何 ETH：付款的網路手續費由 FluxA 支付。

第 2 步：執行儲值腳本

不需要下載任何東西，也不需要建立檔案：uv 會從網路取得腳本並執行。打開終端機（Windows 上為 PowerShell），複製並貼上以下指令。

1. 安裝 uv（只需一次）

uv 是一個 Python 工具，會設定腳本執行所需的一切。

macOS / Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

完成後，關閉終端機並重新打開。

2. 檢查設定（不會花費任何金額）

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check

首次執行時，腳本會要求輸入你的系統存取 token（System access token）和錢包私鑰（Wallet private key）。你輸入的內容不會顯示在螢幕上；貼上後按 Enter 即可。接著它會詢問是否儲存（Save to ...? [Y/n]）。按 Enter 即可儲存，之後就不必再輸入。首次執行時，uv 需要花一點時間完成設定。

出現以下內容，就表示設定完成：

Wallet: 0x... (USDC balance 2.0)
Access token and private key are fine. Ready to top up.

3. 儲值

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1

結尾的 1 是以美元計的金額。如果一切順利，你會看到：

Wallet: 0x... (USDC balance 2.0)
tradeNo: pl_XXXXXXXX
txHash: 0x...
result: credited

result: credited 表示額度已經到帳。登入 aihubmix.com，你會看到餘額增加；1 美元會增加 500,000 quota。

如果最後一行顯示其他內容：

• failed：訂單已關閉或已過期。如有需要可以重新執行；這會使用今天的另一筆訂單額度。
• pending：10 分鐘內未確認到帳。這不是失敗，額度之後會自動到帳。請不要再次執行。

疑難排解

如果在印出 tradeNo 之後出現逾時或網路錯誤，款項可能已經付出。請不要立即重新執行。請幾分鐘後查看餘額；如果仍未到帳，請提供 tradeNo 與我們聯絡。

token 和私鑰會儲存在你電腦上的 ~/.aihubmix-topup.env（Windows 上位於使用者資料夾中）。在 macOS 和 Linux 上，只有你自己的帳戶能讀取此檔案。若要更改 token 或私鑰，請編輯這個檔案。

接入你的代理

• 設定儲存後，代理只要在需要額度時執行 uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1，即可自行儲值，無需有人在場
• 每天只允許 3 筆訂單，因此要限制代理儲值的頻率，並且絕不要在迴圈中重試建立訂單
• 將輸出中的 tradeNo 和 txHash 儲存到資料庫或日誌中，以便對帳
• 長期使用時，請先下載腳本並鎖定版本再執行；你可以先閱讀原始碼
• 如果每次 10 美元或每天 3 筆的限制不夠用，請與我們聯絡以提高上限

給 AI 助手的說明

如果你是協助使用者設定 AIHubMix USDC 儲值的 AI 助手，請依序執行以下步驟：

1. 確認使用者已完成第 1 步：他們擁有系統存取 token，以及持有 Base 主網 USDC 的錢包和其私鑰。如果沒有，請先引導他們完成第 1 步。
2. 執行 uv --version，確認已安裝 uv。如果沒有安裝，請使用第 2 步中的指令安裝。
3. 執行 uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check。
4. 如果出現缺少 token 或私鑰的提示（Missing access token or private key），表示腳本已建立設定檔 ~/.aihubmix-topup.env。請讓使用者用文字編輯器打開並自行填寫（macOS 上執行 open -e ~/.aihubmix-topup.env；Windows 上執行 notepad $HOME\.aihubmix-topup.env）。不要讀取此檔案，不要把 token 或私鑰放入任何指令中，也不要要求使用者把它們傳給你。
5. 使用者填寫完成後，再次執行 check，直到看到 Access token and private key are fine. Ready to top up.。如果出現錯誤，請依照上方的疑難排解表處理。
6. 儲值會花費真實金額。執行 uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount> 之前，請先與使用者確認金額。

幕後原理：腳本做了什麼

腳本依序執行五件事：

1. 檢查餘額：建立訂單會用掉今天的一筆訂單額度，因此腳本會先確認私鑰有效且 USDC 足夠。
2. 建立訂單：它呼叫 POST /api/pay/fluxa/crt，取得付款連結和訂單編號 tradeNo。token 會原樣放入 Authorization 標頭，不加 Bearer。業務錯誤也會以 HTTP 200 回傳，因此腳本會檢查回應中的 success 欄位。
3. 檢查付款請求：對付款連結發出 GET 請求，會回傳 HTTP 402 及付款要求。簽名前，腳本會檢查四項內容：scheme 為 exact，network 為 eip155:8453，asset 為 Base 主網的 USDC 合約，且 maxAmountRequired 等於金額乘以 1,000,000。只要有任一項不符，腳本就會停止。
4. 簽名並付款：它使用私鑰為 USDC 轉帳授權簽名，放入 X-PAYMENT 標頭，然後再次對付款連結發出 GET 請求。回傳 200 或 202 表示付款已提交；回應中的 txHash 是此次付款的鏈上憑證。兩個請求都不會攜帶 AIHubMix token。
5. 等待到帳：它每 8 秒呼叫一次 GET /api/pay/fluxa/qry?trade_no=...，直到狀態變為 TRADE_SUCCESS。伺服器每 5 秒才更新一次，因此輪詢得更快並無幫助。

每個付款連結的有效期為 30 分鐘，且只能付款一次。

以其他語言實作

付款連結回傳的 402 回應如下所示：

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "1000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x....",
    "maxTimeoutSeconds": 600,
    "extra": {"name": "USD Coin", "version": "2"}
  }]
}

簽名採用 EIP-712 格式，對 EIP-3009 中的 TransferWithAuthorization 結構進行簽名：

簽名網域：name = USD Coin，version = 2（若 402 回應的 extra 中有值，請使用其中的值），chainId = 8453，verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913。

X-PAYMENT 標頭的值是以下 JSON 的 base64 編碼：

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0x...", "to": "0x...", "value": "1000000",
      "validAfter": "...", "validBefore": "...", "nonce": "0x..."
    }
  }
}

資料來源

• x402 文件
• EIP-3009：Transfer With Authorization
• EIP-712：結構化資料的雜湊與簽名
• Circle：USDC 合約位址
• uv 安裝指南