git:20261012.2c3d827 to git:20261019.195a28f

6 added, 8 removed. Audit A to A.

---

name: futures-minutes

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

---

# 期货历史分钟K线

## 1. 接口描述

| 项目 | 说明 |

|------|------|

| 接口名称 | 期货历史分钟K线（futures_minutes） |

| 外部接口 | `GET /api/v2/market/data/futures_minutes` |

- | 请求方式 | GET（query 参数，`symbols` 以重复参数发送） |

+ | 请求方式 | GET（query 参数，`symbols` 使用逗号分隔） |

| 适用场景 | 获取单个或批量期货合约的历史分钟 K 线；同一路径通过 `symbol` / `symbols` 区分查询形式 |

| 数据范围 | 历史 1 分钟原始 K 线，可聚合为 1、5、15、30、60 分钟 K 线；不返回实时分钟数据 |

| 单次限量 | 单合约查询 `limit` 默认 500，范围 1～1000；批量查询支持 1～20 个合约；时间跨度不超过 3 个自然日（含首尾） |

## 2. 请求参数

| 参数名 | 类型 | 是否必填 | 描述 | 取值示例 | 备注 |

|--------|------|----------|------|----------|------|

| 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.items` 为分组对象数组，每项含 `symbol`（请求中的合约代码）、`items`（该合约符合条件且经 `limit` 截断后的分钟 K 线列表）、`total`（该合约**符合条件的记录总数**，不受 `limit` 截断影响）。

- 真机验证：`limit=3` 时单合约 `items` 为 3 条而 `total` 为 73；批量 `limit=1` 时每组 `items` 为 1 条而 `total` 为 73/110。`limit` 只截断 `items` 条数，不改变 `total`。

+ - **批量查询**（`--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. 调用方式

```bash

# 单合约：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.SHF --interval 5min --start 1791475200000 --end 1791647999000 --limit 5

+ 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. 注意事项

- - **交易所后缀规则（必读）**：合约代码格式为 `<合约代码>.<三字符交易所后缀>`，本接口支持 `.DCE`、`.SHF`、`.CZC`、`.INE`、`.GFE`、`.CFE`；长后缀 `.SHFE`、`.CZCE`、`.GFEX`、`.CFFEX` 等不支持，会返回 HTTP 400，请勿照搬公开行情数据源写法。

+ - **交易所后缀规则（必读）**：合约代码格式为 `<合约代码>.<交易所代码>`，只接受交易所全称后缀 `.SHFE`、`.INE`、`.DCE`、`.CZCE`、`.CFFEX`、`.GFEX`；短后缀 `.SHF`、`.CZC`、`.CFE`、`.GFE` 及其它未列出的后缀会返回 HTTP 400；无后缀的裸合约代码仍兼容。

- `--symbol` / `--symbols` 二选一，至少提供一个且不能同时传入；`start` 与 `end` 必须同时传入，时间跨度不得超过 3 个北京时间自然日。

- - 批量查询时 `symbols` 以重复参数发送（`symbols=A2611.DCE&symbols=CU2611.SHF`）；逗号分隔在接口侧也兼容。

+ - 批量查询时 `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`。