# 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</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>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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.infoway.io/en-docs/rest-api/market-data/post-candlestick-real-historical.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.