跳轉到主要內容
Python SDK 適合後端服務、資料任務、自動化 Agent 和批次處理指令碼。acedatacloud 負責 API 呼叫,acedatacloud-x402 負責簽出 PAYMENT-SIGNATURE 請求標頭。 原始碼與套件位址:

安裝相依套件

如果要使用 upto,還需要一次性呼叫 Permit2 approve CLI,該 CLI 相依於 web3:
乾淨 Python venv 的安裝和匯入檢查輸出:
結果說明:
  • acedatacloud 和 acedatacloud-x402 均可從 PyPI 安裝並匯入。
  • pip install 'acedatacloud-x402[cli]' 會附帶 approve-permit2 CLI,用於 upto 前置授權。

Base 範例

下面範例不需要 API Token。錢包私鑰只在本機簽名,不會傳送給 Ace Data Cloud。
Python SDK 目前回傳的是 dict,所以範例使用 res["choices"][0]["message"]["content"]。不要直接假設它一定有 .choices 屬性。

Solana 範例

Solana 使用 base58 編碼的 secret key:
Solana 路徑會建構並提交 SPL USDC TransferChecked 交易,然後把交易簽名放入 PAYMENT-SIGNATURE envelope。 Solana paid retry 在生產 API 上已回傳 HTTP 200 和 ADC_SOLANA_E2E_OK。本次公開 RPC 查詢遇到限流,未穩定確認鏈上 signature;需要對帳時請使用你自己的 Solana RPC 查詢該次交易。

Async 用戶端

同一個 payment handler 可以用於 AsyncAceDataCloud:

使用 upto 後置計量

聊天補全、模型呼叫等 API 的實際成本可能需要等回應結束後才知道。此時 API 可能同時回傳 exact 和 upto。如果要優先使用 upto:
Base upto 的程式執行結果:
鏈上確認:
結果說明:
  • content ADC_BASE_UPTO_OK 說明請求實際進入模型 API。
  • settled value 3 atomic USDC 說明 upto 按實際用量結算,而不是扣除完整上限。
  • settlement tx 可在 BaseScan 開啟,對帳時儲存 tx hash、payer、completion id 和請求摘要。
upto 使用 Permit2 授權一個上限,實際結算金額不能超過該上限。第一次使用前,需要對目標鏈上的 USDC 做一次 approve(Permit2, amount)。 CLI 方式:
程式方式:
該 helper 是冪等的。如果 allowance 已經足夠,會回傳 {"skipped": true},不會重複發送鏈上交易。

低階簽名

如果你不使用 SDK,也可以直接呼叫低階簽名函式:
低階函式適合測試、代理層、閘道整合或非官方 SDK。一般業務程式碼優先使用 create_x402_payment_handler。