歷史匯率 API

按基準貨幣、報價貨幣和日期範圍請求已儲存的匯率。

歷史資料操作按時間由舊到新回傳目前已接受並儲存的序列。它與目前的 FX 和經濟數據請求使用相同的 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 年。資料涵蓋範圍可擴大，無須變更此介面規範。

此介面回傳目前已接受的歷史序列，而非過去每次發布時的資料版本。回應不包含來源、提供者、授權、推導方式、過期狀態及市場交易時段欄位。請參閱外匯方法說明以了解公開資料政策，並參閱 FX 產品頁面以查看所有已上線的操作。