# 实时 K 线订阅

`WS` `push · cmd 105`

> **行情权限要求 · 免费**
> 美股：默认免费赠送 US LV1 实时行情。
> 港股：默认赠送 LV1 实时行情。
> K 线推送所需权限与订阅行情相同。
> _OpenAPI 行情权限独立于 App/Web 行情权限_

已订阅标的的实时 K 线数据推送。回调在当前 K 线更新时触发（Realtime 模式）或在一根 K 线周期结束时触发（Confirmed 模式）。

:::tip
本页介绍的是**推送** API（`subscribe_candlesticks`）。如需按需拉取历史 K 线数据，请参见 [K 线 - 拉取](/quote/stocks/candlestick)。
:::

```protobuf
message PushCandlestick {
  string symbol = 1;
  Period period = 2;
  Candlestick candlestick = 3;
}
```

## Push Fields

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `symbol` | string | No | 标的代码，例如：AAPL.US |
| `period` | int32 | No | K 线周期，详见 Period |
| `candlestick` | object | No | K 线数据 |
| `└ close` | string | No | 收盘价 |
| `└ open` | string | No | 开盘价 |
| `└ high` | string | No | 最高价 |
| `└ low` | string | No | 最低价 |
| `└ volume` | int64 | No | 成交量 |
| `└ turnover` | string | No | 成交额 |
| `└ timestamp` | int64 | No | K 线时间（Unix 时间戳） |
| `└ trade_session` | int32 | No | 交易时段，详见 TradeSession |

## Response JSON Example

```json
{
  "symbol": "700.HK",
  "period": 1,
  "candlestick": {
    "close": "162.500",
    "open": "160.000",
    "high": "163.000",
    "low": "159.800",
    "volume": 123456,
    "turnover": "19987654.000",
    "timestamp": 1651103700,
    "trade_session": 0
  }
}
```
