# KlineShare 行情 API 参考

A 股**实时行情**、**分时图**、多周期 **K 线**、**股票信息**、**上市公司资料**、**交易日历**、**涨停专题**、**龙虎榜**、**游资名录**；沪深 ETF 走专用 `/v1/etf*` 路径。基础地址：`/v1`。

套餐档位、scope 与主要指数列表为动态配置，以 `GET /public/v1/catalog` 为准。

## 鉴权

除 `GET /v1/health`、本文档与 `/public/v1/*` 元数据外，数据接口均需 API Key。

```http
GET /v1/realtime?symbol=603778.SS
X-API-Key: tg_xxxxxxxxxxxxxxxxxxxxxxxx
```

也支持查询参数 `?api_key=tg_xxx`（不推荐，易泄露到日志）。Key 在用户中心签发，**完整 Key 仅显示一次**。

## 权限说明

权限分两层：**接口权限（scope）** 与 **K 线数据策略**。

### 接口权限

未开通相应 scope 时返回 `403`。各套餐接口差异见 `GET /public/v1/catalog` 的 `scope_rows`（含各档位 ✓/— 对照）与 `tier_columns`。

### K 线数据策略

在拥有 `kline` scope 的前提下，限制可请求的周期、条数、复权方式与技术指标。超出套餐上限时条数会自动裁切。`GET /v1/me` 可查看当前 Key 的 `kline` 摘要。

### 账号状态

- 用户中心「接口测试」无有效 Key → `403`
- 账号已过期 → `401`
- 账号或 Key 已禁用 → `401` / `403`

## 限流规则

采用**每分钟固定窗口**计数：全局限流（账号下所有接口合计）与各 scope 分接口限流。触发限流返回 `429`，响应含 `retry_after`（秒），Header 含 `Retry-After`。

## 接口列表

| 方法 | 路径 | 鉴权 |
|------|------|------|
| GET | `/v1/health` | 否 |
| GET | `/v1/realtime` | Key + `realtime` |
| GET | `/v1/trend` | Key + `trend` |
| GET | `/v1/kline` | Key + `kline` |
| GET | `/v1/bj/trend` | Key + `trend`（北交所 T+1） |
| GET | `/v1/bj/kline` | Key + `kline`（北交所 T+1） |
| GET | `/v1/stock` | Key + `stock` |
| GET | `/v1/stocks` | Key + `stock` |
| GET | `/v1/corp` | Key + `corp` |
| GET | `/v1/calendar` | Key + `calendar` |
| GET | `/v1/limit-up` | Key + `limit_up`（**旗舰版**；基础/专业 **试用 2 次/日**） |
| GET | `/v1/limit-up/break` | Key + `limit_up`（**旗舰版**；基础/专业 **试用 2 次/日**） |
| GET | `/v1/limit-up/limit-down` | Key + `limit_up`（**旗舰版**；基础/专业 **试用 2 次/日**） |
| GET | `/v1/limit-up/yesterday` | Key + `limit_up`（**旗舰版**；基础/专业 **试用 2 次/日**） |
| GET | `/v1/limit-up/ladder` | Key + `limit_up`（**旗舰版**；基础/专业 **试用 2 次/日**） |
| GET | `/v1/limit-up/plates/trending` | Key + `limit_up`（**旗舰版**；基础/专业 **试用 2 次/日**） |
| GET | `/v1/limit-up/plates/industry` | Key + `limit_up`（**旗舰版**；基础/专业 **试用 2 次/日**） |
| GET | `/v1/limit-up/plates/concept` | Key + `limit_up`（**旗舰版**；基础/专业 **试用 2 次/日**） |
| GET | `/v1/limit-up/plates/style` | Key + `limit_up`（**旗舰版**；基础/专业 **试用 2 次/日**） |
| GET | `/v1/abnormal-events` | Key + `abnormal_events`（**旗舰版**；基础/专业 **试用 2 次/日**） |
| GET | `/v1/abnormal-events/stream` | Key + `abnormal_events`（**旗舰版**；基础/专业 **试用 2 次/日**，SSE 订阅） |
| GET | `/v1/market-flash/stream` | Key + `market_flash`（**旗舰版**；基础/专业 **试用 2 次/日**，SSE 订阅） |
| GET | `/v1/lhb/daily` | Key + `lhb` |
| GET | `/v1/lhb/stock` | Key + `lhb` |
| GET | `/v1/lhb/dates` | Key + `lhb` |
| GET | `/v1/lhb/stats` | Key + `lhb` |
| GET | `/v1/lhb` | Key + `lhb` |
| GET | `/v1/hot-money` | Key + `hot_money` |
| GET | `/v1/hot-money/seat` | Key + `hot_money` |
| GET | `/v1/moneyflow/daily-trend` | Key + `moneyflow`（专业版、旗舰版） |
| GET | `/v1/moneyflow/stage` | Key + `moneyflow`（专业版、旗舰版） |
| GET | `/v1/moneyflow/distribution` | Key + `moneyflow`（专业版、旗舰版） |
| GET | `/v1/etf` | Key + `etf`（专业版、旗舰版） |
| GET | `/v1/etfs` | Key + `etf`（专业版、旗舰版） |
| GET | `/v1/etf/realtime` | Key + `etf_realtime`（专业版、旗舰版） |
| GET | `/v1/etf/trend` | Key + `etf_trend`（专业版、旗舰版） |
| GET | `/v1/etf/kline` | Key + `etf_kline`（专业版、旗舰版） |
| GET | `/public/v1/corp/schema` | 否 |
| GET | `/public/v1/moneyflow/schema` | 否 |
| GET | `/public/v1/etf/schema` | 否 |
| GET | `/public/v1/indices` | 否 |
| GET | `/public/v1/catalog` | 否 |
| GET | `/v1/me` | Key |

## 健康检查

```http
GET /v1/health
```

无需 Key。响应示例：

```json
{ "success": true, "version": "1" }
```

## 实时行情

```http
GET /v1/realtime?symbol=603778.SS
GET /v1/realtime?symbol=000001.SS
GET /v1/realtime?symbol=600519.SS&symbol=603778.SS
GET /v1/realtime?symbol=600519.SS,000001.SS
GET /v1/realtime?symbol=603778.SS&include_valuation=true
GET /v1/realtime?symbol=603778.SS&include_depth=true
```

| 参数 | 必填 | 说明 |
|------|------|------|
| symbol | 是 | 股票或主要指数代码；可重复传参，或用逗号/分号分隔；单次上限见套餐（基础 20、专业 40、旗舰 60） |
| include_valuation | 否 | `1` / `true` / `yes` / `on` 时额外返回估值字段（需对应 scope，见 catalog `realtime_feature_gates`） |
| include_depth | 否 | `1` / `true` / `yes` / `on` 时额外返回买卖五档（需对应 scope，见 catalog `realtime_feature_gates`） |

单只时 `data` 为对象；多只时 `data` 为数组。部分未命中时 HTTP 200，`meta.missing` 列出未找到的代码。指数响应 `meta.instrument_type` 为 `index`。

| 字段 | 说明 |
|------|------|
| symbol | 标准代码，如 `603778.SS` |
| timestamp | 行情时间戳（毫秒） |
| date | 交易日期 YYYYMMDD |
| price / close | 最新价 |
| open / high / low | 开高低 |
| volume / turnover | 成交量、成交额 |
| name | 证券简称 |
| change_percent | 涨跌幅（小数，0.1 表示 10%） |
| change | 涨跌额 |
| trade_status | 交易状态，如 `TRADE` |

`include_valuation=true` 时额外返回：

| 字段 | 说明 |
|------|------|
| valuation | PE/PB/市值等：`pe_ttm`、`pe_dynamic`、`pb`、`bps`、`total_market_cap`（亿元）、`circulation_market_cap`（亿元）、`total_shares` / `circulation_shares`（万股） |
| quote | 顶层未包含的扩展行情：`pre_close`、`turnover_ratio`、`amplitude`、`volume_ratio`、`time` |

需 `realtime_valuation` scope（默认映射见 `realtime_feature_gates`）。

`include_depth=true` 时额外返回 `depth`（需 `realtime_depth` scope，映射见 `realtime_feature_gates`）：

| 字段 | 说明 |
|------|------|
| depth.bids[] | 买盘五档，每项 `price` / `volume` / `orders` |
| depth.asks[] | 卖盘五档，每项 `price` / `volume` / `orders` |
| depth.inner_volume | 内盘成交量（主动卖） |
| depth.outer_volume | 外盘成交量（主动买） |

需 `realtime` 权限（**基础版**及以上）。当前 Key 单次上限见 `GET /v1/me` 的 `max_realtime_symbols`。

**ETF 不可走本接口**（返回 400），须改用 `/v1/etf/realtime` 等专用路径。

**北交所不可走本接口**（返回 400），须改用 `/v1/bj/kline` 或 `/v1/bj/trend`。

## 北交所行情（T+1）

北交所与沪深接口分离，行情为 **T+1**。

```http
GET /v1/bj/kline?symbol=920000.BJ&period=86400&adjust_type=forward&count=256
GET /v1/bj/trend?symbol=920000.BJ&date=20250620
```

| 接口 | scope | 说明 |
|------|-------|------|
| `/v1/bj/kline` | `kline` | 参数同 `/v1/kline`；支持全部周期及前/后/不复权（分钟线由 1m 聚合与复权因子计算） |
| `/v1/bj/trend` | `trend` | 须传 `date=YYYYMMDD` |

代码格式：`920000.BJ` 或 `bj920000`。

## 主要指数

实时、分时、K 线接口支持多个主要指数（与个股共用 `realtime` / `trend` / `kline` scope）。完整列表：

```http
GET /public/v1/indices
```

响应 `data[]` 含 `symbol`、`name`、`group`；股指期货类另含 `futures`（IF/IH/IC/IM）。

裸写 `000001` 会解析为个股平安银行（`000001.SZ`），查询上证请用 `000001.SS`。

暂未提供行情数据的指数（如北证50 `899050`、中证2000 `932000`、中证全指 `000985`）。

指数 K 线无复权，统一按 `adjust_type=none` 返回（见 `meta.hints`）。

## 分时图

```http
GET /v1/trend?symbol=300042.SZ
GET /v1/trend?symbol=000001.SS
GET /v1/trend?symbol=399006.SZ&date=20250620
```

需 `trend` 权限（**基础版**及以上）。**每次仅 1 只** symbol；可选 `date=YYYYMMDD` 查询历史交易日分时。

响应 `data` 结构：

| 字段 | 说明 |
|------|------|
| data[] | 分时 tick 列表 |
| pre_close | 昨收价 |
| total | tick 总数 |

`data[]` 每项含 `timestamp`（毫秒）、`price`、`avg_price`、`volume`、`turnover`、`open`、`high`、`low`、`change`、`change_percent`。`meta` 含 `symbol`、`instrument_type`、`tick_count`；历史分时另含 `date`。

## K 线

复权方式由管理后台配置，**所有 K 线拉取路径**（含盘中实时、快照窗口）均遵循：

- `direct`：按 `adjust_type` 从接口拉**已复权** K
- `factor`：从接口拉**不复权** K，再按复权因子动态换算（快照/本地冷存同理：先 none、合入当日 bar、再换算）

`meta.adjust_mode` 返回当前配置。复权因子见 [`/v1/adjust-factors`](#adjust-factors)。

```http
GET /v1/kline?symbol=603778.SS&period=86400&adjust_type=forward&count=256
GET /v1/kline?symbol=000001.SS&period=86400&count=120
GET /v1/kline?symbol=600519.SS&count=120&indicators=ma:5,10,20&indicators=rsi:14&indicators=macd:12,26,9&indicators=boll:20,2
```

| 参数 | 必填 | 默认 | 说明 |
|------|------|------|------|
| symbol | 是 | - | 股票或主要指数代码 |
| period | 否 | 86400 | 周期（秒） |
| adjust_type | 否 | forward | 复权类型：`forward`（前复权）、`backward`（后复权）、`none`（不复权）；受套餐限制 |
| count | 否 | 256 | 返回 K 线条数，受套餐上限裁切 |
| timestamp | 否 | - | 结束时间戳（秒），向前加载更多 |
| indicators | 否 | - | 可选技术指标，可重复传参或使用分号分隔 |

请求指标时，每根 K 线在 `data[]` 元素内附带 `indicators` 对象；预热不足处为 `null`。计算指标时会自动多拉若干根 K 线用于预热（见 `meta.warmup_bars`，不计入 count）。

`data[].indicators` 结构示例：

```json
{
  "date": "20250620",
  "close": 105.2,
  "indicators": {
    "ma:5,10,20": { "5": 104.2, "10": 103.1, "20": 102.0 },
    "rsi:14": { "14": 55.3 },
    "macd:12,26,9": { "dif": 0.5, "dea": 0.3, "macd": 0.4 },
    "boll:20,2": { "upper": 110.0, "mid": 105.0, "lower": 100.0 }
  }
}
```

| indicators 取值 | 默认参数 | data[].indicators 字段 |
|-----------------|----------|------------------------|
| ma / ma:5,10,20 | 5,10,20 | 周期键名如 "5", "10" |
| ema / ema:12,26 | 12,26 | 周期键名 |
| rsi / rsi:14 | 14 | 周期键名 |
| macd / macd:12,26,9 | 12,26,9 | dif / dea / macd |
| boll / boll:20,2 | 20,2 | upper / mid / lower |

可用指标种类与单次上限见 `GET /v1/me` 的 `kline.allowed_indicators_label`、`kline.max_indicator_specs`。

**周期取值（period 秒）：**

| period | 含义 |
|--------|------|
| 60 | 1 分钟 |
| 300 | 5 分钟 |
| 900 | 15 分钟 |
| 1800 | 30 分钟 |
| 3600 | 60 分钟 |
| 86400 | 日线 |
| 604800 | 周线 |
| 2592000 | 月线 |

K 线 `data[]` 每项含 `timestamp`（毫秒）、`date`、`open`、`high`、`low`、`close`、`volume`、`turnover`。

## 复权因子 {#adjust-factors}

```http
GET /v1/adjust-factors?symbol=603778.SS&adjust_type=forward&count=256
GET /v1/adjust-factors?symbol=600519.SS&adjust_type=backward&start=20240101&end=20241231
```

| 参数 | 必填 | 默认 | 说明 |
|------|------|------|------|
| symbol | 是 | - | 股票代码 |
| adjust_type | 否 | forward | `forward`（前复权因子）、`backward`（后复权因子） |
| count | 否 | - | 返回最近 N 条；与 start/end 可组合 |
| start / bdate | 否 | - | 起始日期 YYYYMMDD |
| end / edate | 否 | - | 结束日期 YYYYMMDD |

权限与 `/v1/kline` 共用 `kline` scope；`adjust_type` 受套餐复权权限限制。

`data[]` 每项含 `date`（YYYYMMDD）、`factor`（复权因子）。换算约定：复权价 = 原始价 / factor。

`meta` 含 `symbol`、`adjust_type`、`count`、`adjust_mode`（当前复权方式：`direct` | `factor`）。

## 股票信息

```http
GET /v1/stock?symbol=600519.SS
GET /v1/stocks?keyword=茅台&limit=20
GET /v1/stocks?market=sh&page=1&num=100
```

| 路径 | 参数 | 说明 |
|------|------|------|
| `/v1/stock` | symbol | 单只查询，如 `603778.SS` |
| `/v1/stocks` | keyword, market, limit | 按名称或代码搜索，最多 200 条 |
| `/v1/stocks` | market, page, num | 分页列表；market 可选 sh、sz、bj |

`/v1/stock` 响应 `data` 含 `symbol`、`code`、`name`、`market`、`update_time`。`/v1/stocks` 搜索时 `data` 为数组；分页时 `meta` 含 `page`、`count`、`total`、`market`，以及可选 `list.update_time` / `list.total_stocks`。

## ETF 专用接口

响应 `meta.instrument_type` 恒为 `etf`。部分新上市 ETF 可能暂不可用。

沪深 ETF 与 A 股个股**强制拆分**：清单、基本信息、实时、分时、K 线均须走 `/v1/etf*` 路径。个股/指数接口对 ETF 代码返回 400。

**权限：专业版及以上**（`pro` / `premium`）。免费版、基础版返回 403。

```http
GET /v1/etf?symbol=515250.SS
GET /v1/etfs?keyword=智能汽车&limit=20
GET /v1/etf/realtime?symbol=515250.SS
GET /v1/etf/trend?symbol=515250.SS
GET /v1/etf/kline?symbol=515250.SS&period=86400&count=120
GET /public/v1/etf/schema
```

| 路径 | scope | 说明 |
|------|-------|------|
| `/v1/etf` | etf | 单只 ETF 基本信息；symbol 如 `515250.SS`、`159915.SZ`，亦支持 6 位代码 |
| `/v1/etfs` | etf | 搜索（keyword）或分页列表；支持 `market`（sh/sz）、`category` 筛选 |
| `/v1/etf/realtime` | etf_realtime | 实时行情；symbol 可重复传参或逗号/分号分隔；单次上限见套餐（基础 20、专业 40、旗舰 60） |
| `/v1/etf/trend` | etf_trend | 分时（可选 date=YYYYMMDD） |
| `/v1/etf/kline` | etf_kline | K 线（参数同 K 线接口） |

字段说明见 `GET /public/v1/etf/schema`（无需 Key）。`/v1/etf` 的 `data` 含 symbol、code、sname、category、benchmark、aum 等；实时/分时/K 线响应结构与对应个股接口相同。

## 上市公司资料

```http
GET /v1/corp?symbol=600519.SS
GET /public/v1/corp/schema
```

| 路径 / 参数 | 必填 | 说明 |
|-------------|------|------|
| `/v1/corp` · symbol | 是 | 股票代码，如 `600519.SS` |
| `/public/v1/corp/schema` | - | 字段说明（无需 Key） |

## 交易日历

```http
GET /v1/calendar
GET /v1/calendar?date=20250620
GET /v1/calendar?start=20250101&end=20250630
```

| 参数 | 必填 | 说明 |
|------|------|------|
| date | 否 | 指定日期 YYYYMMDD，返回是否交易日及前后相邻交易日 |
| start, end | 否 | 日期区间（须同时提供），最多 366 天 |
| window | 否 | 无参数时的前后窗口天数，默认 30，最大 90 |

无参数时返回最近/下一交易日及窗口内交易日列表，并附带交易时段配置。

## 涨停专题 {#limit-up}

涨停专题（scope：`limit_up`）覆盖**涨停数据（实时）**、**连板天梯（实时）**、**板块排名**与**个股/板块异动**，盘中实时更新。

### 套餐与试用 {#limit-up-tiers}

| 套餐 | 涨停数据（实时） / 炸板数据（实时） / 跌停数据（实时） / 昨日涨停（实时） / 连板天梯（实时） / 板块排名 | 说明 |
|------|--------------------------------------|------|
| 免费版 | — | 无 `limit_up` 权限，返回 `403` |
| 基础版 | 试用 | 每日 **2 次**调用（含沙盒），超出返回 `429` |
| 专业版 | 试用 | 每日 **2 次**调用（含沙盒），超出返回 `429` |
| **旗舰版** | **正式开通** | 涨停五接口 **15 次/分钟**（合计）；板块排名 **240 次/分钟**；无日调用上限 |

**试用计数规则：**

- 各 `/v1/limit-up*` 接口**独立**计数，每个接口每日 **2 次**试用（含沙盒）。
- 额度按 **UTC+8 自然日** 零点重置。
- 试用仅用于评估接口形态与字段，**不建议**用于生产轮询；正式接入请升级 **旗舰版**。
- 超出试用额度时响应示例：`{ "success": false, "code": 429, "message": "涨停专题试用额度已用尽（2 次/日），请升级旗舰版" }`

`GET /v1/me` 与 `GET /public/v1/catalog` 的 `scope_rows` 可查看当前 Key 是否含 `limit_up` 及所属套餐。

### 接口一览 {#limit-up-routes}

```http
GET /v1/limit-up                      # 涨停数据（实时）
GET /v1/limit-up/break                # 炸板数据（实时）
GET /v1/limit-up/limit-down           # 跌停数据（实时）
GET /v1/limit-up/yesterday            # 昨日涨停（实时）— 昨日封板标的今日行情
GET /v1/limit-up/ladder               # 连板天梯（实时）— 按连板高度分组
GET /v1/limit-up/plates/trending      # 行业板块排名（实时）
GET /v1/limit-up/plates/industry      # 行业板块（实时）
GET /v1/limit-up/plates/concept       # 概念板块排名（实时）
GET /v1/limit-up/plates/style         # 风格板块排名（实时）
GET /v1/abnormal-events               # 异动历史（单次拉取）
GET /v1/abnormal-events/stream        # 异动实时订阅（SSE 长连接）
```

### 异动推送 {#abnormal-events}

盘中个股与板块异动：封板、炸板、拉升、跳水等。

**历史拉取** `GET /v1/abnormal-events`：

| 参数 | 说明 |
|------|------|
| `count` | 条数，默认 30，最大 100 |
| `types` | 逗号分隔的异动类型，不传为全部 14 类（见下表） |
| `kind` | `all` / `stock` / `plate`，默认 `all` |
| `timestamp` | 翻页游标，取上一页最后一条 `occurred_at` |

**异动类型**（`types` 参数与响应 `type` 字段）：

| type | 说明 | 类别 |
|------|------|------|
| `limit_up_seal` | 封涨停板 | 个股 |
| `limit_down_seal` | 封跌停板 | 个股 |
| `limit_up_open` | 打开涨停板 | 个股 |
| `limit_down_open` | 打开跌停板 | 个股 |
| `limit_up_near` | 逼近涨停 | 个股 |
| `limit_down_near` | 逼近跌停 | 个股 |
| `limit_up_about_open` | 即将打开涨停 | 个股 |
| `limit_down_about_open` | 即将打开跌停 | 个股 |
| `stock_surge` | 大幅拉升 | 个股 |
| `stock_plunge` | 快速跳水 | 个股 |
| `ipo_open` | 新股开板 | 个股 |
| `ipo_reseal` | 新股开板回封 | 个股 |
| `plate_surge` | 板块拉升 | 板块 |
| `plate_plunge` | 板块跳水 | 板块 |

**实时订阅** `GET /v1/abnormal-events/stream`：

- **订阅模式**：客户端发起 GET 并保持长连接（SSE），服务端在有新异动时推送；**不是**轮询历史接口。
- 同一 API Key **并发订阅数**见 `GET /v1/me` 的 `max_abnormal_events_subscriptions`（基础 **1**、专业 **2**、旗舰 **5**，可在角色中配置）；超出上限时**顶掉最早建立的连接**，被顶掉端收到 `{"type":"evicted",...}` 后断开。
- 响应类型 `text/event-stream`；首条为 `{"type":"ready","subscription":{...}}`，之后每条异动为 `{"type":"event","data":{...}}`（`data` 字段结构与历史上 `data[]` 单条一致）。
- 参数 `types`、`kind` 与历史接口相同，用于订阅过滤；约每 15 秒发送心跳注释行。
- 断开连接即取消订阅；**每次新建连接计 1 次调用**（试用额度按连接次数，非按推送条数）。
- 客户端示例：`curl -N -H "X-API-Key: tg_xxx" "https://api.example/v1/abnormal-events/stream?kind=stock"`
- 浏览器端需用 `fetch` 流式读取（原生 `EventSource` 不支持自定义 `X-API-Key` Header）。

- 鉴权：`X-API-Key` + scope `abnormal_events`。
- `sentiment`：`1` 偏多、`-1` 偏空、`0` 中性；`minute_change_percent` 为分时涨跌幅（小数）。
- 响应 `meta.types` 为本次请求的异动类型；`meta.type_catalog` 为全部类型目录。

**字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | int | 异动记录 ID |
| `kind` | string | `stock` 个股 / `plate` 板块 |
| `type` | string | 异动类型（见上表） |
| `type_label` | string | 异动类型中文名 |
| `occurred_at` | int | 发生时刻 Unix 秒 |
| `occurred_time` | string | 发生时刻 `HH:MM:SS` |
| `sentiment` | int | 多空倾向：`1` 偏多、`-1` 偏空、`0` 中性 |
| `symbol` | string | 股票代码（个股异动） |
| `name` | string | 简称（个股）或板块名（板块异动） |
| `price` | number | 现价（个股异动） |
| `change_percent` | number | 涨跌幅（小数） |
| `minute_change_percent` | number | 分时涨跌幅（小数，个股异动） |
| `plates` | array | 关联板块：`name`、`change_percent` |
| `stocks` | array | 关联个股（板块异动）：`symbol`、`name`、`change_percent` 等 |

---

## 市场快讯 {#market-flash}

市场快讯（scope：`market_flash`）为 **SSE 实时订阅**，盘中推送发布、更新与撤回事件；暂无历史拉取接口。

| 套餐 | 快讯订阅 | 说明 |
|------|----------|------|
| 免费版 | — | 无 `market_flash` 权限，返回 `403` |
| 基础版 | 试用 | 每日 **2 次**连接（含沙盒） |
| 专业版 | 试用 | 每日 **2 次**连接（含沙盒） |
| **旗舰版** | **正式开通** | 按角色 `market_flash` 限流；无日连接上限 |

```http
GET /v1/market-flash/stream        # 市场快讯实时订阅（SSE 长连接）
```

**实时订阅** `GET /v1/market-flash/stream`：

- **订阅模式**：客户端发起 GET 并保持长连接（SSE），服务端在有新快讯时推送。
- 同一 API Key **并发订阅数**见 `GET /v1/me` 的 `max_market_flash_subscriptions`（基础 **1**、专业 **2**、旗舰 **5**，可在角色中配置）；超出上限时**顶掉最早建立的连接**，被顶掉端收到 `{"type":"evicted",...}` 后断开。
- 响应类型 `text/event-stream`；首条为 `{"type":"ready","subscription":{...}}`，之后每条为 `{"type":"event","data":{...}}`。
- 参数 `actions`：逗号分隔，可选 `publish`（发布）、`update`（更新）、`withdraw`（撤回）；不传为全部。
- 参数 `include_withdrawn`：传 `1`/`true` 时包含已撤回条目；默认过滤。
- 约每 15 秒发送心跳注释行；断开连接即取消订阅；**每次新建连接计 1 次调用**。
- 鉴权：`X-API-Key` + scope `market_flash`。

**字段说明**（`data` 单条）：

| 字段 | 类型 | 说明 |
|------|------|------|
| `action` | string | `publish` / `update` / `withdraw` |
| `action_label` | string | 动作中文名 |
| `title` | string | 标题 |
| `summary` | string | 摘要（可选） |
| `content` | string | 正文（可选） |
| `subtitle` | string | 副标题（可选） |
| `occurred_at` | int | 发生时刻 Unix 秒 |
| `occurred_time` | string | 发生时刻 `HH:MM:SS` |
| `updated_at` | int | 更新时间 Unix 秒（可选） |
| `sentiment` | int | 多空倾向：`1` 偏多、`-1` 偏空、`0` 中性 |
| `is_withdrawn` | bool | 是否已撤回 |
| `has_summary` | bool | 是否有摘要 |
| `image` | string | 配图 URL（可选） |
| `plates` | array | 关联板块：`name`、`change_percent` |
| `stocks` | array | 关联个股：`symbol`、`name`、`change_percent` |

---

### 涨停专题（续） {#limit-up-continued}

**通用约定：**

- 鉴权：`X-API-Key` + scope `limit_up`。
- 涨停数据（实时）与连板天梯（实时）**无请求参数**，返回当日盘中快照。
- **旗舰版**涨停五接口（`/v1/limit-up`、`/break`、`/limit-down`、`/yesterday`、`/ladder`）共用 **15 次/分钟** 限流；板块排名仍按 `limit_up` **240 次/分钟**。
- 板块排名支持 `limit`（默认 50，最大 200）；行业/概念/风格另支持 `field`（排序字段，默认 `core_avg_pcp` 核心均涨幅）。
- 响应统一为 `{ success, data[], meta }`；`meta.as_of` 为响应时间 `YYYYMMDDHHmmss`；涨停数据（实时） `meta.count` 为全量条数（`data` 返回全部，非分页）。
- `change_percent`、`turnover_rate` 等为**小数**：`0.099962` ≈ **+9.996%**，`0.10023` ≈ **+10.023%**（已四舍五入到 6 位小数）。
- `symbol` 统一代码格式：`603778.SS`（沪）、`002962.SZ`（深）。
- 封板/炸板时刻：`first_sealed_at` 等为 Unix **秒**（UTC+8 交易时段），`*_time` 为 `HH:MM:SS` 便于展示。

---

### 涨停数据（实时） {#limit-up-pool}

`GET /v1/limit-up` — 当日盘中涨停数据（实时）。默认排序：**连板天数降序** → **首封时间升序**（越早封板越靠前）。

| 字段 | 类型 | 说明 |
|------|------|------|
| symbol | string | 股票代码，如 `002674.SZ` |
| name | string | 简称 |
| price | number | 现价 |
| change_percent | number | 涨跌幅（小数） |
| turnover_rate | number | 换手率（小数） |
| consecutive_days | int | 连板天数（含当日） |
| first_sealed_at | int | 首次封涨停 Unix 秒 |
| first_sealed_time | string | 首次封涨停 `HH:MM:SS` |
| last_sealed_at | int | 末次封涨停 Unix 秒 |
| last_sealed_time | string | 末次封涨停 `HH:MM:SS` |
| open_count | int | 开板次数（0=一字板） |

**响应示例**（2026-06-27 盘中，`data` 截取前 3 条，`meta.count=73` 为全量）：

```json
{
  "success": true,
  "data": [
    {
      "symbol": "002674.SZ",
      "name": "兴业科技",
      "price": 28.83,
      "change_percent": 0.099962,
      "turnover_rate": 0.02574,
      "consecutive_days": 6,
      "first_sealed_at": 1782437100,
      "first_sealed_time": "09:25:00",
      "last_sealed_at": 1782437100,
      "last_sealed_time": "09:25:00",
      "open_count": 0
    },
    {
      "symbol": "603595.SS",
      "name": "ST东尼",
      "price": 36.98,
      "change_percent": 0.049972,
      "turnover_rate": 0.014485,
      "consecutive_days": 6,
      "first_sealed_at": 1782437101,
      "first_sealed_time": "09:25:01",
      "last_sealed_at": 1782438076,
      "last_sealed_time": "09:41:16",
      "open_count": 2
    },
    {
      "symbol": "605366.SS",
      "name": "宏柏新材",
      "price": 14.38,
      "change_percent": 0.10023,
      "turnover_rate": 0.195887,
      "consecutive_days": 4,
      "first_sealed_at": 1782437483,
      "first_sealed_time": "09:31:23",
      "last_sealed_at": 1782455925,
      "last_sealed_time": "14:38:45",
      "open_count": 47
    }
  ],
  "meta": {
    "pool": "limit_up",
    "label": "涨停数据（实时）",
    "route": "/v1/limit-up",
    "count": 73,
    "as_of": "20260627230705"
  }
}
```

---

### 连板天梯（实时） {#limit-up-ladder}

`GET /v1/limit-up/ladder` — 根据当日涨停数据（实时），按 `consecutive_days`（连板高度）分组为梯队层级。同一高度内按**首封时间升序**排列。

| 字段 | 类型 | 说明 |
|------|------|------|
| data[].height | int | 连板高度（≥1） |
| data[].label | string | 中文标签，如 `6连板` |
| data[].count | int | 该高度涨停家数 |
| data[].stocks[] | array | 该层个股列表 |
| data[].stocks[].symbol / name | | 代码、简称 |
| data[].stocks[].price / change_percent / turnover_rate | | 现价、涨跌幅、换手率 |
| data[].stocks[].first_sealed_at / first_sealed_time | | 首封时刻 |
| data[].stocks[].last_sealed_at / last_sealed_time | | 末封时刻 |
| data[].stocks[].open_count | int | 开板次数 |

`meta.max_height` 为当前市场最高连板数；`meta.height_count` 为有天梯的层数（仅含当日有票的高度）；`meta.total_stocks` 与涨停数据（实时）总数一致。

**响应示例**（2026-06-27 盘中，`stocks` 每层截取前 2 条；实际返回该层全部个股）：

```json
{
  "success": true,
  "data": [
    {
      "height": 6,
      "label": "6连板",
      "count": 2,
      "stocks": [
        {
          "symbol": "002674.SZ",
          "name": "兴业科技",
          "price": 28.83,
          "change_percent": 0.099962,
          "turnover_rate": 0.02574,
          "first_sealed_at": 1782437100,
          "first_sealed_time": "09:25:00",
          "last_sealed_at": 1782437100,
          "last_sealed_time": "09:25:00",
          "open_count": 0
        },
        {
          "symbol": "603595.SS",
          "name": "ST东尼",
          "price": 36.98,
          "change_percent": 0.049972,
          "turnover_rate": 0.014485,
          "first_sealed_at": 1782437101,
          "first_sealed_time": "09:25:01",
          "last_sealed_at": 1782438076,
          "last_sealed_time": "09:41:16",
          "open_count": 2
        }
      ]
    },
    {
      "height": 4,
      "label": "4连板",
      "count": 2,
      "stocks": [
        {
          "symbol": "605366.SS",
          "name": "宏柏新材",
          "price": 14.38,
          "change_percent": 0.10023,
          "turnover_rate": 0.195887,
          "first_sealed_at": 1782437483,
          "first_sealed_time": "09:31:23",
          "last_sealed_at": 1782455925,
          "last_sealed_time": "14:38:45",
          "open_count": 47
        },
        {
          "symbol": "002822.SZ",
          "name": "ST中装",
          "price": 2.9,
          "change_percent": 0.050725,
          "turnover_rate": 0.033443,
          "first_sealed_at": 1782438735,
          "first_sealed_time": "09:52:15",
          "last_sealed_at": 1782439905,
          "last_sealed_time": "10:11:45",
          "open_count": 1
        }
      ]
    },
    {
      "height": 3,
      "label": "3连板",
      "count": 1,
      "stocks": [
        {
          "symbol": "000823.SZ",
          "name": "超声电子",
          "price": 28.46,
          "change_percent": 0.100116,
          "turnover_rate": 0.178575,
          "first_sealed_at": 1782437100,
          "first_sealed_time": "09:25:00",
          "last_sealed_at": 1782443469,
          "last_sealed_time": "11:11:09",
          "open_count": 21
        }
      ]
    },
    {
      "height": 2,
      "label": "2连板",
      "count": 7,
      "stocks": [
        {
          "symbol": "600228.SS",
          "name": "返利科技",
          "price": 10.79,
          "change_percent": 0.099898,
          "turnover_rate": 0.001429,
          "first_sealed_at": 1782437101,
          "first_sealed_time": "09:25:01",
          "last_sealed_at": 1782437101,
          "last_sealed_time": "09:25:01",
          "open_count": 0
        },
        {
          "symbol": "603956.SS",
          "name": "威派格",
          "price": 5.83,
          "change_percent": 0.1,
          "turnover_rate": 0.014188,
          "first_sealed_at": 1782437101,
          "first_sealed_time": "09:25:01",
          "last_sealed_at": 1782437101,
          "last_sealed_time": "09:25:01",
          "open_count": 0
        }
      ]
    },
    {
      "height": 1,
      "label": "1连板",
      "count": 61,
      "stocks": [
        {
          "symbol": "600180.SS",
          "name": "*ST瑞茂",
          "price": 1.13,
          "change_percent": 0.046296,
          "turnover_rate": 0.004784,
          "first_sealed_at": 1782437101,
          "first_sealed_time": "09:25:01",
          "last_sealed_at": 1782437101,
          "last_sealed_time": "09:25:01",
          "open_count": 0
        },
        {
          "symbol": "002568.SZ",
          "name": "百润股份",
          "price": 15.73,
          "change_percent": 0.1,
          "turnover_rate": 0.016421,
          "first_sealed_at": 1782437400,
          "first_sealed_time": "09:30:00",
          "last_sealed_at": 1782437400,
          "last_sealed_time": "09:30:00",
          "open_count": 0
        }
      ]
    }
  ],
  "meta": {
    "source": "limit_up",
    "label": "连板天梯（实时）",
    "route": "/v1/limit-up/ladder",
    "max_height": 6,
    "height_count": 5,
    "total_stocks": 73,
    "as_of": "20260627231145"
  }
}
```

> 上例当日最高 **6 连板**（兴业科技、ST东尼），共 5 个高度层、73 只涨停股。若某高度当日无涨停股，该层不会出现在 `data` 中（如无 5 连板层）。

---

### 炸板数据（实时） {#limit-up-break}

`GET /v1/limit-up/break` — 曾触涨停但未封住的标的。默认排序：**炸板次数降序** → **首次炸板时间升序**。

| 字段 | 类型 | 说明 |
|------|------|------|
| symbol / name / price / change_percent / turnover_rate | | 同涨停数据（实时） |
| consecutive_days | int | 连板天数（触板语境，非封板） |
| first_limit_up_at | int | 首次触涨停 Unix 秒 |
| first_limit_up_time | string | 首次触涨停 `HH:MM:SS` |
| first_break_at | int | 首次炸板 Unix 秒 |
| first_break_time | string | 首次炸板 `HH:MM:SS` |
| break_count | int | 炸板次数 |

**响应示例**（2026-06-27 盘中，截取前 3 条）：

```json
{
  "success": true,
  "data": [
    {
      "symbol": "605366.SS",
      "name": "宏柏新材",
      "price": 14.38,
      "change_percent": 0.10023,
      "turnover_rate": 0.195887,
      "consecutive_days": 4,
      "first_limit_up_at": 1782437483,
      "first_limit_up_time": "09:31:23",
      "first_break_at": 1782437498,
      "first_break_time": "09:31:38",
      "break_count": 47
    },
    {
      "symbol": "002962.SZ",
      "name": "五方光电",
      "price": 19.34,
      "change_percent": 0.100114,
      "turnover_rate": 0.257957,
      "consecutive_days": 1,
      "first_limit_up_at": 1782440109,
      "first_limit_up_time": "10:15:09",
      "first_break_at": 1782440223,
      "first_break_time": "10:17:03",
      "break_count": 41
    },
    {
      "symbol": "603650.SS",
      "name": "彤程新材",
      "price": 85.83,
      "change_percent": 0.099962,
      "turnover_rate": 0.058396,
      "consecutive_days": 1,
      "first_limit_up_at": 1782438000,
      "first_limit_up_time": "09:40:00",
      "first_break_at": 1782438018,
      "first_break_time": "09:40:18",
      "break_count": 33
    }
  ],
  "meta": {
    "pool": "break_limit_up",
    "label": "炸板数据（实时）",
    "route": "/v1/limit-up/break",
    "count": 73,
    "as_of": "20260627230705"
  }
}
```

> 同一只股票可能**同时**出现在涨停数据（实时）与炸板数据（实时）中（如宏柏新材：当日仍封住涨停，但盘中多次开板，炸板数据按触板记录统计）。

---

### 跌停数据（实时） {#limit-up-limit-down}

`GET /v1/limit-up/limit-down` — 当日盘中跌停数据（实时）。默认排序：**连续跌停天数降序** → **首次封跌停时间升序**。

| 字段 | 类型 | 说明 |
|------|------|------|
| symbol / name / price / change_percent / turnover_rate | | 同涨停数据（实时） |
| consecutive_down_days | int | 连续跌停天数 |
| first_sealed_at / first_sealed_time | | 首次封跌停 |
| last_sealed_at / last_sealed_time | | 末次封跌停 |
| break_count | int | 打开跌停次数 |

**响应示例**（2026-06-27 盘中，截取前 3 条）：

```json
{
  "success": true,
  "data": [
    {
      "symbol": "603272.SS",
      "name": "*ST联翔",
      "price": 24.03,
      "change_percent": -0.049822,
      "turnover_rate": 0.046138,
      "consecutive_down_days": 7,
      "first_sealed_at": 1782437101,
      "first_sealed_time": "09:25:01",
      "last_sealed_at": 1782442601,
      "last_sealed_time": "10:56:41",
      "break_count": 12
    },
    {
      "symbol": "002514.SZ",
      "name": "*ST宝馨",
      "price": 2.25,
      "change_percent": -0.050633,
      "turnover_rate": 0.084896,
      "consecutive_down_days": 5,
      "first_sealed_at": 1782437100,
      "first_sealed_time": "09:25:00",
      "last_sealed_at": 1782452805,
      "last_sealed_time": "13:46:45",
      "break_count": 7
    },
    {
      "symbol": "002789.SZ",
      "name": "*ST建艺",
      "price": 11.5,
      "change_percent": -0.050372,
      "turnover_rate": 0.031766,
      "consecutive_down_days": 5,
      "first_sealed_at": 1782437577,
      "first_sealed_time": "09:32:57",
      "last_sealed_at": 1782454281,
      "last_sealed_time": "14:11:21",
      "break_count": 8
    }
  ],
  "meta": {
    "pool": "limit_down",
    "label": "跌停数据（实时）",
    "route": "/v1/limit-up/limit-down",
    "count": 44,
    "as_of": "20260627230705"
  }
}
```

---

### 昨日涨停（实时） {#limit-up-yesterday}

`GET /v1/limit-up/yesterday` — **昨日涨停**标的的**今日**行情与昨日封板信息。默认排序：**昨连板降序** → **今日涨幅降序**。

| 字段 | 类型 | 说明 |
|------|------|------|
| symbol / name / price / change_percent / turnover_rate | | **今日**行情 |
| yesterday_consecutive_days | int | 昨日连板天数 |
| yesterday_first_sealed_at / yesterday_first_sealed_time | | 昨日首封 |
| yesterday_last_sealed_at / yesterday_last_sealed_time | | 昨日末封 |
| yesterday_open_count | int | 昨日开板次数 |

**响应示例**（2026-06-27，截取前 3 条）：

```json
{
  "success": true,
  "data": [
    {
      "symbol": "002674.SZ",
      "name": "兴业科技",
      "price": 28.83,
      "change_percent": 0.099962,
      "turnover_rate": 0.02574,
      "yesterday_consecutive_days": 5,
      "yesterday_first_sealed_at": 1782350700,
      "yesterday_first_sealed_time": "09:25:00",
      "yesterday_last_sealed_at": 1782350700,
      "yesterday_last_sealed_time": "09:25:00",
      "yesterday_open_count": 0
    },
    {
      "symbol": "603595.SS",
      "name": "ST东尼",
      "price": 36.98,
      "change_percent": 0.049972,
      "turnover_rate": 0.014485,
      "yesterday_consecutive_days": 5,
      "yesterday_first_sealed_at": 1782351006,
      "yesterday_first_sealed_time": "09:30:06",
      "yesterday_last_sealed_at": 1782351006,
      "yesterday_last_sealed_time": "09:30:06",
      "yesterday_open_count": 0
    },
    {
      "symbol": "605366.SS",
      "name": "宏柏新材",
      "price": 14.38,
      "change_percent": 0.10023,
      "turnover_rate": 0.195887,
      "yesterday_consecutive_days": 3,
      "yesterday_first_sealed_at": 1782350701,
      "yesterday_first_sealed_time": "09:25:01",
      "yesterday_last_sealed_at": 1782350701,
      "yesterday_last_sealed_time": "09:25:01",
      "yesterday_open_count": 0
    }
  ],
  "meta": {
    "pool": "yesterday_limit_up",
    "label": "昨日涨停（实时）",
    "route": "/v1/limit-up/yesterday",
    "count": 91,
    "as_of": "20260627230706"
  }
}
```

---

### 行业板块排名（实时） {#limit-up-plates-trending}

`GET /v1/limit-up/plates/trending` — **行业板块排名（实时）**推荐列表，含说明文案与代表股。

| 参数 | 必填 | 说明 |
|------|------|------|
| limit | 否 | 返回条数，默认 50，最大 200 |

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 板块 ID |
| name | string | 板块名称 |
| description | string | 风口说明（与 `reason` 通常一致） |
| change_percent | number | 核心均涨幅 |
| rise_count / fall_count / limit_up_count | int | 涨/跌/涨停家数 |
| fund_flow | number | 板块资金流向（元，可正可负） |
| reason | string | 热点原因（若有） |
| stocks[] | array | 代表股 `{ symbol, name }` |

**响应示例**（`?limit=3`，2026-06-27）：

```json
{
  "success": true,
  "data": [
    {
      "id": 92084622,
      "name": "玻璃基板封装",
      "change_percent": 0.012489,
      "rise_count": 24,
      "fall_count": 20,
      "limit_up_count": 5,
      "fund_flow": 1155415232.15,
      "reason": "康宁发布光学互连组件“玻璃桥”",
      "description": "康宁发布光学互连组件“玻璃桥”",
      "stocks": [
        { "symbol": "002962.SZ", "name": "五方光电" },
        { "symbol": "002106.SZ", "name": "莱宝高科" }
      ]
    },
    {
      "id": 6374814,
      "name": "大硅片",
      "change_percent": 0.047813,
      "rise_count": 15,
      "fall_count": 4,
      "limit_up_count": 2,
      "fund_flow": 2447353099.65,
      "reason": "台媒报道称行业释放出新一轮涨价信号",
      "description": "台媒报道称行业释放出新一轮涨价信号",
      "stocks": [
        { "symbol": "002129.SZ", "name": "TCL中环" },
        { "symbol": "605399.SS", "name": "晨光新材" }
      ]
    },
    {
      "id": 52153249,
      "name": "光刻机（胶）",
      "change_percent": 0.006207,
      "rise_count": 34,
      "fall_count": 40,
      "limit_up_count": 3,
      "fund_flow": -5616568797.29,
      "reason": "SK海力士计划募资近300亿美元，用于晶圆厂建设和EUV光刻机采购",
      "description": "SK海力士计划募资近300亿美元，用于晶圆厂建设和EUV光刻机采购",
      "stocks": [
        { "symbol": "603650.SS", "name": "彤程新材" },
        { "symbol": "603928.SS", "name": "兴业股份" }
      ]
    }
  ],
  "meta": {
    "kind": "trending",
    "label": "行业板块排名（实时）",
    "route": "/v1/limit-up/plates/trending",
    "limit": 3,
    "count": 3,
    "updated_at": 1782489000,
    "as_of": "20260627230706"
  }
}
```

---

### 行业板块（实时） {#limit-up-plates-industry}

`GET /v1/limit-up/plates/industry` — **行业板块**按核心均涨幅排名。

| 参数 | 必填 | 说明 |
|------|------|------|
| limit | 否 | 默认 50，最大 200 |
| field | 否 | 排序字段，默认 `core_avg_pcp` |

| 字段 | 类型 | 说明 |
|------|------|------|
| id / name | | 板块 ID、名称 |
| change_percent | number | 核心均涨幅 |
| rise_count / fall_count / limit_up_count | int | 涨/跌/涨停家数 |
| fund_flow | number | 资金流向 |
| reason | string | 热点原因（若有） |

**响应示例**（`?limit=3`）：

```json
{
  "success": true,
  "data": [
    {
      "id": 22114510,
      "name": "玻纤",
      "change_percent": 0.03798,
      "rise_count": 8,
      "fall_count": 4,
      "limit_up_count": 1,
      "fund_flow": 531236928.93
    },
    {
      "id": 19771457,
      "name": "有机硅",
      "change_percent": 0.015502,
      "rise_count": 15,
      "fall_count": 16,
      "limit_up_count": 3,
      "fund_flow": -1320593432.19
    },
    {
      "id": 18533889,
      "name": "橡胶",
      "change_percent": 0.014571,
      "rise_count": 3,
      "fall_count": 4,
      "limit_up_count": 1,
      "fund_flow": -179699544.85
    }
  ],
  "meta": {
    "kind": "industry",
    "rank_type": 2,
    "label": "行业板块（实时）",
    "route": "/v1/limit-up/plates/industry",
    "field": "core_avg_pcp",
    "limit": 3,
    "count": 3,
    "as_of": "20260627230706"
  }
}
```

---

### 概念板块排名（实时） {#limit-up-plates-concept}

`GET /v1/limit-up/plates/concept` — **概念板块**按核心均涨幅排名。参数与字段同行业板块。

**响应示例**（`?limit=3`）：

```json
{
  "success": true,
  "data": [
    {
      "id": 6374814,
      "name": "大硅片",
      "change_percent": 0.047813,
      "rise_count": 15,
      "fall_count": 4,
      "limit_up_count": 2,
      "fund_flow": 2447353099.65,
      "reason": "台媒报道称行业释放出新一轮涨价信号"
    },
    {
      "id": 65767826,
      "name": "中芯国际概念股",
      "change_percent": 0.023123,
      "rise_count": 32,
      "fall_count": 20,
      "limit_up_count": 3,
      "fund_flow": -4685472299.99
    },
    {
      "id": 67510926,
      "name": "电子布",
      "change_percent": 0.017528,
      "rise_count": 7,
      "fall_count": 5,
      "limit_up_count": 0,
      "fund_flow": 643881263.89
    }
  ],
  "meta": {
    "kind": "concept",
    "rank_type": 1,
    "label": "概念板块（实时）",
    "route": "/v1/limit-up/plates/concept",
    "field": "core_avg_pcp",
    "limit": 3,
    "count": 3,
    "as_of": "20260627230706"
  }
}
```

---

### 风格板块排名（实时） {#limit-up-plates-style}

`GET /v1/limit-up/plates/style` — **风格板块**按核心均涨幅排名。参数与字段同行业板块。

**响应示例**（`?limit=3`）：

```json
{
  "success": true,
  "data": [
    {
      "id": 13492121,
      "name": "筹码集中",
      "change_percent": 0.002912,
      "rise_count": 8,
      "fall_count": 12,
      "limit_up_count": 3,
      "fund_flow": -151005399.3
    },
    {
      "id": 24898553,
      "name": "ST股",
      "change_percent": -0.004751,
      "rise_count": 74,
      "fall_count": 115,
      "limit_up_count": 13,
      "fund_flow": -990631157.62
    },
    {
      "id": 93250001,
      "name": "回购增持再贷款",
      "change_percent": -0.005521,
      "rise_count": 8,
      "fall_count": 15,
      "limit_up_count": 0,
      "fund_flow": 529549506.91
    }
  ],
  "meta": {
    "kind": "style",
    "rank_type": 3,
    "label": "风格板块（实时）",
    "route": "/v1/limit-up/plates/style",
    "field": "core_avg_pcp",
    "limit": 3,
    "count": 3,
    "as_of": "20260627230706"
  }
}
```

## 龙虎榜

```http
GET /v1/lhb/daily?date=2025-06-20&with_details=1
GET /v1/lhb/stock?symbol=600519&bdate=2025-06-01&edate=2025-06-20&with_details=1
GET /v1/lhb/dates?bdate=2020-01-01&edate=2025-06-20
GET /v1/lhb/stats?kind=stock&lastdays=5&page=1
GET /v1/lhb/stats?kind=broker&bdate=2025-06-01&edate=2025-06-20&page=1
```

需 `lhb` 权限（**专业版、旗舰版**）。也可使用 `GET /v1/lhb`（参数与 daily / stock 相同）。

### 日榜 `/v1/lhb/daily`

| 参数 | 说明 |
|------|------|
| date / tradedate | 交易日 YYYY-MM-DD，留空为最近有数据的一日 |
| with_details | `1` 含买卖前五席位 |
| with_hot_money / tag_seats | 默认 `1`，席位附加知名游资名称 |

无数据时返回 `404`。

### 单票 `/v1/lhb/stock`

| 参数 | 说明 |
|------|------|
| symbol | 股票代码 |
| bdate + edate | 区间起止日（须同时提供） |
| with_details / with_hot_money / tag_seats | 同日榜 |

### 日期 `/v1/lhb/dates`

| 参数 | 说明 |
|------|------|
| bdate / start | 区间起始日 YYYY-MM-DD（可选） |
| edate / end | 区间结束日 YYYY-MM-DD（可选） |

返回 `data.dates`（有数据的交易日列表）、`first` / `last`、`count`；可选 `with_details_count`、`updated_at`。

### 统计 `/v1/lhb/stats`

| 参数 | 说明 |
|------|------|
| kind | `stock` 个股、`broker` 营业部、`inst` 机构增仓、`inst_detail` 机构明细 |
| lastdays | 默认 5，统计最近 N 个交易日（与 bdate/edate 二选一） |
| bdate + edate | 指定区间，最多 60 个交易日 |
| page | 默认 1，每页 50 条 |

`data[]` 字段因 `kind` 而异：

| kind | 主要字段 |
|------|----------|
| stock | code、name、list_count、buy_total_10k、sell_total_10k、net_10k、buy_seats、sell_seats |
| broker | broker_name、list_count、buy/sell_total_10k、top_buy_stocks |
| inst | code、name、price、change_pct、inst_buy/sell_total_10k、inst_buy/sell_count、net_10k |
| inst_detail | code、name、tradedate、inst_buy_10k、inst_sell_10k |

`meta` 含 `kind`、`bdate`、`edate`、`days`、`page`、`count`、`total`。

### 公共字段（daily/stock）

| 字段 | 说明 |
|------|------|
| code / name | 股票代码、简称 |
| close / metric_pct | 收盘价、涨跌幅（%） |
| volume_10k_shares / amount_10k_cny | 成交量（万股）、成交额（万元） |
| type | 榜单类型 |
| reason | 上榜原因 |
| tradedate | 交易日期 |
| detail.buy[] / detail.sell[] | 席位明细 |

席位明细（`with_details=1`）每项含 `broker_code`、`broker_name`、买卖金额（`*_amount_10k_cny`）、`net_amount_10k_cny`；开启标注时含 `hot_money`（游资名称数组）。

## 个股资金流向 {#moneyflow}

```http
GET /v1/moneyflow/daily-trend?symbol=600519.SS&bdate=2025-01-01&edate=2025-06-01&limit=100
GET /v1/moneyflow/stage?symbol=600519.SS
GET /v1/moneyflow/distribution?symbol=600519.SS
GET /public/v1/moneyflow/schema
```

需 `moneyflow` 权限（**专业版、旗舰版**）。仅支持**沪深 A 股**。字段说明见 `GET /public/v1/moneyflow/schema`（无需 Key）。

### 日资金流入趋势 {#moneyflow-daily-trend}

`GET /v1/moneyflow/daily-trend` — 日级净流入、占比、主力净额等。

| 字段 | 说明 |
|------|------|
| date | 交易日 |
| trade | 收盘价 |
| changeratio | 涨跌幅（%） |
| turnover | 成交额 |
| netamount | 净流入额 |
| ratioamount | 净流入占比（%） |
| r0_net | 主力净额 |
| r0_ratio | 主力净占比（%） |
| r0x_ratio | 主力/散户净占比（%） |
| cnt_r0x_ratio | 主力/散户计数比 |
| cate_ra / cate_na | 分类占比 |

### 阶段主力动向 {#moneyflow-stage}

`GET /v1/moneyflow/stage` — 3/5/10 日阶段主力净额与占比。

| 字段 | 说明 |
|------|------|
| date | 交易日 |
| r0_net_3 / r0_ratio_3 / r0x_ratio_3 | 3 日主力净额、占比 |
| r0_net_5 / r0_ratio_5 / r0x_ratio_5 | 5 日 |
| r0_net_10 / r0_ratio_10 / r0x_ratio_10 | 10 日 |

### 历史成交分布 {#moneyflow-distribution}

`GET /v1/moneyflow/distribution` — 大/中/小/散单成交与净额分布。

| 字段 | 说明 |
|------|------|
| date | 交易日 |
| trade / changeratio / turnover | 价、涨跌幅、成交额 |
| netamount / ratioamount | 净流入额、占比 |
| r0~r3 | 大/中/小/散单成交额 |
| r0_net~r3_net | 对应净额 |

### 字段说明 {#moneyflow-schema}

`GET /public/v1/moneyflow/schema` — 三表字段定义（无需 Key）。

公共参数：

| 参数 | 必填 | 说明 |
|------|------|------|
| symbol | 是 | 股票代码 |
| date | 否 | 单个交易日 YYYY-MM-DD（与 bdate/edate 互斥） |
| bdate / start | 否 | 起始日 YYYY-MM-DD |
| edate / end | 否 | 结束日 YYYY-MM-DD |
| limit | 否 | 最多返回条数，默认 100，最大 500；`bdate`~`edate` 跨度最多 **10 日**（含首尾） |

未指定日期时默认返回最近可用交易日。`date` 与 `bdate`/`edate` 不可同时使用。

`data[]` 每项含 `date` 及对应数值字段（字符串）。`meta` 含 `symbol`、`dataset`、`label`、`count`、`as_of`。无数据时 `404`；数据暂不可用时 `503`。

## 游资名录

```http
GET /v1/hot-money
GET /v1/hot-money?name=赵老哥
GET /v1/hot-money?keyword=章
GET /v1/hot-money?q=章
GET /v1/hot-money/seat?broker=中信证券上海溧阳路
GET /v1/hot-money/seat?seat=中信证券上海溧阳路
```

需 `hot_money` 权限（**专业版、旗舰版**）。查询知名游资及其常用营业部；支持按名称精确查询、关键词搜索（`keyword` 或 `q`）、按营业部反查（`broker` 或 `seat`）。名录未就绪时返回 `503`。

| 字段 | 说明 |
|------|------|
| name | 游资名称 |
| desc | 简要说明 |
| intro | 详细介绍 |
| seats | 关联营业部名称列表 |

参数 `limit` 默认 50，最大 200（列表/搜索时有效）。`name` 与 `keyword` 不可同时使用。

`/v1/hot-money/seat` 响应 `data` 含 `broker`、`hot_money`（名称列表）、`traders`（完整条目数组）。

## 查询当前权限

```http
GET /v1/me
```

响应示例结构：

| 字段 | 说明 |
|------|------|
| account.name | 账号名称 |
| account.plan | 当前生效套餐 |
| account.expires_at | 到期时间 |
| account.subscription_active | 订阅是否有效 |
| account.subscribed_plan | 过期时原订阅套餐名 |
| key.prefix / key.label | Key 前缀与备注 |
| scopes[] | 已开通 scope；每项含 scope、name、rate_limit |
| kline | K 线策略摘要（周期、条数上限、复权、指标） |
| max_realtime_symbols | 实时 / ETF 实时单次最多 symbol 数（无权限时不返回） |
| rate_limit | 全局限流（如有） |

## 套餐档位

各档位 **K 线**周期、条数上限、复权与限流见 `GET /public/v1/catalog` 的 `tiers`。接口权限按套餐的差异见同接口返回的 `scope_rows`（矩阵：接口 × 免费/基础/专业/旗舰）。

**实时批量：** `/v1/realtime` 与 `/v1/etf/realtime` 单次 symbol 上限 — 基础 **20 只**、专业 **40 只**、旗舰 **60 只**（`tiers[].max_realtime_symbols` / `realtime_batch_limits`）。**分时**每次 **1 只**。

## 错误码

| HTTP | 含义 | 常见原因 |
|------|------|----------|
| 400 | 参数错误 | 缺少 symbol、period 无效、ETF 走错路径等 |
| 401 | 未授权 | Key 无效、账号过期、Key 已吊销 |
| 403 | 无权限 | 未开通 scope，或 K 线周期/复权不在套餐内 |
| 404 | 未找到 | 股票或公司资料暂无数据 |
| 429 | 限流 | 超过每分钟调用上限 |
| 503 | 服务不可用 | 游资名录等依赖数据暂不可用 |
| 500 | 服务器错误 | 服务暂时不可用 |

错误响应示例：

```json
{ "success": false, "code": 403, "message": "说明文字" }
```

成功响应示例：

```json
{
  "success": true,
  "data": { "...": "业务字段" },
  "meta": { "symbol": "603778.SS" }
}
```

## 调用示例

```bash
curl -s -H "X-API-Key: YOUR_KEY" "http://data.klineshare.cn/v1/realtime?symbol=603778.SS"
curl -s -H "X-API-Key: YOUR_KEY" "http://data.klineshare.cn/v1/kline?symbol=603778.SS&period=86400&count=100"
```

```python
import requests

headers = {"X-API-Key": "tg_your_key"}
r = requests.get(
    "http://data.klineshare.cn/v1/kline",
    params={
        "symbol": "603778.SS",
        "period": 86400,
        "adjust_type": "forward",
        "count": 100,
    },
    headers=headers,
    timeout=15,
)
print(r.json())
```

用户中心「接口测试」可走沙箱路径调试（计入限流）；生产环境请使用 `/v1/*` 并在请求头携带 `X-API-Key`。

## MCP（AI 客户端）

MCP 用于在**你自己使用的 AI 客户端**里直接查行情（实时、K 线、涨停等）。配置写在客户端本地或设置页，不是写在我们服务器上；调用仍走同一套 API Key、scope、限流。

**远程端点：** `http://data.klineshare.cn/mcp`（Streamable HTTP）

### 配置步骤

1. 在用户中心签发 API Key（`tg_...`）
2. 在 MCP 客户端中添加远程服务（见下方 JSON；各产品入口见门户 `/docs/mcp` 页的「兼容客户端」表）
3. 保存并**刷新 MCP 连接**，在对话中提问，例如「查 600519.SS 最近 20 根日 K」

**说明：** 只有支持 MCP 的客户端才能接入。网页版 ChatGPT 等无法安装 MCP 时，请用 REST API，或将 [`llms-full.txt`](http://data.klineshare.cn/llms-full.txt) 作为上下文交给模型阅读。

### 鉴权

与 REST 相同，任选其一：

- Header：`X-API-Key: tg_xxx`
- Header：`Authorization: Bearer tg_xxx`
- Query：`?token=tg_xxx` 或 `?api_key=tg_xxx`

### 配置 JSON

Header 传 Key（推荐）：

```json
{
  "mcpServers": {
    "klineshare": {
      "url": "http://data.klineshare.cn/mcp",
      "headers": { "X-API-Key": "tg_你的密钥" }
    }
  }
}
```

Query 传 Key：

```json
{
  "mcpServers": {
    "klineshare": {
      "url": "http://data.klineshare.cn/mcp?token=tg_你的密钥"
    }
  }
}
```

### 三种接入方式对比

| 方式 | 作用 |
|------|------|
| `/v1/*` REST | 程序、脚本、用户中心沙箱 |
| `llms-full.txt` | 让模型**读懂**接口与参数（@Docs、粘贴上下文） |
| `/mcp` | 让**已配置 MCP 的客户端**自动调工具**查数据** |

### 可用工具

`get_health`、`get_my_permissions`、`get_realtime`、`get_trend`、`get_kline`、`get_stock`、`search_stocks`、`list_stocks`、`get_corp`、`get_calendar`、`get_limit_up`、`get_limit_up_break`、`get_limit_down_pool`、`get_yesterday_limit_up`、`get_limit_up_ladder`、`get_limit_up_plates_trending`、`get_limit_up_plates_industry`、`get_limit_up_plates_concept`、`get_limit_up_plates_style`、`get_lhb`、`get_lhb_daily`、`get_lhb_stock`、`get_lhb_dates`、`get_lhb_stats`、`get_hot_money`、`get_hot_money_by_seat`、`get_moneyflow_daily_trend`、`get_moneyflow_stage`、`get_moneyflow_distribution`、`get_market_indices`、`get_public_catalog`，及 ETF 系列 `get_etf`、`search_etfs`、`get_etf_realtime`、`get_etf_trend`、`get_etf_kline`（专业版、旗舰版）。

配置后在对话中直接提问即可触发工具；调用计入与普通 REST 相同的 scope 与限流。