# 历史 K 线

`WS` `request · cmd 27`

> **行情权限要求 · 免费**
> 按账户等级配额，每自然月可查询 100–3,000 个标的（每月重置，详见文档中的配额表）。
> 美股：默认免费赠送 US LV1 行情（含盘前、盘中、盘后、夜盘全时段）。
> 港股：默认赠送 LV1 行情。
> 美股期权：默认无权限，需购买「OPRA 美股期权行情 (OpenAPI)」行情卡。
> _OpenAPI 行情权限独立于 App/Web 行情权限_

该接口用于获取标的的历史 K 线数据。

```protobuf
message SecurityHistoryCandlestickRequest {
  string symbol = 1;
  Period period = 2;
  AdjustType adjust_type = 3;
  HistoryCandlestickQueryType query_type = 4;
  OffsetQuery offset_request = 5;
  DateQuery date_request = 6;
}

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 线周期 |
| `adjust_type` | int32 | Yes | 复权类型 |
| `query_type` | int32 | Yes | 查询方式 (1-按偏移查询，2-按日期区间查询) |
| `date_request` | object | No | 按日期查询时必填 |
| `└ start_date` | string | No | 开始日期，格式为 YYYYMMDD |
| `└ end_date` | string | No | 结束日期，格式为 YYYYMMDD |
| `offset_request` | object | No | 按偏移查询时必填 |
| `└ direction` | int32 | Yes | 查询方向 (0-向历史，1-向最新) |
| `└ date` | string | No | 查询日期，格式为 YYYYMMDD；为空时使用最新交易日 |
| `└ minute` | string | No | 查询时间，格式为 HHMM；仅在查询分钟级别 K 线时有效 |
| `└ count` | int32 | No | 查询数量，范围 [1,1000]；默认 10 |
| `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
    }
  ]
}
```
