跳轉到主要內容

​
title: ‘AFK API v1’ description: ‘AFK Crypto - 非託管錢包自動化 API’

​
概覽

  • 基礎路徑：/api/v1
  • 驗證：透過 x-api-key 傳遞 API Key
  • 冪等：寫入端點需要 Idempotency-Key（UUID）
  • 回應格式：所有回應包含 x-request-id 用於追蹤

​
端點

  • GET /api/v1/wallets – 列出使用者錢包
  • GET /api/v1/wallets/balances – 呼叫方錢包餘額（依鏈；預設使用預設錢包）
  • GET /api/v1/wallets/:address/balances – 查詢特定所屬錢包地址餘額
  • GET /api/v1/tx/:id – 取得交易詳情
  • POST /api/v1/send – 發送原生資產與代幣（EVM + Solana）
  • POST /api/v1/token/approve – ERC20 授權（僅 EVM）
  • POST /api/v1/contracts/send – 通用合約互動（僅 EVM）
  • POST /api/v1/trade/quote – 取得兌換報價（EVM + Solana）
  • POST /api/v1/trade/swap – 執行兌換（EVM + Solana）

​
鏈

完整清單見「支援的鏈」。在請求的 chain 欄位中使用鏈識別（例如 base、solana-devnet）。

​
頻率限制

  • 寫入（包含 POST /api/v1/trade/quote）：每使用者每分鐘 15 次請求
  • 讀取：每使用者每分鐘 60 次請求
  • 回應：超限回應 HTTP 429
  • 標頭：Retry-After（距離下一個視窗的秒數）

​
冪等（寫入）

  • 所有變更端點需要 Idempotency-Key。
  • 相同請求體重複使用相同 Key 會回傳原始 200 回應。
  • 若請求體不同，回傳 HTTP 409 與 code: IDEMPOTENT_BODY_MISMATCH。
  • 若無已存成功回應，回傳 HTTP 409 與 code: IDEMPOTENT_REPLAY。
  • Key 以使用者為範圍；端點路徑會被記錄以供追蹤。
  • 適用於：POST /api/v1/send、POST /api/v1/token/approve、POST /api/v1/contracts/send、POST /api/v1/trade/swap。

​
錯誤處理

​
錯誤回應格式

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "requestId": "unique-request-id"
}

​
錯誤代碼

  • UNAUTHORIZED – 缺少/無效驗證或 API 金鑰（HTTP 401）
  • FORBIDDEN – 已驗證但無權限執行操作（HTTP 403）
  • NOT_FOUND – 找不到資源（HTTP 404）
  • RATE_LIMITED – 超過頻率限制（HTTP 429）
  • INVALID_INPUT – 無效請求參數（HTTP 400）
  • WALLET_NOT_FOUND – 找不到指定錢包
  • USER_NOT_LINKED – 使用者未連結到 Privy
  • WALLET_NOT_DELEGATED – 錢包未委託給伺服器簽署者
  • WALLET_ID_REQUIRED – 缺少 Privy 錢包 ID
  • CHAIN_UNKNOWN – 未知或不支援的鏈
  • INSUFFICIENT_FUNDS – 發送方缺少資金用於支付價值/費用
  • IDEMPOTENT_BODY_MISMATCH – 相同冪等鍵但請求體不同（HTTP 409）
  • IDEMPOTENT_REPLAY – 冪等鍵已被使用（HTTP 409）
  • PRIVY_RPC_ERROR – Privy RPC 服務錯誤
  • SEND_FAILED – 交易提交失敗
  • SERVICE_UNAVAILABLE – 所需服務未配置
  • QUOTE_FAILED – 報價服務錯誤（HTTP 400）
  • INTERNAL_ERROR – 伺服器錯誤
QUOTE_FAILED 細節：
  • Solana/Jupiter：某些 Solana mint 在 Jupiter 上無法交易（經篩選的白名單）。這種情況下，此 API 回傳 HTTP 400，code: QUOTE_FAILED，錯誤訊息如：「Token not tradable on Jupiter」。
  • EVM/1inch：如果代幣不被 1inch 支援，API 回傳 HTTP 400，code: QUOTE_FAILED，訊息如：「Token not tradable on 1inch」。
  • 當請求的輸出代幣/mint 被上游提供商標記為無法交易時，這是預期行為，即使其他地方存在流動性池。

​
校驗

​
位址格式

  • EVM: must match /^0x[a-fA-F0-9]{40}$/
  • Solana: must be a valid base58 public key

​
通用參數

  • 數量（EVM）：僅整數字串（十進位或 0x-hex）。必須非負。對於 ERC20 和 value，必須適配 uint256。
  • 數量（Solana）：基本單位的整數字串。SPL 數量必須適配無符號 64 位元範圍。
  • 發送方（from）：可選。如省略，使用使用者針對指定鏈的預設錢包。
  • 冪等：所有寫入端點需要 Idempotency-Key 標頭。相同請求體的重複請求回傳原始回應。

​
原生代幣關鍵字

交易端點（/api/v1/trade/quote、/api/v1/trade/swap）接受不區分大小寫的 NATIVE 關鍵字用於 fromToken/toToken：
  • EVM：NATIVE 解析為 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
  • Solana：NATIVE 解析為包裝的 SOL mint So11111111111111111111111111111111111111112
  • 回應回傳解析後的地址（而非 NATIVE）
  • 發送端點使用 asset: "native" 而不是代幣地址來進行原生轉帳

​
約定

  • 鏈選擇：使用 chain 識別（如 base、base-sepolia、solana-devnet）。
  • Solana Transaction.chainId 守衛對應：0 = 主網，-2 = 測試網，-3 = 開發網。
  • 冪等：unique per user and key; repeats return the original response; mismatched bodies → 409.

​
相關

支援的鏈

策略與安全