# History Candlesticks

`WS` `request · cmd 27`

> **Quote Permission Required · Free**
> Quota-based access: 100–3,000 unique symbols per calendar month depending on account tier (resets monthly; see quota table in the docs).
> US stocks: US LV1 included free by default (pre-market, regular, after-hours, and overnight sessions).
> HK stocks: LV1 included by default.
> US options: no permission by default — purchase "OPRA US Options Quotes (OpenAPI)".
> _OpenAPI quote perms are separate from App/Web perms_

This API is used to obtain the history candlestick data of security.

```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 | Security code, in ticker.region format, e.g. 700.HK |
| `period` | int32 | Yes | Candlestick period |
| `adjust_type` | int32 | Yes | Adjustment type |
| `query_type` | int32 | Yes | Type of query (1-by offset, 2-by date) |
| `date_request` | object | No | Required when querying by date |
| `└ start_date` | string | No | Date of query begin, in YYYYMMDD format |
| `└ end_date` | string | No | Date of query end, in YYYYMMDD format |
| `offset_request` | object | No | Required when querying by offset |
| `└ direction` | int32 | Yes | Query direction (0-historical, 1-latest) |
| `└ date` | string | No | Query date, in YYYYMMDD format; default latest trading day |
| `└ minute` | string | No | Query time, in HHMM format; only valid for minute-level data |
| `└ count` | int32 | No | Count of candlestick, range [1,1000]; default 10 |
| `trade_session` | int32 | No | Trading session, 0: intraday, 100: All (pre, intraday, post, overnight) |

## Response Fields

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `symbol` | string | No | Security code, e.g. AAPL.US |
| `candlesticks` | object[] | No | Candlestick data |
| `└ close` | string | No | Close price |
| `└ open` | string | No | Open price |
| `└ low` | string | No | Low price |
| `└ high` | string | No | High price |
| `└ volume` | int64 | No | Volume |
| `└ turnover` | string | No | Turnover |
| `└ timestamp` | int64 | No | Timestamp |
| `└ trade_session` | int32 | No | Trade session |

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