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

# AFK API v1

> AFK Crypto API v1 概览与约定

## 概览

* 基础路径：`/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` = 开发网。
* 幂等：对每位用户与 Key 唯一；重复请求返回原始响应；请求体不一致 → 409。

## 相关

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

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