浏览全部文档

期货数据接口参考

29 个期货的价格和历史

概览

29 个期货的价格和价格历史：商品、股指、国债和货币。每个请求都需要 Bearer 密钥，REST 和 MCP 共用同一余额。

id 是交易所的根代码，例如 CL 表示 WTI 原油，GC 表示黄金，ES 表示 E-mini S&P 500，6E 表示欧元。不区分大小写。列表路由返回每个 id 及其名称、类别、交易所、币种和单位。

每个序列是近月合约，首尾相接，未做调整。近月合约切换当天，价格会从一个合约跳到下一个合约。这个跳变按实际成交保留在数据中。

基础 URL： 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路径参数是字符串期货 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查询参数是字符串以逗号分隔的 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路径参数是字符串期货 id：交易所的根代码，例如 CL、GC、ES 或 6E。不区分大小写。序列为连续近月合约，未做调整：每个换月日都有跳空。
interval查询参数否取值之一：1d、1m1d（每个交易日一根 K 线，日期为其所属交易日）或 1m（一分钟 K 线；保留 12 个月）。其他值返回 400 invalid_interval。
start查询参数否字符串第一根 K线。1d：日期（YYYY-MM-DD），包含该日；省略表示取最早的一根。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字符串总是
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
}

错误

错误使用通用的 problem 结构，并带有 request_id。查看 API 错误码与额度 了解该结构和额度相关的响应头。失败的请求不计费。

代码状态含义
invalid_query400参数缺失、未知、重复或超出范围。
invalid_id400id 或交易对的写法不符合此 API 的要求。
too_many_ids400批量请求包含的 id 超过 50 个。
invalid_interval400interval 不是 1d 或 1m，或该品种不支持。
range_too_large400时间窗口超过该路由允许的长度。
not_found404没有这个标的、基金或交易对。
invalid_cursor400该游标不是本请求返回的，或来自另一个请求。
insufficient_credits402您的额度余额低于该请求的费用。
area_unavailable503该区域目前无法响应。

此页面对你有帮助吗?