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