futures-kline-batch

批量查询多个期货合约的历史 K 线(futures_kline_batch,GET /api/v2/market/data/futures/kline/batch)。用户问多只期货合约日/周/月/季/年 K 线、批量期货开高低收、期货批量行情、多合约对比 K 线时使用。

SKILL.md

GitHub

批量期货合约历史K线

1. 接口描述

项目 说明
接口名称 批量期货合约历史K线(futures_kline_batch)
外部接口 GET /api/v2/market/data/futures/kline/batch
请求方式 GET(query 参数,symbols 使用逗号分隔)
适用场景 一次批量获取多个期货合约的历史 K 线(开高低收、成交量、成交额、vwap、持仓量),支持日/周/月/季周期
数据范围 支持日、周、月、季 K 线;周、月、季 K 线由历史日 K 线聚合生成
单次限量 symbols 支持 1~20 个合约;每个合约 limit 默认 500;时间范围不超过 12 个自然月

2. 请求参数

参数名 类型 是否必填 描述 取值示例 备注
symbols string 是 期货合约代码列表,逗号分隔传给 CLI A2611.DCE,M2611.DCE 1~20 个;接口侧以逗号分隔发送,兼容旧的重复参数格式
interval string 否 K 线周期 daily daily/weekly/monthly/quarterly;默认 daily
start int 否 起始时间戳(毫秒) 1790784000000 闭区间;按北京时间解释
end int 否 结束时间戳(毫秒) 1791647999000 闭区间;不能单独传入
limit int 否 每个合约返回的最新 K 线条数 5 默认 500

3. 响应说明

外层固定为 code(成功 200)/ message(成功 success)/ data。data 为按请求顺序排列的标的分组数组(非分页),每项结构为 {symbol, items, total}:

字段名 类型 说明
symbol string 请求中的合约代码(保留请求值)
items array 该合约符合条件且经 limit 截断后的 K 线记录列表
total integer items 中的 K 线记录数(已应用 limit);无数据时为 0

分组内每根 K 线字段:

字段名 类型 说明
symbol string 去除交易所后缀并转小写后的合约代码
datetime int K 线时间戳(毫秒)
trade_date int 交易日 YYYYMMDD
open / high / low / close number 开盘价 / 最高价 / 最低价 / 收盘价
volume int 成交量
amount number 成交额
vwap number 成交量加权均价
open_interest number 持仓量
dominant_contract string / null 主力合约;当前接口返回 null
forward_factor number / null 前复权因子;当前接口返回 null
backward_factor number / null 后复权因子;当前接口返回 null

4. 调用方式

python <RUN_PY> futures-kline-batch --symbols A2611.DCE,M2611.DCE --interval daily --start 1790784000000 --end 1791647999000 --limit 5
python <RUN_PY> futures-kline-batch --symbols A2611.DCE,M2611.DCE,CU2611.SHFE --interval weekly --limit 5

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

5. 注意事项

  • 交易所后缀规则(必读):合约代码格式为 <合约代码>.<交易所代码>,只接受交易所全称后缀 .SHFE、.INE、.DCE、.CZCE、.CFFEX、.GFEX;短后缀 .SHF、.CZC、.CFE、.GFE 及其它未列出的后缀会返回 HTTP 400;无后缀的裸合约代码仍兼容。
  • symbols 使用逗号分隔发送(symbols=A2611.DCE,M2611.DCE),兼容旧的重复参数格式。
  • 外层分组的 symbol 保留请求值;分组内 K 线记录的 symbol 为去除交易所后缀并转小写后的合约代码。
  • start 与 end 均为 Unix 毫秒时间戳,按北京时间解释;end 不能单独传入,必须与 start 同时使用(handler 会本地校验)。
  • start 与 end 的时间跨度不得超过 12 个自然月。
  • 单合约历史 K 线请使用 futures-kline;历史分钟 K 线请使用 futures-minutes。