> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afkcrypto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

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）

## 鏈

完整清單見「[支援的鏈](/api-reference/supported-chains/)」。在請求的 `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`。

## 錯誤處理

### 錯誤回應格式

```json theme={null}
{
  "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` – 伺服器錯誤

<Note>
  **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 被上游提供商標記為無法交易時，這是預期行為，即使其他地方存在流動性池。
</Note>

## 校驗

### 位址格式

* 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.

## 相關

<CardGroup cols={2}>
  <Card title="支援的鏈" icon="link-simple" href="/api-reference/supported-chains/" />

  <Card title="策略與安全" icon="shield" href="/api-reference/policies-security/" />
</CardGroup>