历史汇率 API

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

历史数据操作按时间从旧到新返回当前已接受并存储的数据序列。它与当前汇率和经济数据请求使用同一个 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 记录。这是真实的稀疏观测，不是部分响应错误。

价格柱

GET /v1/fx/rates/{base}/bars返回单一货币相对USD的已收盘价格柱，包含开盘价、最高价、最低价和收盘价。MCP工具为fx_get_rate_bars。

REST

curl --request GET \
  --url "https://api.narwhalapi.com/v1/fx/rates/USD/bars?currency=EUR&interval=1h&start=2026-10-08T00:00:00Z&end=2026-10-08T03:00:00Z" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

参数	规则
`base`	仅支持`USD`。其他基准货币返回`404 currency_not_supported`。
`currency`	价格采集器采集的一种报价货币。
`interval`	`1m`、`5m`、`15m`、`1h`、`4h`或`1d`（默认值）。
`start / end`	对齐完整间隔边界的UTC时刻（`4h`为00、04、08时，依此类推；`1d`为午夜）。包含起始时刻，不包含结束时刻。
`limit / cursor`	默认`100`，最多`500`。使用相同查询复用`next_cursor`。

每个价格柱包含timestamp（价格柱起始时刻），以及以每一单位base对应的currency数量表示的open、high、low和close。我们从不填补空缺，缺失的价格柱保持缺失。分钟级价格柱保留30天，小时级和日级价格柱无限期保留，可用历史范围受套餐限制。

错误

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 年。覆盖范围可扩展，无需更改此接口规范。

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