历史汇率 API

按基准货币、报价货币和日期范围请求已存储的汇率。

历史操作按最早优先顺序返回当前已接受的存储序列。它与当前 FX 和 Economics 请求使用相同的 Narwhal 密钥和共享月度额度。

请求

REST

curl --request GET \
  --url "https://api.narwhalapi.com/v1/fx/rates/USD/observations?currencies=EUR,NZD&start_date=2026-08-20&end_date=2026-08-28&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

参数	规则
`base`	路径中的大写流通ISO 4217货币代码。
`currencies`	必需值：以逗号分隔的 1–64 个唯一报价货币；不能包含基础货币。
`start_date`	不早于以下日期（包含当日）： `1971-01-01`.
`end_date`	包含起始日期当天及之后的日期，且不能是未来日期。
`limit`	每页的观测日期。默认值为 `100`；最大值 `366`.
`cursor`	上一页返回的不透明值。只能在使用相同筛选条件时重用。

MCP 工具是 fx_get_rate_history。其 currencies 输入是 JSON 数组；所有其他字段含义相同。

响应

贴近生产环境的示例

{
  "base": "USD",
  "start_date": "2026-08-20",
  "end_date": "2026-08-28",
  "observations": [
    {
      "date": "2026-08-20",
      "rates": [
        { "currency": "EUR", "rate": "0.85609" },
        { "currency": "NZD", "rate": "1.681" }
      ]
    },
    {
      "date": "2026-08-21",
      "rates": [
        { "currency": "EUR", "rate": "0.85477" },
        { "currency": "NZD", "rate": "1.6714" }
      ]
    },
    {
      "date": "2026-08-24",
      "rates": [{ "currency": "EUR", "rate": "0.85734" }]
    }
  ],
  "next_cursor": null,
  "has_more": false
}

每个汇率都是十进制字符串。一个单位的 base 等于返回的金额 currency 在该观测日期。

分页

limit 按日期计数，因此一页不会拆分同一日期的货币记录。当 has_more 为 true 时，传入 next_cursor 使用完全相同的基准货币、货币列表、开始日期和结束日期返回。游标绑定筛选条件；更改这些值会返回 400 invalid_cursor.

没有总体日期跨度上限。完整历史回填会反复使用同一个有界页面，直到 next_cursor 为 null。

不会捏造缺失的日期和货币

仅显示实际存储的观测日期。周末、节假日和其他缺失的发布日期会被省略。Narwhal 不会向前填充这些日期。

某个日期可能只包含所请求货币的子集。例子中，8 月 24 日没有 NZD 记录，但有 EUR 记录。这是真实的稀疏观测，不是部分响应错误。

错误

400 invalid_query 适用于无效货币、日期或页面大小。
400 invalid_cursor 适用于格式错误或与筛选条件不匹配的分页状态。
401 invalid_api_key 当Bearer密钥缺失或无效时。
404 currency_not_supported 所选货币不可用时。
429 rate_limit_exceeded 达到短窗口限制时；等待 Retry-After ，再重试。
429 quota_exhausted 共享月度额度耗尽时。
503 upstream_unavailable 无法安全读取已接受的历史数据时。

查看错误和限制指南适用于两类速率限制请求头和重试行为。

覆盖范围和限制

不同货币的覆盖起始日期不同。最早受支持的存储序列始于1971年；大多数每日覆盖始于1999年或2000年。覆盖范围可以扩展，而无需改变本契约。

该接口返回当前已接受的历史序列，而不是每个更早的发布版本。它省略来源、提供方、许可证、推导过程、陈旧状态和市场交易时段字段。请阅读该外汇数据方法说明用于公开数据政策以及外汇产品页面适用于所有上线操作。