# Klines (candlestick data) (MARKET_DATA)

## API Description

Historical candles. Built by aggregating the trade server's 1-minute bars.

Use this for **history**. For live candles use the
[`<SYMBOL>@kline_<interval>`](/websocket-market-streams/kline-streams.md) WebSocket stream.

## HTTP Request

```http
GET /v1/klines
```

## Request Weight

1 for `limit` ≤ 100, 2 for `limit` ≤ 500, 5 for `limit` ≤ 1000

## Request Parameters

| Name | Type | Mandatory | Description |
| - | - | - | - |
| `symbol` | STRING | YES | Exact, case-sensitive. |
| `interval` | ENUM | YES | `1m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `1d`. |
| `startTime` | LONG | NO | Inclusive, Unix ms. |
| `endTime` | LONG | NO | Inclusive, Unix ms. |
| `limit` | INT | NO | Default `500`, maximum `1000`. |

- With neither `startTime` nor `endTime`, the most recent `limit` candles are returned.
- With `startTime` only, up to `limit` candles **forward** from `startTime`.
- With `endTime` only, the most recent `limit` candles ending at `endTime`.
- With both, candles in `[startTime, endTime]`, capped at the **first** `limit` from `startTime`.
- Candles are ordered **oldest first**.
- The last row is the **currently forming** candle unless `endTime` is in the past.

Missing `symbol` or `interval` is `-1102`; an unknown `symbol` is `-1121`; an interval not in the
list (they are case-sensitive — `1M` is not `1m`) is `-1120`; a `limit` outside `1`–`1000` or a
non-integer time is `-1130`. `-5015` only when the trade server cannot be reached and nothing is
cached for the symbol.

## Response Example

```json
[
  [1789012320000, "2331.02", "2331.40", "2330.95", "2331.15", 38, 1789012379999, 0],
  [1789012380000, "2331.15", "2331.62", "2331.10", "2331.58", 44, 1789012439999, 0]
]
```

| Index | Name | Type | Description |
| - | - | - | - |
| 0 | `openTime` | LONG | Candle open, Unix ms. |
| 1 | `open` | DECIMAL | |
| 2 | `high` | DECIMAL | |
| 3 | `low` | DECIMAL | |
| 4 | `close` | DECIMAL | |
| 5 | `tickVolume` | LONG | Number of ticks in the candle. This is MT5's volume for most instruments. |
| 6 | `closeTime` | LONG | Last millisecond of the candle, Unix ms. |
| 7 | `realVolume` | LONG | Exchange-reported traded volume. `0` on symbols where the trade server has no real volume (most forex and CFD symbols). |

New elements may be appended to the end of a row without notice. Index from the front.

**Notes**

- Bars are **aligned to the Unix epoch in UTC**, not to the trade server's session. `1d` candles
  therefore open at 00:00 UTC, which is **not** the broker's trading day and will not match the
  daily candle in an MT5 terminal. Use `1h` or finer if you need session alignment, and build the
  daily bucket yourself.
- `1w` and `1M` are **not supported**. Epoch-aligned bucketing does not produce correct calendar
  weeks or months; build them from `1d`.
- The service reads 1-minute bars from the trade server and aggregates. The source window per
  request is bounded (currently \~50,000 minutes, about 34 days). A request whose
  `startTime`/`endTime` window or `limit` implies more one-minute history than that returns the
  most recent candles within the bound rather than an error — check `openTime` on the first row
  rather than assuming you received `limit` candles.
- There are no gaps for weekends and market closures: candles simply do not exist for those
  periods. Do not assume consecutive rows are `interval` apart.