歷史匯率 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年。覆蓋範圍可以擴展，而無需改變本契約。

該介面返回當前已接受的歷史序列，而不是每個更早的發布版本。它省略來源、提供方、許可證、推導過程、陳舊狀態和市場交易時段欄位。請閱讀該外匯數據方法說明用於公開數據政策以及外匯產品頁面適用於所有上線操作。