> 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)

### Overview

The **Real-Time/Historical Candlestick API** provides the latest candlestick data (OHLCV - Open, High, Low, Close, Volume) for various financial products, including stocks, cryptocurrencies, forex, energy, commodities, and more. This API allows users to retrieve real-time candlestick data for a specified list of symbols, based on different time intervals.

### Endpoint

<table><thead><tr><th width="179.77777099609375">Market</th><th>Endpoint</th></tr></thead><tbody><tr><td>Stocks（US、HK、CN）（No Adjustment）</td><td><code>https://data.infoway.io/stock/v2/batch_kline</code></td></tr><tr><td>Crypto</td><td><code>https://data.infoway.io/crypto/v2/batch_kline</code></td></tr><tr><td>Japan（Forward Adjustment）</td><td><code>https://data.infoway.io/japan/v2/batch_kline</code></td></tr><tr><td>India（Forward Adjustment）</td><td><code>https://data.infoway.io/india/v2/batch_kline</code></td></tr><tr><td>Korea（Forward Adjustment）</td><td><code>https://data.infoway.io/korea/v2/batch_kline</code></td></tr><tr><td>Forex, Commodities, Futures</td><td><code>https://data.infoway.io/common/v2/batch_kline</code></td></tr></tbody></table>

### Request Frequency

This API shares the same rate limits as other endpoints. The number of allowed requests per second depends on your subscription plan. Please refer to the [**Rate Limit Policy**](/en-docs/getting-started/api-limitation/rest-api-limitation.md) for details.

### Error Codes

See the [HTTP Error Codes](/en-docs/getting-started/error-codes/rest-api-error-codes.md) section for reference.

### Authentication

Each request must include your **API Key** in the header.

| **Header** | **Type** | **Required** | **Description**                                 |
| ---------- | -------- | ------------ | ----------------------------------------------- |
| `apiKey`   | String   | Yes          | Your API Key associated with your current plan. |

#### Request Body Parameters (JSON)

<table data-header-hidden><thead><tr><th width="119.6666259765625"></th><th width="79.66668701171875"></th><th width="99.66656494140625"></th><th width="221.6666259765625"></th><th></th></tr></thead><tbody><tr><td><strong>Parameter</strong></td><td><strong>Type</strong></td><td><strong>Required</strong></td><td><strong>Description</strong></td><td><strong>Example</strong></td></tr><tr><td><code>klineType</code></td><td>int</td><td>Yes</td><td>The type of candlestick interval. Options:<br><code>1</code> = 1 minute<br><code>2</code> = 5 minutes<br><code>3</code> = 15 minutes<br><code>4</code> = 30 minutes<br><code>5</code> = 1 hour<br><code>6</code> = 2 hours<br><code>7</code> = 4 hours<br><code>8</code> = 1 day<br><code>9</code> = 1 week<br><code>10</code> = 1 month<br><code>11</code> = 1 quarter<br><code>12</code> = 1 year</td><td><code>1</code></td></tr><tr><td><code>klineNum</code></td><td>int</td><td>Yes</td><td>Number of candle to query (up to 500 candles per symbol; for multiple symbols, only the most recent 2 candles per symbol can be queried).</td><td><code>500</code></td></tr><tr><td><code>codes</code></td><td>String</td><td>Yes</td><td>Comma-separated list of product codes to query. (Up to 100 symbol at once).</td><td><code>TSLA.US,AAPL.US</code></td></tr><tr><td><code>timestamp</code></td><td>Long</td><td>No</td><td>For minute and hourly candlestick only. A timestamp in seconds to query historical data. If not provided, the most recent candles are returned.</td><td><code>1727007864</code></td></tr></tbody></table>

### 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"
                },
                {
                    "t": "1751372280",
                    "h": "298.450",
                    "o": "298.090",
                    "l": "298.000",
                    "c": "298.380",
                    "v": "32214",
                    "vw": "9607344.900",
                    "pc": "0.10%",
                    "pca": "0.290"
                }
            ]
        },
        {
            "s": "01810.HK",
            "respList": [
                {
                    "t": "1751270400",
                    "h": "59.950",
                    "o": "59.950",
                    "l": "59.950",
                    "c": "59.950",
                    "v": "23669600",
                    "vw": "1418992520.000",
                    "pc": "0.50%",
                    "pca": "0.300"
                },
                {
                    "t": "1751270340",
                    "h": "59.700",
                    "o": "59.650",
                    "l": "59.650",
                    "c": "59.650",
                    "v": "829002",
                    "vw": "49466778.300",
                    "pc": "-0.08%",
                    "pca": "-0.050"
                }
            ]
        }
    ]
}
```

### Response Fields

| **Field**  | **Type** | **Required** | **Description**                          | **Example / Values** |
| ---------- | -------- | ------------ | ---------------------------------------- | -------------------- |
| `s`        | String   | Yes          | Product code or symbol.                  | `TSLA.US`            |
| `respList` | Array    | Yes          | List of candlestick data for the symbol. | See below            |

### **`respList` Fields**

| **Field** | **Type** | **Required** | **Description**                                             | **Example**   |
| --------- | -------- | ------------ | ----------------------------------------------------------- | ------------- |
| `t`       | `string` | Yes          | Time of the candlestick in Unix timestamp format (seconds). | `1751372340`  |
| `h`       | `string` | Yes          | High price of the candlestick.                              | `298.620`     |
| `o`       | `string` | Yes          | Open price of the candlestick.                              | `298.439`     |
| `l`       | `string` | Yes          | Low price of the candlestick.                               | `298.100`     |
| `c`       | `string` | Yes          | Close price of the candlestick.                             | `298.310`     |
| `v`       | `string` | Yes          | Volume of the candlestick.                                  | `24329`       |
| `vw`      | `string` | Yes          | Weighted average price of the candlestick.                  | `7259092.235` |
| `pc`      | `string` | Yes          | Percentage change in price.                                 | `-0.02%`      |
| `pca`     | `string` | Yes          | Price change in absolute terms.                             | `-0.070`      |

### Notes

* This API supports various candlestick intervals (e.g., 1 minute, 5 minutes, 1 day, 1 week, etc.) to suit different trading strategies and analysis needs.
* The `timestamp` field allows you to query historical candlestick data based on a specific point in time, which is especially useful for minute and hourly intervals.
* The `klineNum` parameter allows you to specify the number of candlestick to query, with a maximum of 500 candles per product.