Stock Prices

# 查询单只股票分时价格（一分钟级别）

## 接口说明

| 项目     | 说明                                                                                                                                                                                                               |
|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 接口名称 | 查询单只股票分时价格（一分钟级别）                                                                                                                                                                                   |
| 外部接口 | /api/v2/stocks/:stock/prices                                                                                                                                                                                       |
| 请求方式 | GET                                                                                                                                                                                                                |
| 适用场景 | 获取 A 股指定股票在指定时间范围内的分时数据（一分钟一根），用于分时图、当日/多日走势；每条含该分钟的价格、成交量、成交额、均价、时间戳；支持从今天起、从五日前起、从 N 个交易日前起或从指定毫秒时间戳起；响应含昨收与当前交易日 |

## 请求参数

说明：stock 为路径参数（必填）；时间范围由 since 或 since_ts_ms 二选一指定（不传 since 时必传 since_ts_ms）。

| 参数名      | 类型   | 是否必填 | 描述                            | 取值示例                               | 备注                                             |
|-------------|--------|----------|---------------------------------|----------------------------------------|--------------------------------------------------|
| stock       | string | 是       | 股票标的键（路径参数，带市场后缀） | 688295.XSHG、000001.SZ、920036.BJ        | 沪 .XSHG、深 .SZ、北交所 .BJ                       |
| since       | string | 条件必填 | 时间范围起点（语义）              | TODAY、FIVE_DAYS_AGO、TRADE_DAYS_AGO(10) | 见下方取值说明；与 since_ts_ms 二选一             |
| since_ts_ms | long   | 条件必填 | 时间范围起点（毫秒时间戳）        | 1735689600000                          | 须属于“今天”或“最近一个交易日”；不传 since 时必传 |

since 取值说明：

| 取值              | 含义                                                   |
|-------------------|--------------------------------------------------------|
| TODAY             | 从今天（或最近一个交易日）的第一条分时数据开始           |
| FIVE_DAYS_AGO     | 从五个交易日前的第一条分时数据开始（含今天）             |
| TRADE_DAYS_AGO(n) | 从 n 个交易日前的第一条分时数据开始（含今天），n 为正整数 |

## 执行方式

通过根目录的 `run.py` 调用（推荐）：

```bash
# 从今天起的分时
python <RUN_PY> stock-prices --stock 000001.XSHG --since TODAY

# 从五日前起
python <RUN_PY> stock-prices --stock 000001.XSHG --since FIVE_DAYS_AGO

# 从 10 个交易日前起
python <RUN_PY> stock-prices --stock 000001.XSHG --since "TRADE_DAYS_AGO(10)"

# 从指定毫秒时间戳起（不传 since 时必传）
python <RUN_PY> stock-prices --stock 000001.XSHG --since_ts_ms 1735689600000
```

> `<RUN_PY>` 为主 SKILL.md 同级的 `run.py` 绝对路径，参见主 SKILL.md 的「调用方式」说明。

## 响应说明

返回指定股票的分时价格列表、昨收及当前交易日，与代码 GetStockPricesReply 一致：

```json
{
    "prices": [ { "p", "v", "t", "a", "tm" }, ... ],
    "prev_close": 12.34,
    "today": 20250312
}
```

### 根字段

| 字段名     | 类型  | 是否可为空 | 说明                                     |
|------------|-------|------------|------------------------------------------|
| prices     | array | 否         | 分时价格列表，按时间正序；单条结构见下表   |
| prev_close | float | 是         | 昨收价（用于分时涨跌幅等计算）；无时为 null |
| today      | int   | 否         | 当前交易日，YYYYMMDD 格式                 |

### 分时单条结构（prices 元素，对应 PriceShortKey）

| 字段名 | 类型  | 是否可为空 | 说明                   | 单位 |
|--------|-------|------------|------------------------|------|
| p      | float | 否         | 该分钟价格             | 元   |
| v      | long  | 否         | 该分钟成交量           | 股   |
| t      | float | 否         | 该分钟成交额           | 元   |
| a      | float | 是         | 该分钟均价（若有）       | 元   |
| tm     | long  | 否         | 该分钟对应时间戳（毫秒） | ms   |

## 注意事项

- stock 为必填；since 与 since_ts_ms 二选一，必须提供其一
- 股票代码需携带市场后缀：沪市 .XSHG、深市 .SZ、北交所 .BJ
- since 为 TRADE_DAYS_AGO(n) 时需带括号和数字，如 TRADE_DAYS_AGO(10)
- 所有接口请求需携带 X-Client-Name: ft-claw 请求头
- 执行方式：脚本在输出前将 `prices` 中每条记录的 `tm`（毫秒）转为北京时间 ISO 字符串（YYYY-MM-DDTHH:mm:ss）；`since` 与 `since_ts_ms` 二选一，两个都不传或两个都传时报 `ValueError` 并退出。
- 接口返回的是前复权数据，且不支持选择复权