# K 線

`WS` `request · cmd 19`

> **行情權限要求 · 免費**
> 按帳戶等級配額，每自然月可查詢 100–3,000 個標的（每月重置，詳見文檔中的配額表）。
> 美股：預設免費贈送 US LV1 行情（含盤前、盤中、盤後、夜盤全時段）。
> 港股：預設贈送 LV1 行情。
> 美股期權：預設無權限，需購買「OPRA 美股期權行情 (OpenAPI)」行情卡。
> _OpenAPI 行情權限獨立於 App/Web 行情權限_

該接口用於獲取標的的 K 線數據。

```protobuf
message SecurityCandlestickRequest {
  string symbol = 1;
  Period period = 2;
  int32 count = 3;
  AdjustType adjust_type = 4;
  int32 trade_session = 5;
}

message SecurityCandlestickResponse {
  string symbol = 1;
  repeated Candlestick candlesticks = 2;
}
```

## Request Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `symbol` | string | Yes | 標的代碼，使用 ticker.region 格式，例如：700.HK |
| `period` | int32 | Yes | K 線週期 |
| `count` | int32 | Yes | 數據數量；最大 1000 |
| `adjust_type` | int32 | Yes | 復權類型 |
| `trade_session` | int32 | No | 交易時段，0: 盤中，100: 所有延長時段（盤前，盤中，盤後，夜盤） |

## Response Fields

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `symbol` | string | No | 標的代碼，例如：AAPL.US |
| `candlesticks` | object[] | No | K 線數據 |
| `└ close` | string | No | 當前週期收盤價 |
| `└ open` | string | No | 當前週期開盤價 |
| `└ low` | string | No | 當前週期最低價 |
| `└ high` | string | No | 當前週期最高價 |
| `└ volume` | int64 | No | 當前週期成交量 |
| `└ turnover` | string | No | 當前週期成交額 |
| `└ timestamp` | int64 | No | 當前週期的時間戳 |
| `└ trade_session` | int32 | No | 交易時段 |

## Response JSON Example

```json
{
  "symbol": "700.HK",
  "candlesticks": [
    {
      "close": "362.000",
      "open": "364.600",
      "low": "361.600",
      "high": "368.800",
      "volume": 10853604,
      "turnover": "3954556819.000",
      "timestamp": 1650384000
    }
  ]
}
```
