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.mdftshare-market-data/sub-skills/futures-minutes/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。