> 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       |
| `Content-Type` | String | Yes      | `application/json` |

### Request body

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

| 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      | Positive integer. Up to 500 candles for one symbol; multi-symbol requests return at most 2 per symbol, with larger requested counts reduced to 2 | `500`             |
| `codes`     | String | Yes      | Comma-separated, up to 100 symbols                                                                                                               | `TSLA.US,AAPL.US` |
| `timestamp` | long   | No       | Inclusive end time in Unix seconds, supported for all periods. Omit for the latest candles. Minute/hour history depth depends on the plan        | `1727007864`      |

### Queries and pagination

`codes` must be a comma-separated string, not a JSON array. Multi-symbol requests return at most 2 candles per symbol, or fewer when less data is available.

`timestamp` sets the inclusive end time: returned candles satisfy `t <= timestamp` and are ordered newest first. To retrieve an earlier page, convert the oldest returned `t` to an integer, subtract 1, and use that value as the next `timestamp`. A timestamp later than the current time is treated as a request for the latest data.

Periods 1–7 (minute/hour candles) validate both the seconds timestamp and the plan history window. Periods 8–12 (daily and longer candles) still filter by `timestamp`, but do not apply that history-window validation. The latest candle may still be forming and can change in later responses.

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

### GET compatibility endpoints

Equities, crypto, and common-market products also support the following GET endpoints. They use the same `apiKey` header and symbol-count, candle-count, period, and history limits.

| Market                                                            | Full URL                                                                    |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Equities (US, HK, CN A-shares)                                    | `https://data.infoway.io/stock/batch_kline/{klineType}/{klineNum}/{codes}`  |
| Crypto                                                            | `https://data.infoway.io/crypto/batch_kline/{klineType}/{klineNum}/{codes}` |
| Forex, energy, commodities, metals, futures, and related products | `https://data.infoway.io/common/batch_kline/{klineType}/{klineNum}/{codes}` |

Place `klineType`, `klineNum`, and `codes` in the path. The optional `timestamp` is a query parameter in Unix seconds.

```http
GET https://data.infoway.io/crypto/batch_kline/1/10/BTCUSDT
apiKey: YOUR_API_KEY
```

To set an inclusive end time, append `?timestamp=<Unix-seconds>` to the URL. Japan, India, Korea, and Taiwan use the POST endpoints above.

### Numeric format

For `/common/v2/batch_kline`, `o`, `h`, `l`, `c`, `v`, `vw`, and `pca` use 5 decimal places. `pc` is a percentage string including `%`.

For crypto candles, `pca` is the current close minus the previous candle close, and `pc` is that difference divided by the previous close, expressed as a percentage. When no previous candle is available, the calculation falls back to the current candle open. On minute candles, these fields describe the change over that candle period.