期貨 API 參考文件

29 種期貨的價格與歷史資料

概覽

29 種期貨的價格與歷史價格：商品、股價指數、美國公債與貨幣。每個請求都需要 Bearer 金鑰，REST 與 MCP 共用同一個額度餘額。

id 是交易所的商品代碼，例如 CL 代表 WTI 原油，GC 代表黃金，ES 代表 E-mini S&P 500，6E 代表歐元。大小寫皆可。清單路由會回傳每個 id 及其名稱、類別、交易所、幣別與單位。

每個序列都是近月合約首尾相接而成，未經調整。近月合約換月當天，價格會從一個合約跳到下一個合約。這個跳動會如實保留在資料中。

基礎網址： https://api.narwhalapi.com。 MCP 工具是 futures, with one action ，適用於下列每個路由。

每個帳戶都能取得的內容

費用	所有帳戶
最新價格	在線
日線柱狀數據	完整歷史，自 2017 年 4 月起
1 分鐘 K 線	最近 12 個月
序列清單	已包含

查看定價說明每次呼叫的費用。除非路由另有說明，請求依其所屬 API 的價格計費。

期貨價格沒有前收盤價、漲跌或成交量。跨越合約換月的漲跌會失真，因此 API 不計算。
價格與 K 線是近月合約的實際成交資料。每逢換月日會出現跳動：CL 在 2026 年 10 月 19 日跳動了約 4 美元。請勿將此跳動視為單日漲跌。
market_session 依合約公布的交易時段為 open 或 closed。已收市的序列會回傳最後價格，且不算過時。開市中的序列若價格超過 15 分鐘未更新，即為過時。
日 K 線涵蓋一個交易日，於 00:00 UTC 出現。當日尚未完成的 K 線不會顯示。
一分鐘 K 線保留 12 個月，單一請求最多涵蓋 5 天。
一個批次最多包含 50 個 id，每個回傳價格的 id 計為一次呼叫。未知的 id 會列在 errors，且不計次。

端點

每個路由都是 GET 請求，並需要將你的金鑰放在以下請求標頭中： Authorization: Bearer 標頭。範例僅展示回應的結構，並非即時資料。

提供報價的期貨

GET /v1/futures

我們提供報價的所有期貨序列，依 id 排序，並附名稱與單位。資料來自我們自己的清單，所有帳號皆可使用，計為一次呼叫。

MCP：工具 futures, action list。

參數

此路由不接受任何參數。

回應欄位

欄位	類型	傳送	含義
`futures`	物件陣列	固定回傳	我們提供報價的所有序列，依 id 排序。
`futures[].id`	字串	固定回傳	商品代碼，例如 CL。
`futures[].name`	字串	固定回傳	序列名稱。
`futures[].category`	energy、metals、grains、livestock、equity_index、interest_rate、currency 擇一	固定回傳
`futures[].commodity_key`	字串	選填	商品的固定鍵值，在現貨、期貨、預測與實物價格中皆相同，例如 gold 或 crude-oil。可用它來串接這些資料。股價指數、利率與貨幣期貨會省略。
`futures[].benchmark`	wti、brent、urals、dubai 擇一	選填	原油基準：wti、brent、urals 或 dubai。僅原油會回傳；沒有此欄位的原油資料列代表整體原油。
`futures[].exchange`	字串	固定回傳	掛牌的交易所。
`futures[].exchange_mic`	字串	選填	交易所的 ISO 10383 市場識別碼，例如 XNYM。
`futures[].currency`	字串	固定回傳	價格的幣別。
`futures[].unit`	字串	固定回傳	價格的計價單位，例如 usd_per_barrel 或 index_point。
`futures[].unit_key`	字串	選填	單位的標準小寫名稱，在所有使用它的介面上皆相同，例如 barrel、troy_ounce、mmbtu 或 tonne。`unit` 保留來源的原始寫法。
`futures[].price_scale`	字串	選填	僅在價格以次單位報價時回傳。將 `price` 乘以此值即得到以 `currency` 表示的價格：0.01 代表 `price` 以美分計，因此單位為 cent_per_bushel、價格為 450 時，即每蒲式耳 4.50 USD。

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures"

{
  "futures": [
    {
      "id": "CL",
      "name": "WTI Crude Oil",
      "category": "energy",
      "exchange": "NYMEX",
      "currency": "USD",
      "unit": "usd_per_barrel"
    },
    {
      "id": "GC",
      "name": "Gold",
      "category": "metals",
      "exchange": "COMEX",
      "currency": "USD",
      "unit": "usd_per_troy_ounce"
    }
  ]
}

單一期貨序列的最新價格

GET /v1/futures/{id}/price

最新價格。market_session 依序列的交易時段為 open 或 closed；已收市的序列會回傳最後價格，只有開市中的序列在最近 15 分鐘內沒有價格時，stale 才為 true。期貨價格沒有前收盤價、漲跌或成交量：序列是近月合約首尾相接而成，未經調整，因此每逢換月日都有缺口。

MCP：工具 futures, action price。

參數

參數	位置	必填	類型	含義
`id`	path	是	字串	期貨 id：交易所的商品代碼，例如 CL、GC、ES 或 6E。大小寫皆可。序列為連續的近月合約，未經調整，每逢換月日都有缺口。

回應欄位

欄位	類型	傳送	含義
`id`	字串	固定回傳	商品代碼。
`name`	字串	固定回傳	名稱，依我們代號清單所載。
`commodity_key`	字串	選填	商品的固定鍵值，在現貨、期貨、預測與實物價格中皆相同，例如 gold 或 crude-oil。可用它來串接這些資料。股價指數、利率與貨幣期貨會省略。
`benchmark`	wti、brent、urals、dubai 擇一	選填	原油基準：wti、brent、urals 或 dubai。僅原油會回傳；沒有此欄位的原油資料列代表整體原油。
`exchange`	字串	固定回傳
`exchange_mic`	字串	選填	交易所的 ISO 10383 市場識別碼，例如 XNYM。
`currency`	字串	固定回傳	價格的幣別。
`unit`	字串	固定回傳
`unit_key`	字串	選填	單位的標準小寫名稱，在所有使用它的介面上皆相同，例如 barrel、troy_ounce、mmbtu 或 tonne。`unit` 保留來源的原始寫法。
`price_scale`	字串	選填	僅在價格以次單位報價時回傳。將 `price` 乘以此值即得到以 `currency` 表示的價格：0.01 代表 `price` 以美分計，因此單位為 cent_per_bushel、價格為 450 時，即每蒲式耳 4.50 USD。
`price`	字串	固定回傳	連續近月合約的最新成交價。
`market_session`	open、closed 擇一	固定回傳	序列依公布時段交易時為 `open`，否則為 `closed`。已收市的序列仍會回傳最後價格；時段內遇到假日時顯示為 `open`，並標示為 `stale`。
`timestamp`	日期時間	固定回傳	價格有效的時間（UTC，精確到秒）。
`stale`	布林值	固定回傳	序列開市中且價格超過 15 分鐘未更新，或無法更新時為 true。已收市的序列不算過時。
`delayed`	一律為 true	選填	不會回傳：所有帳號的價格皆為即時。

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures/CL/price"

{
  "id": "CL",
  "name": "WTI Crude Oil",
  "commodity_key": "crude-oil",
  "benchmark": "wti",
  "exchange": "NYMEX",
  "exchange_mic": "XNYM",
  "currency": "USD",
  "unit": "usd_per_barrel",
  "unit_key": "barrel",
  "price": "102.11",
  "market_session": "open",
  "timestamp": "2026-10-29T18:38:00Z",
  "stale": false
}

最多 50 個期貨序列的最新價格

GET /v1/futures/prices

所列每個 id 的最新價格。每個回傳價格的 id 計為一次呼叫，並一次性扣款：若餘額不足以支付已解析的 id，整個請求會以 402 insufficient_credits 拒絕。未回傳價格的 id 會列在 errors（以 id 表示），不收費；若沒有任何 id 能解析，回應仍為 200，且 prices 為空。期貨價格沒有前收盤價、漲跌或成交量：序列是近月合約首尾相接而成，未經調整，因此每逢換月日都有缺口。

最多可傳入 50 個 ID。批次一次扣款：若餘額不足以支付可解析的 ID，整個請求會回傳 402 insufficient_credits。

MCP：工具 futures, action prices。

參數

參數	位置	必填	類型	含義
`ids`	query	是	字串	以逗號分隔的 id，去除重複後最多 50 個。每個 id 的規則與單一價格路由相同。每個回傳價格的 id 計為一次呼叫。

回應欄位

欄位	類型	傳送	含義
`prices`	物件陣列	固定回傳	每個成功解析的 ID 各有一筆價格，以 ID 為鍵。
`prices[].id`	字串	固定回傳	商品代碼。
`prices[].name`	字串	固定回傳	名稱，依我們代號清單所載。
`prices[].commodity_key`	字串	選填	商品的固定鍵值，在現貨、期貨、預測與實物價格中皆相同，例如 gold 或 crude-oil。可用它來串接這些資料。股價指數、利率與貨幣期貨會省略。
`prices[].benchmark`	wti、brent、urals、dubai 擇一	選填	原油基準：wti、brent、urals 或 dubai。僅原油會回傳；沒有此欄位的原油資料列代表整體原油。
`prices[].exchange`	字串	固定回傳
`prices[].exchange_mic`	字串	選填	交易所的 ISO 10383 市場識別碼，例如 XNYM。
`prices[].currency`	字串	固定回傳	價格的幣別。
`prices[].unit`	字串	固定回傳
`prices[].unit_key`	字串	選填	單位的標準小寫名稱，在所有使用它的介面上皆相同，例如 barrel、troy_ounce、mmbtu 或 tonne。`unit` 保留來源的原始寫法。
`prices[].price_scale`	字串	選填	僅在價格以次單位報價時回傳。將 `price` 乘以此值即得到以 `currency` 表示的價格：0.01 代表 `price` 以美分計，因此單位為 cent_per_bushel、價格為 450 時，即每蒲式耳 4.50 USD。
`prices[].price`	字串	固定回傳	連續近月合約的最新成交價。
`prices[].market_session`	open、closed 擇一	固定回傳	序列依公布時段交易時為 `open`，否則為 `closed`。已收市的序列仍會回傳最後價格；時段內遇到假日時顯示為 `open`，並標示為 `stale`。
`prices[].timestamp`	日期時間	固定回傳	價格有效的時間（UTC，精確到秒）。
`prices[].stale`	布林值	固定回傳	序列開市中且價格超過 15 分鐘未更新，或無法更新時為 true。已收市的序列不算過時。
`prices[].delayed`	一律為 true	選填	不會回傳：所有帳號的價格皆為即時。
`errors`	物件陣列	固定回傳	沒有回傳價格的 ID，不收費。
`errors[].id`	字串	固定回傳	請求時傳入的 ID。
`errors[].code`	固定為 "not_found"	固定回傳	not_found：沒有此序列。

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures/prices?ids=CL,GC,ES"

{
  "prices": [
    {
      "id": "CL",
      "name": "WTI Crude Oil",
      "commodity_key": "crude-oil",
      "benchmark": "wti",
      "exchange": "NYMEX",
      "exchange_mic": "XNYM",
      "currency": "USD",
      "unit": "usd_per_barrel",
      "unit_key": "barrel",
      "price": "102.11",
      "market_session": "open",
      "timestamp": "2026-10-29T18:38:00Z",
      "stale": false
    },
    {
      "id": "GC",
      "name": "Gold",
      "exchange": "COMEX",
      "currency": "USD",
      "unit": "usd_per_troy_ounce",
      "price": "4021.3",
      "market_session": "open",
      "timestamp": "2026-10-29T18:38:00Z",
      "stale": false
    }
  ],
  "errors": [
    {
      "id": "XX",
      "code": "not_found"
    }
  ]
}

單一期貨序列的價格 K 線

GET /v1/futures/{id}/bars

日（1d，每個交易日一根 K 線）或一分鐘（1m）K 線，由舊到新排列。某日的 K 線在該日結束後的 00:00 UTC 產生；當日尚未完成的 K 線不會顯示。一分鐘 K 線保留 12 個月。歷史資料：全部，所有帳號皆可取得。每頁最多 5,000 根 K 線，並附 next_cursor。每頁計為一次呼叫。

K 線是近月合約的原始價格，因此在換月日，某根 K 線的開盤價可能與前一根的收盤價有落差。

MCP：工具 futures, action bars。

參數

參數	位置	必填	類型	含義
`id`	path	是	字串	期貨 id：交易所的商品代碼，例如 CL、GC、ES 或 6E。大小寫皆可。序列為連續的近月合約，未經調整，每逢換月日都有缺口。
`interval`	query	否	下列其一：1d、1m	`1d`（每個交易日一根 K 線，以所屬日期標記）或 `1m`（一分鐘 K 線，保留 12 個月）。其他值會回傳 400 invalid_interval。
`start`	query	否	字串	第一根 K 線。`1d`：日期（YYYY-MM-DD），含該日；省略時為最舊的一根。`1m`：UTC 時間（YYYY-MM-DDTHH:MM:SSZ，或以日期代表 UTC 00:00），含該時間；省略時為 `end` 的前一天。
`end`	query	否	字串	最後一根 K 線。`1d`：日期，含當日；省略表示最近一個已完成的日子。`1m`：UTC 時間，不含；省略表示現在，或 `start` 之後五天。`1m` 的 `start` 與 `end` 最多相隔 5 天（400 range_too_large）。
`cursor`	query	否	字串	上一頁的 `next_cursor`，且參數須與前次相同。

回應欄位

欄位	類型	傳送	含義
`id`	字串	固定回傳
`commodity_key`	字串	選填	商品的固定鍵值，在現貨、期貨、預測與實物價格中皆相同，例如 gold 或 crude-oil。可用它來串接這些資料。股價指數、利率與貨幣期貨會省略。
`benchmark`	wti、brent、urals、dubai 擇一	選填	原油基準：wti、brent、urals 或 dubai。僅原油會回傳；沒有此欄位的原油資料列代表整體原油。
`currency`	字串	固定回傳	價格的幣別。
`price_scale`	字串	選填	僅在價格以次單位報價時回傳。將 `price` 乘以此值即得到以 `currency` 表示的價格：0.01 代表 `price` 以美分計，因此單位為 cent_per_bushel、價格為 450 時，即每蒲式耳 4.50 USD。
`start`	字串	選填	不會回傳：`start` 不會被調整。
`end`	字串	選填	不會回傳：日 K 線不會被截斷。
`bars`	物件陣列	固定回傳	每頁最多 5,000 根 K 線。
`bars[].timestamp`	日期時間	固定回傳	K 線所屬期間的起點（UTC）：日 K 線為該交易日的 00:00，一分鐘 K 線為該分鐘。
`bars[].open`	字串	固定回傳	期間的第一個價格。
`bars[].high`	字串	固定回傳	期間的最高價。
`bars[].low`	字串	固定回傳	期間的最低價。
`bars[].close`	字串	固定回傳	期間的最後價格。
`next_cursor`	字串	固定回傳	傳回此值即可讀取下一頁。最後一頁為 null。

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures/ES/bars?interval=1d&start=2017-04-03&end=2017-04-05"

{
  "id": "ES",
  "currency": "USD",
  "bars": [
    {
      "timestamp": "2017-04-03T00:00:00Z",
      "open": "2357.5",
      "high": "2363.25",
      "low": "2340",
      "close": "2354.5"
    }
  ],
  "next_cursor": null
}

錯誤

錯誤使用共用的問題格式，並包含 request_id。查看 API 錯誤處理：錯誤碼、額度與重試了解格式與額度標頭。失敗的請求不計費。

代碼	狀態	含義
`invalid_query`	400	參數缺漏、未知、重複，或超出範圍。
`invalid_id`	400	id 或交易對的寫法不符合此 API 的要求。
`too_many_ids`	400	批次包含超過 50 個 id。
`invalid_interval`	400	間隔不是 1d 或 1m，或此商品不支援該間隔。
`range_too_large`	400	區間超過此路由允許的長度。
`not_found`	404	沒有此標的、基金或交易對。
`invalid_cursor`	400	此游標不是這個請求所回傳的，或來自不同的請求。
`insufficient_credits`	402	您的額度餘額不足以支付此請求的費用。
`area_unavailable`	503	此區域目前無法回應。

此頁面對你有幫助嗎?