# 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`。

## 怎么用文档

左侧 **数据接口** 与用户中心「接口测试」同分类、同入口名。
点击某一项打开该接口的**使用说明**（参数、字段、示例）。

| 文档分区 | 内容 |
|------|------|
| [行情与 K 线](/docs/market) | compact / 沪深 / 北交所 / 竞价 / 指数 / 分时 / K 线 |
| [扩展行情](/docs/extended) | 贵金属、期货、全球指数/债券、站内板块 |
| [证券与资料](/docs/instruments) | ETF、债券、资料、日历 |
| [专题数据](/docs/topics) | 涨停、异动、快讯、龙虎榜、资金流 |

## 健康检查

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

无需 Key。响应示例：

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

## 实时行情 {#realtime}
```http
GET /v1/realtime?symbol=603778.SS
GET /v1/realtime?symbol=600519.SS&symbol=603778.SS
GET /v1/realtime?symbol=600519.SS,603778.SS
GET /v1/realtime?symbol=603778.SS&include_valuation=true
GET /v1/realtime?symbol=603778.SS&include_depth=true
```

| 参数 | 必填 | 说明 |
|------|------|------|
| symbol | 是 | 沪深 A 股个股代码；可重复传参，或用逗号/分号分隔；单次上限见 `GET /v1/me` 或 `catalog.tiers` |
| include_valuation | 否 | `1` / `true` / `yes` / `on` 时额外返回估值字段（需 `realtime_valuation`） |
| include_depth | 否 | `1` / `true` / `yes` / `on` 时额外返回买卖五档（需 `realtime_depth`） |

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

| 字段 | 说明 |
|------|------|
| 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`。

`include_depth=true` 时额外返回 `depth`（需 `realtime_depth`）：

| 字段 | 说明 |
|------|------|
| 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/index/realtime` 等专用路径。

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

## 实时行情 v2（compact） {#realtime-v2}
紧凑格式：字段名只出现一次，`data` 为字符串数组（一条一行），行内用 `|` 按 `fields` 顺序分割。适合全市场 / 大批量拉取。

```http
GET /v2/realtime?symbol=600519.SS,000001.SZ
GET /v2/realtime?all=1
GET /v2/realtime?all=1&market=SS
GET /v2/realtime?all=1&market=US
GET /v2/realtime?symbol=AAPL.US,TSLA.US
GET /v2/realtime?symbol=600519.SS&include_depth=1&include_valuation=1
```

| 参数 | 必填 | 说明 |
|------|------|------|
| symbol | 与 all 二选一 | 批量代码；A 股如 `600519.SS`，美股如 `AAPL.US`；单次上限默认 **500**（**不受**套餐 `max_realtime_symbols` 限制） |
| all | 与 symbol 二选一 | `1` 拉全市场（**无**套餐只数 / 每分钟品种配额限制） |
| market | 否 | `SS`/`SZ`/`BJ`/`CN`（A 股）或 `US`（美股，不可混用）；常与 `all=1` 联用 |
| include_valuation | 否 | 默认关；`true` 需 `realtime_valuation`，否则 403 |
| include_depth | 否 | 默认关；`true` 需 `realtime_depth`，否则 403 |

响应示例：

```json
{
  "success": true,
  "format": "compact",
  "fields": ["symbol","name","price","open","high","low","pre_close","change","change_percent","volume","turnover","timestamp","time"],
  "sep": "|",
  "data": [
    "600519.SS|贵州茅台|1294.88|1308|..."
  ],
  "meta": {
    "count": 1,
    "mode": "batch",
    "trade_date": "20260727",
    "updated_at": "2026-07-27 14:02:56"
  }
}
```

解析：`row.split(sep)` 后与 `fields[i]` 对齐。含五档时 fields 追加 `bp1,bv1,...,ap5,av5`；含估值时追加 `pe_ttm,pe_dynamic,pb,...`。

**压缩：** 请求头带 `Accept-Encoding: gzip` 时，服务端对较大响应做 gzip（`Content-Encoding: gzip`）。curl 示例：

```bash
curl -s --compressed -H "X-API-Key: YOUR_KEY" -H "Accept-Encoding: gzip" \
  "https://market-api.cn/v2/realtime?all=1&market=SS"
```

盘中全市场实时行情。需独立权限 **`realtime_v2`**（不在套餐默认 scopes 内，需单独开通；与 `/v1/realtime` 的 `realtime` 无关）。

## 沪深京个股 Tick WS {#realtime-ws}
沪深京个股 Tick 推送（与期货推送无关）。需独立权限 **`realtime_stream`**（不在套餐默认 scopes 内，需单独开通；与 HTTP `/v1/realtime` 的 `realtime` 无关）。

```text
WS /v1/realtime/ws?api_key=YOUR_KEY&symbol=600519.SS
WS /v1/realtime/ws?api_key=YOUR_KEY&symbol=600519.SS,000001.SZ,920000.BJ
```

| 参数 | 必填 | 说明 |
|------|------|------|
| api_key | 是* | 浏览器无法自定义 Header 时用 query；非浏览器亦可用 Header `X-API-Key` |
| symbol | 否 | 握手时预订阅；逗号分隔或重复 `symbol=`；单次及连接内只数见 `GET /v1/me` 的 `max_realtime_stream_symbols` |

握手后也可发 JSON 控制帧：

```json
{"op":"sub","symbols":["600519.SS","000001.SZ"],"snapshot":true}
{"op":"unsub","symbols":["000001.SZ"]}
{"op":"ping"}
```

不支持全市场订阅。同一账号并发连接数见 `GET /v1/me` 的 `max_realtime_stream_subscriptions`（超出顶掉最早连接）。握手或 JSON `sub` 单次及同一连接内合计不得超过 `max_realtime_stream_symbols`。

服务端帧：

| type | 说明 |
|------|------|
| ready | 连接就绪；可能含当前订阅 `symbols`；若顶掉旧连接则含 `evicted` |
| tick | 单票行情变化 |
| pong | 心跳应答 |
| error | 参数/权限等错误 |
| evicted | 本连接因超出并发路数被顶替 |

`tick` 主要字段：

| 字段 | 说明 |
|------|------|
| symbol | 标准码，如 `600519.SS` / `000001.SZ` / `920000.BJ` |
| name | 名称（若有） |
| t | 行情时间 |
| o / h / l / c | 开高低最新 |
| pc | 昨收 |
| ul / ll | 涨停 / 跌停 |
| v / to | 成交量 / 成交额 |
| ba | 买卖盘相关（若有） |
| s | 状态（若有） |

示例（Node / 浏览器）：

```javascript
const ws = new WebSocket(
  'wss://YOUR_HOST/v1/realtime/ws?api_key=YOUR_KEY&symbol=600519.SS'
);
ws.onmessage = (ev) => console.log(JSON.parse(ev.data));
```

## 集合竞价分时（沪深京） {#auction}
单票集合竞价过程曲线（约 09:15–09:25，1 秒一点）。**compact** 响应，与 `/v2/auction` 全市场接口 **不同权限**。

```http
GET /v1/auction?symbol=600519.SS
```

| 参数 | 必填 | 说明 |
|------|------|------|
| symbol | 是 | 标准代码，如 `600519.SS` / `000001.SZ` / `920000.BJ`；亦支持 ETF |

响应形态：

```json
{
  "success": true,
  "format": "compact",
  "fields": ["time", "price", "matched_volume", "unmatched_volume"],
  "sep": ",",
  "row_sep": ";",
  "data": "09:15:00,1355.29,0,0;09:15:01,1355.3,400,400;…",
  "meta": { "symbol": "600519.SS", "tick_count": 601, "interval": "1s", "session": "call_auction" }
}
```

解析：`data.split(row_sep)` → 每行再 `split(sep)`，与 `fields[i]` 对齐。

| 字段 | 说明 |
|------|------|
| time | `HH:MM:SS` |
| price | 虚拟匹配价 |
| matched_volume | 匹配量 |
| unmatched_volume | 未匹配量（可负，表示方向） |

最近一交易日；不支持按日查询历史。指数暂无此接口。权限 **`auction`**（基础版起）。建议请求带 `Accept-Encoding: gzip`。

## 集合竞价 v2（compact） {#auction-v2}
集合竞价时段（交易日 09:15–09:30）行情，接口形态对齐 `/v2/realtime`。

```http
GET /v2/auction?symbol=600519.SS&include_minutes=1
GET /v2/auction?all=1
GET /v2/auction?all=1&market=SS
GET /v2/auction?trade_date=20260724&all=1
```

| 参数 | 必填 | 说明 |
|------|------|------|
| symbol | 与 all 二选一 | 批量代码；单次上限默认 **500** |
| all | 与 symbol 二选一 | `1` 拉全市场 |
| market | 否 | `SS`/`SZ`/`BJ`/`CN`；常与 `all=1` 联用 |
| trade_date | 否 | `YYYYMMDD`；指定历史交易日；未指定则为当日 |
| include_minutes | 否 | 默认 **关**；显式 `1`/`true` 才带分钟。`minutes` 为 09:15–09:26 连续序列的紧凑串（见下），`volume` 为竞价撮合量（股），09:26 为开盘量 |

响应 `fields` 默认含：`symbol,name,trade_date,pre_close,match_price,change,change_percent,auction_volume,open_price,open_volume,open_amount,open_avg,minutes_n`；`include_minutes=1` 时追加 `minutes`，并返回：

- `minutes_fields`: `["time","price","volume","amount"]`
- `minutes_sep`: `,`
- `minutes_row_sep`: `;`

`minutes` 示例（一行内，无 JSON）::

  09:15,1297.41,0,0;09:20,1293.66,3400,0;09:25,1308,136600,0;09:26,1308,136600,178672800

解析：先按 `minutes_row_sep` 拆根，再按 `minutes_sep` 与 `minutes_fields` 对齐。
需独立权限 **`auction_v2`**（不在套餐默认 scopes 内）。

## 北交所行情（历史） {#bj-quote}
北交所与沪深接口分离：**无实时行情**，仅提供历史分时与 K 线。

```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`；支持全部周期及前/后/不复权 |
| `/v1/bj/trend` | `trend` | 须传 `date=YYYYMMDD` |

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

## 主要指数 {#indices}
指数与个股**强制拆分**：实时、分时、K 线须走 `/v1/index/*`，权限为独立 scope `index_realtime` / `index_trend` / `index_kline`。个股接口对指数代码返回 400。

```http
GET /v1/index/realtime?symbol=000001.SS
GET /v1/index/trend?symbol=000001.SS
GET /v2/index/kline?symbol=000001.SS,399001.SZ&period=86400&count=120
```

| 接口 | scope | 说明 |
|------|-------|------|
| `/v1/index/realtime` | `index_realtime` | 实时行情；可选 `include_valuation`（需 `index_realtime_valuation`）；不支持 `include_depth` |
| `/v1/index/trend` | `index_trend` | 分时；可选 `date=YYYYMMDD` |
| `/v2/index/kline` | `index_kline` | K 线（最多 5）；无复权；响应 `symbols` + 可选 `fields` |
| `/v1/index/kline` | `index_kline` | **过时**，请用 `/v2/index/kline` |

仅接受 `quote_ready=true` 的指数（见公开指数目录）。

精选清单（`listed=true`）：

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

全量/搜索（`limit` 默认 200、最大 2000；加 `keyword` / `listed` / `quote_ready` 任一即浏览目录）：

```http
GET /public/v1/indices?quote_ready=1
GET /public/v1/indices?listed=all&limit=2000
GET /public/v1/indices?keyword=军工&limit=20
GET /public/v1/indices?keyword=399967
GET /public/v1/indices?keyword=红利
```

| 参数 | 必填 | 默认 | 说明 |
|------|------|------|------|
| keyword | 否 | - | 名称、代码或拼音首字母 |
| listed | 否 | 浏览时 `all` | `1` 精选；`0` 非精选；`all` 全部 |
| limit | 否 | 200 | 最多 2000 |
| quote_ready | 否 | `1` | 传 `1` 进入目录浏览（与无参精选相对） |

无参数时返回精选约 48 条。目录中的指数均可用于 `/v1/index/*`。

搜索响应 `data[]` 含 `symbol`、`name`、`code`、`market`、`group`、`quote_ready`、`listed`。

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

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

指数 K 线无复权，请求时 `adjust_type` 固定为 `none`。

## 贵金属 {#metals}
贵金属独立路径与 scope：`metal_realtime` / `metal_kline`。无复权；K 线周期：`60` / `300` / `900` / `1800` / `3600` / `86400`。

覆盖分组（`meta.groups` / 条目 `groups`）：

| 分组 | 说明 |
|------|------|
| 黄金主力合约 | 现货金银、延期、纽约连续、沪金/沪银连续等 |
| 国际黄金 | 现货金银铂钯、港台黄金等 |
| 上海黄金交易所 | 延期、9999/9995、金条、铂金等 |

完整代码以 `GET /public/v1/metals` 为准（可按 `group` / `keyword` 筛选）。常见别名：`XAUUSD`→`XAU`，`AUT`→`AUT+D`。

```http
GET /public/v1/metals
GET /public/v1/metals?group=国际黄金
GET /public/v1/metals?keyword=延期
GET /v1/metal/realtime?symbols=XAU,AU9999,AU0001
GET /v2/metal/kline?symbol=XAU&period=60&count=120
GET /v2/metal/kline?symbol=XAU&period=300&count=500&timestamp=1786106100
GET /v1/metal/physical/brands
GET /v1/metal/physical/products?brand=laofengxiang
GET /v1/metal/physical/prices
GET /v1/metal/physical/prices?date=2026-08-07&brand=laofengxiang
GET /v1/metal/physical/prices?brand=laofengxiang&product=黄金价格
GET /v1/metal/physical/prices?brand=老凤祥&product=黄金&start_date=2026-08-01&end_date=2026-08-07
```

| 接口 | scope | 说明 |
|------|-------|------|
| `/public/v1/metals` | 无 | 公开清单；可选 `keyword`、`group`、`limit` |
| `/v1/metal/realtime` | `metal_realtime` | 实时快照；`symbols` 或 `symbol`，可多只 |
| `/v2/metal/kline` | `metal_kline` | K 线（最多 5；`count` 上限 1000）；响应 `fields` + `symbols`；可选 `timestamp`（秒）向前翻页，下一页用 `meta.next_timestamp` |
| `/v1/metal/physical/brands` | `metal_realtime` | 实物黄金品牌；可选 `keyword` |
| `/v1/metal/physical/products` | `metal_realtime` | 品牌下产品；可选 `brand`、`keyword` |
| `/v1/metal/physical/prices` | `metal_realtime` | **日更**金店报价。无参=最近日全表；`date`=单日；**同时传 `brand`+`product`**=该产品历史序列（`meta.mode=history`）；也可 `start_date`+`end_date`（须带 brand 或 product） |

实物日价字段：`date`、`brand_id`、`brand`、`product`、`prev_price`、`price`、`change`。历史按 `date` 升序。

开通状态见 `GET /v1/me` 与公开 `GET /public/v1/catalog`。

## 国内期货 {#futures}
国内期货独立路径与 scope：`futures_realtime` / `futures_kline` / `futures_stream`。无复权；K 线周期：`60` / `300` / `900` / `1800` / `3600` / `86400`。

**支持的交易所**

| 交易所 | 码 | 清单 / 实时 / K 线 | SSE / WS 推送 |
|--------|----|-------------------|---------------|
| 上期所 | `SHFE` | ✅ | ✅ |
| 大商所 | `DCE` | ✅ | ✅ |
| 郑商所 | `CZCE` | ✅ | ✅ |
| 能源中心 | `INE` | ✅ | ✅ |
| 中金所 | `CFFEX` | ✅ | ✅ |

**支持的代码**

| 类型 | 示例 | 说明 |
|------|------|------|
| 连续主力 | `AU0001`、`IF0001` | 品种连续合约；清单以 `*0001` 为主 |
| 近月合约 | `AU2610`、`IF2609`、`PG2612` | 品种 + YYMM；见清单 `contracts` |

**不支持**

| 项目 | 说明 |
|------|------|
| 广期所 `GFEX` | 未接入；相关品种如铂 `PT`、钯 `PD` 不可查 |
| 其它未列入交易所 / 品种 | 不在公开清单内的代码会拒绝 |

```http
GET /public/v1/futures
GET /public/v1/futures?exchange=SHFE
GET /public/v1/futures?keyword=黄金
GET /v1/futures/realtime?symbols=AU0001,AU2610,IF2609
GET /v2/futures/kline?symbol=AU0001&period=86400&count=120
GET /v2/futures/kline?symbol=AU2610&period=300&count=200&timestamp=1786106100
GET /v1/futures/stream?exchanges=SHFE
GET /v1/futures/stream?symbols=AU0001,AU2610
```

| 接口 | scope | 说明 |
|------|-------|------|
| `/public/v1/futures` | 无 | 公开清单；可选 `exchange`、`keyword`、`limit`；含交易所、品种、连续主力及近月 `contracts`（YYMM） |
| `/v1/futures/realtime` | `futures_realtime` | 实时快照；`symbols` 或 `symbol`，可多只 |
| `/v2/futures/kline` | `futures_kline` | K 线（最多 5；`count` 上限 1000）；响应 `fields` + `symbols`；可选 `timestamp`（秒）向前翻页；连续主力与真月（品种+YYMM）均可查 |
| `/v1/futures/stream` | `futures_stream` | SSE 推送；可选 `symbols` / `exchanges`（SHFE / DCE / CZCE / INE / CFFEX）；事件 `ready` / `tick` / `ping` / `evicted`；真实月合约盘中可订 |
| `/v1/futures/ws` | `futures_stream` | WebSocket 推送；参数与 SSE 相同；JSON 帧含 `type`；浏览器请用 query `api_key=` |

并发路数见 `GET /v1/me` 的 `max_futures_stream_subscriptions`（国内期货单独配置，与个股 Tick WS 无关）。同一通道内 SSE 与 WS **同源计数**；超出顶掉最早连接。

开通状态见 `GET /v1/me` 与公开 `GET /public/v1/catalog`。

## 国内期货 V2 {#futures-v2}
与「国内期货」并存的独立产品线：路径 `/futures-v2`，scope `futures_v2_realtime` / `futures_v2_trend` / `futures_v2_kline` / `futures_v2_stream`。无复权；K 线周期：`60` / `300` / `900` / `1800` / `3600` / `7200` / `14400` / `28800` / `86400` / `604800` / `2592000`。

**支持的交易所**

| 交易所 | 码 | 清单 / 实时 / 分时 / K 线 | SSE / WS 推送 |
|--------|----|---------------------------|---------------|
| 上期所 | `SHFE` | ✅ | ✅ |
| 大商所 | `DCE` | ✅ | ✅ |
| 郑商所 | `CZCE` | ✅ | ✅ |
| 能源中心 | `INE` | ✅ | ✅ |
| 广期所 | `GFEX` | ✅ | ✅ |
| 中金所 | `CFFEX` | ✅ | ✅ |

**支持的代码**

| 类型 | 示例 | 说明 |
|------|------|------|
| 连续主力 | `AU0001`、`IF0001` | 品种连续合约 |
| 近月合约 | `AU2610`、`IF2609`、`PG2612` | 品种 + YYMM；见清单 `contracts` |

```http
GET /public/v1/futures-v2
GET /public/v1/futures-v2?exchange=SHFE
GET /public/v1/futures-v2?keyword=黄金
GET /v1/futures-v2/realtime?exchange=SHFE
GET /v1/futures-v2/realtime?exchange=CFFEX&kind=continuous
GET /v1/futures-v2/realtime?symbol=AU0001
GET /v1/futures-v2/trend?symbol=AU0001
GET /v1/futures-v2/stream?exchange=SHFE
GET /v1/futures-v2/stream?symbol=AU0001
WS  /v1/futures-v2/ws?exchange=SHFE&api_key=...
WS  /v1/futures-v2/ws?symbol=AU0001&api_key=...
```

推送为 compact：`ready` 声明 `fields` 一次，之后 `tick` 的 `data:` 仅为数组行（与 `fields` 对齐），例如：

```text
event: ready
data: {"type":"ready","format":"compact","fields":["symbol","exchange","price","open","high","low","prev_close","bid","ask","volume","timestamp","received_at"],"exchange":"SHFE","evicted":0}

event: tick
data: ["AU0001","SHFE",952.48,951.0,953.0,950.5,950.0,952.4,952.6,1234,1786700000000,1786700000123]
```

| 接口 | scope | 说明 |
|------|-------|------|
| `/public/v1/futures-v2` | 无 | 公开清单；可选 `exchange`、`keyword`、`limit` |
| `/v1/futures-v2/realtime` | `futures_v2_realtime` | 实时快照；**`exchange` 整板**与 **`symbol` 单码点查二选一**；可选 `kind=continuous\|contract` |
| `/v1/futures-v2/trend` | `futures_v2_trend` | 分时；单标的；当日序列 |
| `/v1/futures-v2/stream` | `futures_v2_stream` | SSE 推送；**`exchange` 整板**（连续+月合约）与 **`symbol` 单码二选一**；`ready` 带 `fields`，`tick` 仅为数组行（compact） |
| `/v1/futures-v2/ws` | `futures_v2_stream` | WebSocket；参数与 SSE 相同；帧为 JSON：`ready` / `{"type":"tick","data":[...]}` / `ping` / `evicted`；浏览器请用 query `api_key=` |
| `/v2/futures-v2/kline` | `futures_v2_kline` | K 线（单标的；`count` 上限 1000）；响应 `fields` + `symbols`；可选 `timestamp`（秒）向前翻页 |

并发路数与 v1 共用字段 `max_futures_stream_subscriptions`，但 **v2 通道单独计数**（SSE 与 WS 在本通道内同源）。超出顶掉最早连接。

开通状态见 `GET /v1/me` 与公开 `GET /public/v1/catalog`。

## 全球指数 {#global-indices}
全球指数独立路径与 scope：`global_index_realtime` / `global_index_trend` / `global_index_kline`。标准码后缀 `.GI`（如 `DJI.GI`、`SPX.GI`、`KS11.GI`）；清单含 `name` 与俗称 `aliases`。无复权；K 线周期：`60` / `300` / `900` / `1800` / `3600` / `86400`。

与 A 股指数（`/v1/index/*`、`/public/v1/indices`）及国际债券（`/v1/global-bond/*`）强制拆分，不可混用。

```http
GET /public/v1/global-indices
GET /public/v1/global-indices?group=亚洲
GET /public/v1/global-indices?keyword=道指
GET /v1/global-index/realtime?symbols=DJI.GI,KS11.GI
GET /v1/global-index/trend?symbol=N225.GI
GET /v1/global-index/trend?symbol=N225.GI&date=20260812
GET /v2/global-index/kline?symbol=DJI.GI&period=86400&count=120
```

| 接口 | scope | 说明 |
|------|-------|------|
| `/public/v1/global-indices` | 无 | 公开清单；可选 `keyword`、`group`、`listed`、`limit` |
| `/v1/global-index/realtime` | `global_index_realtime` | 实时快照；`symbols` 或 `symbol`，可多只 |
| `/v1/global-index/trend` | `global_index_trend` | 分时；单标的；可选 `date=YYYYMMDD`（默认最新有数据交易日） |
| `/v2/global-index/kline` | `global_index_kline` | K 线（单标的；`count` 上限 1000）；响应 `fields` + `symbols`；可选 `timestamp`（秒）向前翻页 |

## 国际债券 {#global-bonds}
国际债券收益率独立路径与 scope：`global_bond_realtime` / `global_bond_kline`。标准码后缀 `.GB`（如 `US10Y.GB`、`JP10Y.GB`）；清单分组：美国 / 欧洲 / 亚洲 / 其他。无复权；K 线周期同全球指数。

与全球指数、A 股债券（`/v1/bonds`、可转债等）强制拆分，不可混用。

```http
GET /public/v1/global-bonds
GET /public/v1/global-bonds?group=美国
GET /public/v1/global-bonds?keyword=美债
GET /v1/global-bond/realtime?symbols=US10Y.GB,JP10Y.GB
GET /v2/global-bond/kline?symbol=US10Y.GB&period=86400&count=120
```

| 接口 | scope | 说明 |
|------|-------|------|
| `/public/v1/global-bonds` | 无 | 公开清单；可选 `keyword`、`group`、`listed`、`limit` |
| `/v1/global-bond/realtime` | `global_bond_realtime` | 实时快照；`symbols` 或 `symbol`，可多只 |
| `/v2/global-bond/kline` | `global_bond_kline` | K 线（最多 5；`count` 上限 1000）；响应 `fields` + `symbols`；可选 `timestamp`（秒）向前翻页 |

## 美股 {#usstocks}
美股独立路径与 scope：`usstock_realtime` / `usstock_trend` / `usstock_kline`。标准码后缀 `.US`（如 `AAPL.US`、`TSLA.US`）；亦兼容裸 ticker（如 `AAPL`）。无复权；K 线周期：`60` / `300` / `900` / `1800` / `3600` / `86400`。日 K 按 `count` 截取近端（单次上限 1000）。

与 A 股（`/v1/realtime`、`/v2/kline`）及美股全市场 compact（`/v2/realtime?market=US`）拆分：本系列为 JSON 报价 / 分时 / K 线；全市场 pipe 快照仍走 `/v2/realtime`。

```http
GET /public/v1/usstocks?keyword=AAPL
GET /public/v1/usstocks?market=N&page=1&limit=50
GET /v1/usstock/realtime?symbols=AAPL.US,TSLA.US
GET /v1/usstock/trend?symbol=AAPL.US
GET /v1/usstock/trend?symbol=AAPL.US&day=5
GET /v2/usstock/kline?symbol=AAPL.US&period=86400&count=30
```

| 接口 | scope | 说明 |
|------|-------|------|
| `/public/v1/usstocks` | 无 | 公开清单/搜索；可选 `keyword`、`market`（`N`/`O`/`A`）、`page`、`limit` |
| `/v1/usstock/realtime` | `usstock_realtime` | 实时快照；`symbols` 或 `symbol`，可多只 |
| `/v1/usstock/trend` | `usstock_trend` | 分时；单标的；可选 `day=1\|5`（默认 1） |
| `/v2/usstock/kline` | `usstock_kline` | K 线（单标的；`count` 上限 1000）；响应 `fields` + `symbols`；可选 `timestamp`（秒）向前翻页 |

## 站内板块 {#plates}
站内主题库板块：标识为整数 `plate_id`（清单 `GET /v1/catalog/plates`）。独立 scope：`plate_realtime` / `plate_trend` / `plate_kline` / `plate_moneyflow`。

与 **新浪板块资金流向榜**（`/v1/moneyflow/ranking/boards`，身份为 `name` + `category`）**不是同一套**，不可互换。

```http
GET /v1/plate/realtime?plate_id=16842834
GET /v1/plate/realtime?plate_id=16842834,16868321
GET /v1/plate/trend?plate_id=16842834
GET /v2/plate/kline?plate_id=16842834&period=86400&count=120
GET /v1/plate/moneyflow?plate_id=16842834
GET /v1/plate/moneyflow/ranking?type=industry&limit=50
GET /public/v1/plate/moneyflow/schema
```

| 接口 | scope | 说明 |
|------|-------|------|
| `/v1/plate/realtime` | `plate_realtime` | 实时快照；`plate_id` 可批量；含 `fund_flow`、涨跌家数等 |
| `/v1/plate/trend` | `plate_trend` | 当日分时（单板）；`pre_close` + `data[{timestamp,price,change_percent}]`；不支持历史 `date` |
| `/v2/plate/kline` | `plate_kline` | 仅日 K（`period=86400`）；无复权；最多 5；`timestamp`（秒）向前翻页；响应 `fields` + `symbols` |
| `/v1/plate/moneyflow` | `plate_moneyflow` | 按 `plate_id` 查当日资金流快照 |
| `/v1/plate/moneyflow/ranking` | `plate_moneyflow` | `type=all/concept/industry/style`，默认按 `fund_flow` 排序 |
| `/public/v1/plate/moneyflow/schema` | 无 | 字段说明 |

实时 / 资金流主要字段：`plate_id`、`name`、`change_percent`、`rise_count`、`fall_count`、`limit_up_count`、`fund_flow`（元）；可选 `stay_count`、`rank`。


## 分时图 {#trend}
```http
GET /v1/trend?symbol=300042.SZ
GET /v1/trend?symbol=600519.SS&date=20250620
```

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

响应 `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 线 {#kline}
推荐 **K 线 v2** `GET /v2/kline`（旧接口 `GET /v1/kline` 已过时）。

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

- `symbol`：逗号分隔，最多 5 只（也可只传 1 只）
- 响应：`symbols: { "600519.SS": [[...], ...], ... }`；顶层 `fields` 为列名（传 `fields=0` 可省略）
- 指数用 `/v2/index/kline`，ETF 用 `/v2/etf/kline`

复权方式见响应 `meta.adjust_mode`：

- `direct`：按请求的 `adjust_type` 返回
- `factor`：用不复权价 + 复权因子换算（因子见 [`/v1/adjust-factors`](#adjust-factors)）

| 参数 | 必填 | 默认 | 说明 |
|------|------|------|------|
| symbol | 是 | - | 沪深 A 股个股代码；可多码（最多 5） |
| period | 否 | 86400 | 周期（秒） |
| adjust_type | 否 | forward | `forward` / `backward` / `none`；受套餐限制 |
| count | 否 | 256 | 返回条数，受套餐上限裁切 |
| timestamp | 否 | - | 结束时间戳（秒），向前翻页 |
| date | 否 | - | 交易日 `YYYYMMDD`（日线及以下）。未传 `count` 时：日线 1 根，分钟线为该日全日；与 `timestamp` / `start` / `end` 互斥 |
| indicators | 否 | - | 技术指标，可重复传参或分号分隔 |

带 `indicators` 时，每行附带 `indicators` 对象；前段可能为 `null`（见 `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 |

需 `kline` 权限；`adjust_type` 受套餐复权权限限制。

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

## 股票信息 {#stock}
```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 专用接口 {#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 /v2/etf/kline?symbol=515250.SS,510300.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 | 实时行情；可选 `include_valuation`（`etf_realtime_valuation`）、`include_depth`（`etf_realtime_depth`）；symbol 批量规则同个股 |
| `/v1/etf/trend` | etf_trend | 分时（可选 date=YYYYMMDD） |
| `/v2/etf/kline` | etf_kline | K 线（最多 5）；参数与响应格式同 `/v2/kline` |
| `/v1/etf/kline` | etf_kline | **过时**，请用 `/v2/etf/kline` |

字段说明见 `GET /public/v1/etf/schema`（无需 Key）。

## 债券专用接口 {#bond}
沪/深/京现券（可转债 / 国债 / 企债）清单与行情**独立于**板块目录与个股接口，按 kind 分路径。

清单 scope：`bond`；行情：`bond_realtime` / `bond_trend`；K 线：`convertible_kline`（可转债 K 线 v2）与 `bond_kline`（国债/企债单券）。
字段说明：`GET /public/v1/bond/schema`（无需 Key）。

现券叶子板：`sh_gz` / `sh_qz` / `sh_kzz`、`sz_*`、`bj_*`；并集别名板 `hskzz_z` / `gz_z`。

```http
GET /v1/convertible?symbol=110075.SS
GET /v1/convertible/profile?symbol=113704.SS
GET /v1/convertible/profile?symbol=113704.SS&sections=all
GET /v1/convertibles?num=100
GET /v1/treasury?symbol=019766.SS
GET /v1/treasury/profile?symbol=019766.SS&sections=basic,issue
GET /v1/treasuries?num=100
GET /v1/enterprise?symbol=111077.SS
GET /v1/enterprises?board=sh_qz&num=100
GET /v1/convertible/boards/sh_kzz/members?limit=200
GET /v1/treasury/realtime?symbol=019766.SS
GET /v2/convertible/kline?symbol=110075.SS,113704.SS&period=86400&count=120
```

| 路径族 | scope | 说明 |
|--------|-------|------|
| `/v1/convertible*`（除 K 线） | bond / bond_realtime / bond_trend | 可转债；kind 不匹配 → 404 |
| `/v2/convertible/kline` | convertible_kline | 可转债 K 线 v2（最多 5 个 symbol） |
| `/v1/treasury*` | bond / 行情；K 线为 bond_kline | 国债 |
| `/v1/enterprise*` | 同上 | 企债 |

概况：未传 `sections` 时仅返回 `data.summary`；`sections=basic,issue,…` 或 `sections=all` 按需扩段。转债可用 `convert` / `clauses` / `exercises` / `price_changes` / `put_call` / `ballot` / `invest`；国债/企债请求转债专用段时记入 `meta.ignored_sections`。

列表 / 搜索、板块成分、国债/企债 K 线为列式响应：`fields` + `data`。可转债 K 线：`GET /v2/convertible/kline`（最多 5 只，格式同 `/v2/kline`）；国债/企债：`/v1/treasury|enterprise/kline`。

## 上市公司资料 {#corp}
```http
GET /v1/corp?symbol=600519.SS
GET /public/v1/corp/schema
```

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

## 财报四表 {#finance}
```http
GET /v1/finance/report?symbol=600519.SS
GET /v1/finance/report?symbol=600519.SS&source=income,balance&periods=4
GET /v1/finance/report?symbol=600519.SS&year=2025
GET /v1/finance/report?symbol=600519.SS&years=3
GET /v1/finance/report?symbol=600519.SS&period=2025Q1
GET /public/v1/finance/schema
```

| 路径 / 参数 | 必填 | 说明 |
|-------------|------|------|
| `/v1/finance/report` · symbol | 是 | 股票代码，如 `600519.SS` |
| source | 否 | 逗号分隔：`metrics` 关键指标、`income` 利润表、`balance` 资产负债表、`cashflow` 现金流量表；默认四表；可选 `special` 专项指标 |
| periods | 否 | 最近几期，默认 `8`，最大 `40`；传 `0` 返回全部 |
| year | 否 | 自然年 `YYYY`，返回该年全部报告期 |
| years | 否 | 最近几个自然年（1–20）；与 `year` 同时传时以 `year` 为准 |
| period | 否 | 单期：`YYYYMMDD`、`2025Q1`、`2025H1`、`2025A`；指定后优先于上述范围参数 |
| `/public/v1/finance/schema` | - | 表类型与字段结构说明（无需 Key） |

需 `finance` 权限（**免费版**及以上）。`data.reports.<source>.values.<report_date>.<field>` 为 `{value, yoy}`；字段中文名见同表 `fields`。每期含 `year`、`period_type`（`Q1`/`H1`/`Q3`/`A`）、`label` 等。

## 板块目录 {#catalog}

行业/概念分类与站内板块、指数成分（scope：`catalog`）。

```http
GET /v1/catalog/nodes
GET /v1/catalog/nodes/{node}
GET /v1/catalog/nodes/{node}/children
GET /v1/catalog/nodes/{node}/members
GET /v1/catalog/plates
GET /v1/catalog/plates/{plate_id}/members
GET /v1/catalog/indices
GET /v1/catalog/indices/{code}/members
GET /v1/catalog/stocks/{symbol}
```

分类像文件夹：先选体系 → 再进下级 → 末级查成分股。

## 交易日历 {#calendar}
```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}

打板、异动、快讯等专题接口按**每个 endpoint** 单独配置正式开通或试用（周期天数 + 窗口内次数），由角色权限决定，**不固定绑定某一套餐档位**。

- **查询当前 Key**：`GET /v1/me` 返回 `endpoint_access_status`（逐接口 `access_mode`、`period_days`、`max_uses`、`remaining`）及 `scopes` / `scope_rows`。
- **试用计数**：各 endpoint **独立**计数（含沙盒与 API 调用）；SSE 订阅按**新建连接**计次。额度按配置周期重置（默认每自然日）。
- 超出试用额度返回 `429`；未开通返回 `403`。
- 公开目录见 `GET /public/v1/catalog` 的 `endpoint_catalog` 与 `scope_rows`（矩阵为展示参考，以账号实际配置为准）。

### 接口一览 {#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`（由角色配置）；超出上限时**顶掉最早建立的连接**，被顶掉端收到 `{"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-tiers}

市场快讯（`market_flash`）按 endpoint 配置正式开通或试用，见 `GET /v1/me` 的 `endpoint_access_status`。

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

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

- **订阅模式**：客户端发起 GET 并保持长连接（SSE），服务端在有新快讯时推送。
- 同一 API Key **并发订阅数**见 `GET /v1/me` 的 `max_market_flash_subscriptions`（由角色配置）；超出上限时**顶掉最早建立的连接**，被顶掉端收到 `{"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"
  }
}
```

## 停复牌 {#suspend}

停复牌数据（scope：`suspend`）。

```http
GET /v1/suspend
GET /v1/suspend/daily?date=20260815
GET /v1/suspend/stock?symbol=600519.SS
GET /v1/suspend/dates
```

| 路径 | 说明 |
|------|------|
| `/v1/suspend` | 当前停牌 |
| `/v1/suspend/daily` | 日事件 |
| `/v1/suspend/stock` | 单票区间 |
| `/v1/suspend/dates` | 有数据的日期 |

## 龙虎榜 {#lhb}
```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/me`）。也可使用 `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` 权限（开通状态见 `GET /v1/me`）。仅支持**沪深 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 日**（含首尾） |

未指定日期时按 `limit` 返回最近有数据的交易日（默认 100，最大 500）。显式 `bdate`/`edate` 跨度最多 **10** 自然日。`date` 与 `bdate`/`edate` 不可同时使用。

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

## 新浪资金流排名（当日盘中快照） {#moneyflow-ranking}

新浪资金流排名：交易时段的板块与个股资金流向排行。**仅当前业务日**（09:15 前为上一交易日），不支持 `date` / `bdate` / `edate` / `capture_id`（传参返回 400）。需 `moneyflow` 权限。响应 `meta.source=sina`、`meta.source_label=新浪`。

```http
GET /v1/moneyflow/ranking/boards?category=industry&limit=50
GET /v1/moneyflow/ranking/stocks/net?sort=netamount&limit=100
GET /v1/moneyflow/ranking/stocks/main?sort=r0_net&limit=100
GET /v1/moneyflow/ranking/stocks/retail?sort=r3_net&limit=100
GET /v1/moneyflow/ranking/snapshot
GET /public/v1/moneyflow/ranking/catalog
```

### 板块榜 {#moneyflow-ranking-boards}

`GET /v1/moneyflow/ranking/boards` — `category` 必填：`industry` / `concept` / `csrc_industry`；可选 `limit`。板块代表股 `ts_symbol` 为标准代码（如 `600519.SS`）。

身份为板块 **名称 + category**，**不是**站内 `plate_id`。按站内板块查资金流请用 `GET /v1/plate/moneyflow`（需 `plate_moneyflow`）。

### 个股榜 {#moneyflow-ranking-stocks}

三类个股榜，按业务含义拆分字段；`sort` 选择按额或按率。可选 `symbol`（如 `600519.SS`）查单票；`data[]` 仅含标准 `symbol`。

| 路径 | 类 | `sort` | 主要字段 |
|------|----|--------|----------|
| `/v1/moneyflow/ranking/stocks/net` | 净流入 | `netamount`（默认）、`ratioamount` | in/out/net/ratioamount |
| `/v1/moneyflow/ranking/stocks/main` | 主力 | `r0_net`（默认）、`r0_ratio` | r0_in/out/net/ratio |
| `/v1/moneyflow/ranking/stocks/retail` | 散户 | `r3_net`（默认）、`r3_ratio` | r3_in/out/net/ratio |

金额类字段单位为**元**；`changeratio` / `*ratio` 为小数比例；`turnover` 为换手万分比（÷100 为 %）；`r0x_ratio` 为主力罗盘（度）。

旧路径 `GET /v1/moneyflow/ranking/stocks?sort=…`（六种 sort、全字段）响应 `meta.deprecated=true`，请改用上表三类路径。

### 快照信息 {#moneyflow-ranking-snapshot}

`GET /v1/moneyflow/ranking/snapshot` — 返回当前业务日更新时间与板块/个股行数统计，无参数。

### 排行目录 {#moneyflow-ranking-catalog}

`GET /public/v1/moneyflow/ranking/catalog` — 可选参数与字段说明，无需 Key。

响应 `meta` 含 `trade_date`（当前业务日）、`captured_at`（`YYYY-MM-DD HH:MM:SS` 北京时间）、`snapshot_policy=today_intraday`、`source` / `source_label`。

## 东财资金流排名（当日盘中快照） {#moneyflow-ranking-em}

东财资金流排名：全市场个股资金流排行（今日四档 + 5/10 日主力字段）。**仅当前业务日**（09:15 前为上一交易日），不支持 `date` / `bdate` / `edate` / `capture_id`。需 `moneyflow` 权限。响应 `meta.source=eastmoney`、`meta.source_label=东财`。

```http
GET /v1/moneyflow/ranking/em/stocks?sort=main_net&limit=100
GET /v1/moneyflow/ranking/em/snapshot
GET /public/v1/moneyflow/ranking/em/catalog
```

### 个股榜 {#moneyflow-ranking-em-stocks}

`GET /v1/moneyflow/ranking/em/stocks` — 可选 `sort`（默认 `main_net`）、`limit`、`symbol`。

常用 `sort`：`main_net` / `main_net_ratio` / `super_net` / `large_net` / `medium_net` / `small_net` / `rank_today` / `main_net_5d` / `main_net_10d` 等（完整列表见 catalog）。`rank_*` 升序，其余降序。金额单位为**元**；占比/涨跌幅为小数。

### 快照信息 {#moneyflow-ranking-em-snapshot}

`GET /v1/moneyflow/ranking/em/snapshot` — 返回当前业务日更新时间与个股行数，无参数。

### 排行目录 {#moneyflow-ranking-em-catalog}

`GET /public/v1/moneyflow/ranking/em/catalog` — sort 与字段说明，无需 Key。

## 游资名录 {#hot-money}
```http
GET /v1/hot-money
GET /v1/hot-money?name=赵老哥
GET /v1/hot-money?keyword=章
GET /v1/hot-money?q=章
GET /v1/hot-money/stats?lastdays=5&page=1
GET /v1/hot-money/stats?name=赵老哥&bdate=2025-06-16&edate=2025-06-20
GET /v1/hot-money/detail?name=赵老哥&lastdays=5
GET /v1/hot-money/detail?symbol=600519.SS&lastdays=5
GET /v1/hot-money/seat?broker=中信证券上海溧阳路
GET /v1/hot-money/seat?seat=中信证券上海溧阳路
```

需 `hot_money` 权限（开通状态见 `GET /v1/me`）。查询知名游资及其常用营业部；支持按名称精确查询、关键词搜索（`keyword` 或 `q`）、按龙虎榜席位关联做统计与明细反查、按营业部反查（`broker` 或 `seat`）。名录未就绪时返回 `503`。

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

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

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

### 统计 `/v1/hot-money/stats`

按龙虎榜席位关联知名游资，区间内聚合上榜次数与买卖额排行。

| 参数 | 说明 |
|------|------|
| lastdays | 默认 5，统计最近 N 个含买卖席位明细的交易日（与 bdate/edate 二选一）；最大 5 |
| bdate + edate | 指定区间，最多 5 个含席位明细的交易日 |
| page | 默认 1，每页 50 条 |
| name | 可选，只看某一游资 |

`data[]` 主要字段：`name`、`list_count`、`buy_total_10k`、`sell_total_10k`、`net_10k`、`buy_seats`、`sell_seats`、`top_buy_stocks`。`meta` 含 `bdate`、`edate`、`days`、`page`、`count`、`total`。

### 反查 `/v1/hot-money/detail`

按游资名称与/或股票代码查询上榜明细（须至少提供其一）。日期参数同统计。

| 参数 | 说明 |
|------|------|
| name | 游资名称 |
| symbol | 股票代码 |
| lastdays / bdate + edate / page | 同统计（区间最多 5 个交易日） |

`data[]` 一行 = 交易日 × 股票 × 游资：`tradedate`、`code`、`stock_name`、`name`、`buy_amount_10k_cny`、`sell_amount_10k_cny`、`net_amount_10k_cny`、`brokers`、`reason`。

## 查询当前权限

```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 数（无权限时不返回） |
| max_realtime_stream_subscriptions | 个股 Tick WS 并发连接数（无权限时为 0；与期货无关） |
| max_realtime_stream_symbols | 个股 Tick WS 单次及连接内最多只数（无权限时为 0） |
| max_futures_stream_subscriptions | 期货推送并发路数；同一通道 SSE 与 WS 同源计数，v1/v2 各自独立（无权限时为 0） |
| rate_limit | 全局限流（如有） |

## 套餐档位

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

**实时批量：** `/v1/realtime` 与 `/v1/etf/realtime` 单次 symbol 上限见 `GET /v1/me` 的 `max_realtime_symbols` 或 `catalog.tiers`。**分时**每次 **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" "https://market-api.cn/v1/realtime?symbol=603778.SS"
curl -s -H "X-API-Key: YOUR_KEY" "https://market-api.cn/v2/kline?symbol=603778.SS&period=86400&count=100"
```

```python
import requests

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

用户中心「接口测试」可调试（计入限流）；正式调用请用 `/v1/*`、`/v2/*` 并在请求头携带 `X-API-Key`。

## MCP（AI 客户端）

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

**远程端点：** `https://market-api.cn/mcp`（Streamable HTTP）

### 配置步骤

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

**说明：** 只有支持 MCP 的客户端才能接入。无法安装 MCP 时，请用 [Agent Skill](https://market-api.cn/docs/skills)（教 Agent 走 REST），或 REST API，或将 [`llms-full.txt`](https://market-api.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": "https://market-api.cn/mcp",
      "headers": { "X-API-Key": "tg_你的密钥" }
    }
  }
}
```

Query 传 Key：

```json
{
  "mcpServers": {
    "klineshare": {
      "url": "https://market-api.cn/mcp?token=tg_你的密钥"
    }
  }
}
```

### 四种接入方式对比

| 方式 | 作用 |
|------|------|
| `/v1/*` REST | 程序、脚本、用户中心沙箱 |
| `llms-full.txt` | 让模型**读懂**接口与参数（@Docs、粘贴上下文） |
| `/mcp` | 让**已配置 MCP 的客户端**自动调工具**查数据** |
| [Agent Skill](https://market-api.cn/docs/skills) | 不支持 MCP 时，教 Agent 用 REST 查数（可与 MCP 并存） |

### 可用工具

`get_health`、`get_my_permissions`、`get_realtime`、`get_trend`、`get_kline_v2`（K 线 v2）、`get_kline`（过时）、`get_index_realtime`、`get_index_trend`、`get_index_kline_v2`（K 线 v2）、`get_index_kline`（过时）、`get_stock`、`search_stocks`、`list_stocks`、`get_corp`、`get_finance_report`、`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`、`search_indices`、`get_public_catalog`，及 ETF 系列 `get_etf`、`search_etfs`、`get_etf_realtime`、`get_etf_trend`、`get_etf_kline_v2`（K 线 v2）、`get_etf_kline`（过时）（开通状态见 `GET /v1/me`）。

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