回填完整历史
分页读取全部历史，保存到文件，中断后可继续。
阅读指南 →所有 API
覆盖原油、金属、谷物与畜牧的商品期货 API
通过 REST 或 MCP，获取 13 种大宗商品期货的最新价格以及日线或 1 分钟历史数据。每个序列都是近月合约，因此价格在换月日会出现跳动。
首次请求
获取 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。可用它关联这些数据。股指、利率和货币期货省略此项。
benchmark取值之一：wti、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
获取单个合约的日线或 1 分钟 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。可用它关联这些数据。股指、利率和货币期货省略此项。
benchmark取值之一：wti、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 · 每桶美元
- 亨利港天然气NG · NYMEX · 每 MMBtu 的美元数
- RBOB 汽油RB · NYMEX · 每加仑美元
- 纽约港超低硫柴油HO · NYMEX · 每加仑美元
金属
- 黄金GC · COMEX · 每金衡盎司美元
- 白银SI · COMEX · 每金衡盎司美元
- 铂金PL · NYMEX · 每金衡盎司美元
- 铜HG · COMEX · 每磅美元
谷物
- 玉米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 美元免费额度，无需绑卡。