futures-minutes

期货历史分钟 K 线,单合约或批量(futures_minutes,GET /api/v2/market/data/futures_minutes)。用户问期货分钟行情、1/5/15/30/60 分钟 K 线、多只期货合约分钟走势时使用。必填 --start、--end 与 --symbol / --symbols 之一;可选 --interval、--limit。

SKILL.md

GitHub

期货历史分钟K线

1. 接口描述

项目 说明
接口名称 期货历史分钟K线(futures_minutes)
外部接口 GET /api/v2/market/data/futures_minutes
请求方式 GET(query 参数,symbols 使用逗号分隔)
适用场景 获取单个或批量期货合约的历史分钟 K 线;同一路径通过 symbol / symbols 区分查询形式
数据范围 历史 1 分钟原始 K 线,可聚合为 1、5、15、30、60 分钟 K 线;不返回实时分钟数据
单次限量 单合约查询 limit 默认 500,范围 1~1000;批量查询支持 1~20 个合约;时间跨度不超过 3 个自然日(含首尾)

2. 请求参数

参数名 类型 是否必填 描述 取值示例 备注
symbol string 二选一 单个期货合约代码 A2611.DCE 与 symbols 不能同时传
symbols string 二选一 1~20 个合约代码,逗号分隔传给 CLI A2611.DCE,CU2611.SHFE 接口侧以逗号分隔发送,兼容旧的重复参数格式
interval string 否 分钟周期 5min 1min/5min/15min/30min/60min;兼容 1m/5m/15m/30m/1h;默认 1min
start int 是 起始时间戳(毫秒) 1791475200000 闭区间;必须与 end 同时传入
end int 是 结束时间戳(毫秒) 1791647999000 闭区间;与 start 跨度不超过 3 个自然日
limit int 否 每个合约返回的最新 K 线条数 5 默认 500,范围 1~1000

3. 响应说明

外层固定为 code(成功 200)/ message(成功 success)/ data。data 结构随查询形式变化:

  • 单合约查询(--symbol):data 为对象 {items, total};total 为查询范围内符合条件的原始分钟记录数,不受 limit 截断影响,不一定等于 items 条数。
  • 批量查询(--symbols):data 为按入参顺序排列的分组数组,每项含 symbol(请求中的合约代码)、items(该合约符合条件且经 limit 截断后的分钟 K 线列表)、total(items 中的分钟 K 线数量,已应用 limit;无数据时为 0)。

每根分钟 K 线字段:

字段名 类型 说明
bar_interval string 返回周期,例如 5min
symbol string 去除交易所后缀并转小写后的合约代码
variety string 期货品种标识
exchange string 交易所标识
datetime int K 线时间戳(毫秒)
trade_date int 交易日 YYYYMMDD
open / high / low / close number 开盘、最高、最低、收盘价格
volume int 成交量
amount number 成交额
vwap number 成交量加权均价
open_interest number 持仓量
pre_settlement_price number 昨日结算价
settlement_price number 结算价;未结算时可能为 0
high_limit_price number 涨停价
low_limit_price number 跌停价
pre_close_price number 昨收价
updated_at int 数据更新时间戳(毫秒)

4. 调用方式

# 单合约:5 分钟 K
python <RUN_PY> futures-minutes --symbol A2611.DCE --interval 5min --start 1791475200000 --end 1791647999000 --limit 5

# 批量:每合约最新 5 根 5 分钟 K
python <RUN_PY> futures-minutes --symbols A2611.DCE,CU2611.SHFE --interval 5min --start 1791475200000 --end 1791647999000 --limit 5

<RUN_PY> 为主 SKILL.md 同级 run.py 的绝对路径。输出 JSON;HTTP 错误输出到 stderr 并以非零状态退出。

5. 注意事项

  • 交易所后缀规则(必读):合约代码格式为 <合约代码>.<交易所代码>,只接受交易所全称后缀 .SHFE、.INE、.DCE、.CZCE、.CFFEX、.GFEX;短后缀 .SHF、.CZC、.CFE、.GFE 及其它未列出的后缀会返回 HTTP 400;无后缀的裸合约代码仍兼容。
  • --symbol / --symbols 二选一,至少提供一个且不能同时传入;start 与 end 必须同时传入,时间跨度不得超过 3 个北京时间自然日。
  • 批量查询时 symbols 使用逗号分隔发送(symbols=A2611.DCE,CU2611.SHFE),兼容旧的重复参数格式。
  • limit 必须在 1~1000;批量超过 20 个合约请求失败(CLI 会提前拦截合约数量)。
  • 当前北京时间日期当天的数据在 16:30 前不可查询。
  • 多分钟 K 在交易日内聚合,bar_interval 标识返回周期;settlement_price 未结算时可能为 0。
  • 历史周期 K 线请使用 futures-kline(单合约)或 futures-kline-batch(批量);实时分钟 K 线请使用 futures-realtime-minute-kline。