期货行情（期货合约 K 线）

1. 接口描述

项目	说明
接口名称	期货行情（futures_contract_kline）
外部接口	GET /api/v1/market/data/futures/kline
请求方式	GET（query 参数）
适用场景	查询期货合约日、周、月、季、年 K 线，含开高低收、成交量、成交额、vwap、持仓量、主力合约与前/后复权因子

2. 请求参数

参数名	类型	是否必填	描述	取值示例	备注
symbol	string	是	期货合约代码	A2605.DCE	支持交易所短后缀
interval	string	否	K 线周期	daily	daily/1d、weekly/1w/week、monthly/1mo/month、quarterly/1q/quarter、yearly/1y/year；默认 daily
start	int	否	起始时间戳（毫秒）	1756431000000	闭区间；可省略时间范围
end	int	否	结束时间戳（毫秒）	1756791000000	闭区间；不能单独传入
limit	int	否	返回条数	5	默认 500，最小值 1，传 0 时按 1 处理

3. 响应说明

外层固定为 code / message / data。data 为对象：items（K 线记录列表）和 total（符合条件记录总数）。

items 元素：

字段名	类型	说明
symbol	string	规范化后的合约代码
datetime	int64	K 线时间戳（毫秒）
trade_date	int	交易日 YYYYMMDD
open / high / low / close	number	开盘价 / 最高价 / 最低价 / 收盘价
volume	int64	成交量
amount	number	成交额
vwap	number	成交均价
open_interest	number	持仓量
dominant_contract	string / null	主力合约；合约 K 线不返回该字段值
forward_factor	number / null	前复权因子；合约 K 线不返回该字段值
backward_factor	number / null	后复权因子；合约 K 线不返回该字段值

4. 调用方式

python <RUN_PY> futures-contract-kline --symbol A2605.DCE --interval daily --limit 5
python <RUN_PY> futures-contract-kline --symbol A2605.DCE --interval weekly --limit 5
python <RUN_PY> futures-contract-kline --symbol A2605.DCE --start 1756431000000 --end 1756791000000

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

5. 注意事项

• 周、月、季、年 K 线基于日 K 线按北京时间聚合。
• end 不能单独传入，必须与 start 同时使用（handler 会本地校验并拒绝）；仅传 start 时查询 start 之后的数据。
• 同时传入 start 和 end 时，跨度不得超过 12 个日历月。
• 本接口查询的是具体合约 K 线；dominant_contract 和复权因子字段对合约 K 线不返回值。