> For the complete documentation index, see [llms.txt](https://docs.infoway.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.infoway.io/en-docs/rest-api/market-data/post-candlestick-real-historical.md).

# POST Candlestick(Real/Historical)

Access historical and realtime candlesticks for stocks, crypto, forex, energy, and commodities.

### Overview

This endpoint returns OHLCV candles. **It is not the order-book API.**

This endpoint is **POST** with a JSON body.

### Request frequency

Shares the same HTTP [rate limits](https://docs.infoway.io/en-docs/getting-started/api-limitation/rest-api-limitation) as other REST endpoints. Per-second quota depends on the plan.

### Error codes

See [REST API Error Codes](https://docs.infoway.io/en-docs/getting-started/error-codes/rest-api-error-codes). Common values: `503` candle count, `505` symbol count, `508` unknown symbol, `513` timestamp outside the plan.

Address list: [Endpoints](https://docs.infoway.io/en-docs/getting-started/endpoints).

### Endpoint

| Market                                      | Full URL                                        |
| ------------------------------------------- | ----------------------------------------------- |
| Equities (US, HK, CN A-shares)              | `https://data.infoway.io/stock/v2/batch_kline`  |
| Japan                                       | `https://data.infoway.io/japan/v2/batch_kline`  |
| India                                       | `https://data.infoway.io/india/v2/batch_kline`  |
| Korea                                       | `https://data.infoway.io/korea/v2/batch_kline`  |
| Taiwan                                      | `https://data.infoway.io/taiwan/v2/batch_kline` |
| Crypto                                      | `https://data.infoway.io/crypto/v2/batch_kline` |
| Forex, energy, commodities, metals, futures | `https://data.infoway.io/common/v2/batch_kline` |

A-shares use `.SH` / `.SZ`. Hong Kong codes are 5 digits. See Symbol convention.

### Authentication

| Header   | Type   | Required | Description  |
| -------- | ------ | -------- | ------------ |
| `apiKey` | String | Yes      | Plan API key |

### Request body

```json
{
    "klineType": 1,
    "klineNum": 10,
    "codes": "TSLA.US,AAPL.US",
    "timestamp": 1758553860
}
```

| Parameter   | Type   | Required | Description                                                                                                      | Example           |
| ----------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- | ----------------- |
| `klineType` | int    | Yes      | `1` 1m; `2` 5m; `3` 15m; `4` 30m; `5` 1h; `6` 2h; `7` 4h; `8` day; `9` week; `10` month; `11` quarter; `12` year | `1`               |
| `klineNum`  | int    | Yes      | Up to 500 candles for one symbol; multi-symbol requests return only the latest 2 per symbol                      | `500`             |
| `codes`     | String | Yes      | Comma-separated, up to 100 symbols                                                                               | `TSLA.US,AAPL.US` |
| `timestamp` | long   | No       | Unix seconds. Minute / hour candles only. Omit for the latest candles. History depth depends on the plan         | `1727007864`      |

### Example response

```json
{
    "ret": 200,
    "msg": "success",
    "traceId": "19814db2-42f7-4788-9b51-b2001bf17953",
    "data": [
        {
            "s": "TSLA.US",
            "respList": [
                {
                    "t": "1751372340",
                    "h": "298.620",
                    "o": "298.439",
                    "l": "298.100",
                    "c": "298.310",
                    "v": "24329",
                    "vw": "7259092.235",
                    "pc": "-0.02%",
                    "pca": "-0.070"
                }
            ]
        }
    ]
}
```

| Field      | Type   | Description           | Example   |
| ---------- | ------ | --------------------- | --------- |
| `s`        | String | Symbol                | `TSLA.US` |
| `respList` | Array  | Candles, newest first |           |

#### `respList`

| Field | Type   | Description                           | Example       |
| ----- | ------ | ------------------------------------- | ------------- |
| `t`   | String | Unix timestamp in seconds             | `1751372340`  |
| `h`   | String | High                                  | `298.620`     |
| `o`   | String | Open                                  | `298.439`     |
| `l`   | String | Low                                   | `298.100`     |
| `c`   | String | Close                                 | `298.310`     |
| `v`   | String | Volume                                | `24329`       |
| `vw`  | String | **Turnover / trade value** (not VWAP) | `7259092.235` |
| `pc`  | String | Percent change                        | `-0.02%`      |
| `pca` | String | Absolute change                       | `-0.070`      |