<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 实时汇率查询

> 实时汇率查询，支持 26 种主流货币（CNY/USD/EUR/GBP/JPY 等）一键互转。数据 1 分钟级更新，毫秒响应，免费且无需注册即可调用。

基于 ALAPI 汇率源，覆盖人民币、美元、欧元、英镑、日元、港币、韩元、澳元、加元、新加坡元、瑞士法郎、新台币、泰铢、马来西亚林吉特、俄罗斯卢布、印度卢比、巴西雷亚尔、南非兰特、新西兰元、瑞典/挪威/丹麦克朗、菲律宾比索、印尼盾、越南盾、阿联酋迪拉姆等。

支持「同币种快路径」（from=to 时本地直接返回，0 上游消耗），以及「货币列表查询」action=currencies 子命令（返回支持的全部 26 种货币代码与中文名）。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `exchange-rate` |
| 接口名称 | 实时汇率查询 |
| 接口地址 | `https://v1.apizero.cn/api/exchange-rate` |
| 请求方法 | `GET` |
| 分类 | finance |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 5 req/s |
| 每日免费额度 | 200 次（已认证用户） |
| 匿名每日额度 | 50 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名每日 50 次、QPS 2；登录用户每日 200 次、QPS 5（全部免费）。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `money` | `number` | 否 | 要转换的金额，必须 > 0；缺省 1 | — |
| `from` | `string` | 否 | 源货币代码（ISO 4217 三字母），如 CNY、USD、EUR；缺省 CNY | `CNY` |
| `to` | `string` | 否 | 目标货币代码（ISO 4217 三字母），如 USD、JPY；缺省 USD | `USD` |
| `action` | `string` | 否 | 传 "currencies" 直接返回 26 种支持货币列表（不调上游、不计费） | `currencies` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | API Key 鉴权头，格式 Bearer sk_live_xxx；匿名调用时可省略（每日 50 次免费） | `Bearer sk_live_xxxxxxxxxxxxxx` |

## 5. 请求示例 (cURL)

```bash
curl "https://v1.apizero.cn/api/exchange-rate?money=&from=CNY&to=USD&action=currencies&key=YOUR_API_KEY"
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `money` | `number` | 原始金额（与请求 money 一致） | — |
| `from` | `string` | 源货币代码 | — |
| `from_name` | `string` | 源货币中文名 | — |
| `to` | `string` | 目标货币代码 | — |
| `to_name` | `string` | 目标货币中文名 | — |
| `rate` | `number` | 汇率（1 单位源币 = rate 单位目标币） | — |
| `result` | `number` | 换算结果（money × rate，取 4 位小数） | — |
| `update_time` | `string` | 上游汇率数据的更新时间（YYYY-MM-DD HH:mm:ss） | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "money": 1,
        "from": "CNY",
        "from_name": "人民币",
        "to": "USD",
        "to_name": "美元",
        "rate": 0.146405,
        "result": 0.1464,
        "update_time": "2026-05-06 13:00:02"
    },
    "request_id": "abc123def456"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 参数错误（money ≤ 0、货币代码长度异常） |
| `4015` | `—` | 匿名调用每日额度用完，需要 API Key |
| `4029` | `—` | QPS 超限 |
| `4030` | `—` | 今日额度用完 |
| `5020` | `—` | 上游服务不可用 / 货币代码不被上游支持 |
| `5021` | `—` | 上游返回数据缺少必要字段 |
| `5030` | `—` | 上游 Key 未配置或异常（管理员问题） |

## 9. 变更日志

- **1.0.0** (2026-05-06)
  - 首次上线，支持 26 种主流货币互转
  - 内建 60 秒缓存 + 同币种快路径（节省上游 quota）
  - action=currencies 子命令返回支持货币列表

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/exchange-rate`

Source: `https://apizero.cn/aidocs/exchange-rate/raw.md`
Last updated: 2026-05-11T16:15:07+08:00