回補完整歷史
分頁讀取全部歷史，儲存到檔案，中斷後可繼續。
閱讀指南 →所有 API
油、金屬、穀物與牲畜期貨報價 API
透過 REST 或 MCP，取得 13 種商品期貨的最新價格，以及日線或一分鐘歷史資料。每個序列都是近月合約，所以價格在換月日會跳動。
首次請求
取得 WTI 原油的最新價格
curl --request GET \
--url "https://api.narwhalapi.com/v1/futures/CL/price" \
--header "Authorization: Bearer $NARWHAL_API_KEY"回應範例
{
"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
}端點
GET列出期貨/v1/futures
GET取得期貨價格/v1/futures/{id}/price
取得單一合約的最新價格。
參數
id必填期貨 id：交易所的商品代碼，例如 CL、GC、ES 或 6E。大小寫皆可。序列為連續的近月合約，未經調整，每逢換月日都有缺口。
主要回應欄位
id字串根代碼，例如 CL。
name字串合約的正式名稱。
commodity_key字串商品的固定鍵值，在現貨、期貨、預測與實物價格中皆相同，例如 gold 或 crude-oil。可用它來串接這些資料。股價指數、利率與貨幣期貨會省略。
benchmarkwti、brent、urals、dubai 擇一原油基準：wti、brent、urals 或 dubai。僅原油會回傳；沒有此欄位的原油資料列代表整體原油。
exchange字串合約交易所在的交易所。
exchange_mic字串交易所的 ISO 10383 市場識別碼，例如 XNYM。
currency字串價格的幣別。
unit字串價格的計價基準，例如 usd_per_barrel 或 index_point。
unit_key字串單位的標準小寫名稱，在所有使用該單位的介面上都相同，例如 barrel、troy_ounce、mmbtu 或 tonne。unit 則保留來源的原始寫法。
price_scale字串僅在價格以較小計價單位報價時才會回傳。將 price 乘以此值即可得到以 currency 計價的價格：0.01 表示 price 以美分計，因此 unit 為 cent_per_bushel、price 為 450 時，即每蒲式耳 4.50 USD。
完整參考文件 →
GET取得多筆期貨價格/v1/futures/prices
一次呼叫取得最多 50 個合約的最新價格。
參數
ids必填以逗號分隔的 id，去除重複後最多 50 個。每個 id 的規則與單一價格路由相同。每個回傳價格的 id 計為一次呼叫。
回應欄位
prices物件陣列每個回傳價格的 id 各有一筆，內容為單一價格的欄位。
errors物件陣列未回傳價格的 id，每個都帶有代碼 not_found。這些不收費。
完整參考文件 →
GET取得期貨 K 線/v1/futures/{id}/bars
取得單一合約的日線或一分鐘 K 線，由舊到新排列。價格為未調整的近月原始價格，所以換月日會跳動。
參數
id必填期貨 id：交易所的商品代碼，例如 CL、GC、ES 或 6E。大小寫皆可。序列為連續的近月合約，未經調整，每逢換月日都有缺口。
interval選填1d（每個交易日一根 K 線，以其所屬日期標示）或 1m（一分鐘 K 線，保留 12 個月）。其他值會回傳 400 invalid_interval。
start選填第一根 K 線。1d：日期（YYYY-MM-DD），含該日；省略則表示最早的一根 K 線。1m：UTC 時間（YYYY-MM-DDTHH:MM:SSZ，或僅填日期，視為 UTC 00:00），含該時間；省略則表示 end 的前一天。
end選填最後一根 K 線。1d：日期，含該日；省略則表示最近一個已收盤的日子。1m：UTC 時間，不含該時間；省略則表示現在，或 start 之後五天。1m 的 start 與 end 之間最多 5 天（400 range_too_large）。
cursor選填上一頁的 next_cursor，其他參數須相同。
回應欄位
id字串根代碼，例如 CL。
commodity_key字串商品的固定鍵值，在現貨、期貨、預測與實物價格中皆相同，例如 gold 或 crude-oil。可用它來串接這些資料。股價指數、利率與貨幣期貨會省略。
benchmarkwti、brent、urals、dubai 擇一原油基準：wti、brent、urals 或 dubai。僅原油會回傳；沒有此欄位的原油資料列代表整體原油。
currency字串價格的幣別。
price_scale字串僅在價格以較小計價單位報價時才會回傳。將 price 乘以此值即可得到以 currency 計價的價格：0.01 表示 price 以美分計，因此 unit 為 cent_per_bushel、price 為 450 時，即每蒲式耳 4.50 USD。
start字串僅在範圍起點被向後移動時才會回傳。
end字串不再回傳，因為所有帳戶的價格都是即時的。
bars物件陣列K 線由舊到新排列。每根都有 timestamp、open、high、low 與 close，沒有成交量。
next_cursor字串傳回此值即可讀取下一頁。最後一頁為 null。
完整參考文件 →
使用情境
涵蓋範圍
能源
- WTI 原油CL · NYMEX · 每桶 USD
- 亨利港天然氣NG · NYMEX · 每 MMBtu 的 USD 價格
- RBOB 汽油RB · NYMEX · 每加侖 USD
- 紐約港超低硫柴油HO · NYMEX · 每加侖 USD
金屬
- 黃金GC · COMEX · 每金衡盎司 USD
- 白銀SI · COMEX · 每金衡盎司 USD
- 鉑金PL · NYMEX · 每金衡盎司 USD
- 銅HG · COMEX · 每磅 USD
穀物
- 玉米ZC · CBOT · 美分／蒲式耳
- 芝加哥軟紅冬麥ZW · CBOT · 美分／蒲式耳
- 黃豆ZS · CBOT · 美分／蒲式耳
Livestock
- 活牛LE · CME · 美分／磅
- 瘦肉豬HE · CME · 美分／磅
相關 API
常見問題
可以取得哪些商品期貨？
13 種合約。能源：WTI 原油、亨利港天然氣、RBOB 汽油與紐約港超低硫柴油。金屬：黃金、白銀、鉑金與銅。穀物：玉米、小麥與黃豆。畜產：活牛與瘦肉豬。
這與現貨價格 API 有何不同？
現貨 API 以多種幣別報價黃金，白銀、鉑金與鈀金則以美元報價。商品期貨是以美元計價的近月合約，採用合約本身的單位。黃金期貨（GC）與黃金現貨（XAU）是不同的價格。
為什麼價格在某些日子會跳動？
每個序列都是近月合約，首尾相接，不做調整。近月合約換月時，序列會轉到下一個合約，價格也跳到該合約的價格。CL 在 2026 年 10 月 19 日跳動了約 4 美元。價格與 K 線如實顯示成交時的跳動，所以不要把它當成一天的漲跌。這也是期貨價格沒有前收盤價或漲跌的原因：換月時的漲跌是假的。
價格的單位是什麼？
每個回應都帶有單位。CL 是 usd_per_barrel，NG 是 usd_per_mmbtu，RB 與 HO 是 usd_per_gallon，GC、SI 與 PL 是 usd_per_troy_ounce，HG 是 usd_per_pound。穀物是 cent_per_bushel，畜產是 cent_per_pound，所以這些價格以美分計，不是美元。
價格是即時的還是延遲的？
所有帳戶的價格都是即時的。日線可追溯到 2017 年 4 月，所有帳戶都可取得完整歷史。
費用是多少？
呼叫費用為每 1,000 次 $2，從預付額度扣款。每個帳戶在前 12 個月內，每月都有 $10 的免費額度。
從免費金鑰開始
12 個月內每月贈送 10 美元免費額度，無需綁卡。每月 10 美元免費額度，無需綁卡。