> 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/rest-api/http-endpoints/get-candles.md).

# POST 获取产品的历史/实时K线(Candles)

获取股票、加密货币、外汇、能源、商品等产品的历史和实时K线

### 接口说明

该接口获取股票、加密货币、外汇、能源、商品等所有产品的历史/实时 K 线（Candles）。

本接口为 **POST**，Body 为 JSON。

### 请求频率

与其他 HTTP 接口共用[频率限制](/getting-started/api-limitation/http.md)，具体每秒次数由套餐决定。

### 错误码说明

见 [HTTP错误码](/getting-started/error-codes/http.md)。常见：`503` K 线根数超限，`505` 产品数超限，`508` 产品不存在，`513` 历史时间戳超出套餐。

地址总览见 [行情地址说明](/getting-started/api-endpoints.md)。

### 接口地址

| 市场              | 完整路径                                            |
| --------------- | ----------------------------------------------- |
| 股票（美股、港股、A 股）   | `https://data.infoway.io/stock/v2/batch_kline`  |
| 日本              | `https://data.infoway.io/japan/v2/batch_kline`  |
| 印度              | `https://data.infoway.io/india/v2/batch_kline`  |
| 韩国              | `https://data.infoway.io/korea/v2/batch_kline`  |
| 台湾              | `https://data.infoway.io/taiwan/v2/batch_kline` |
| 加密货币            | `https://data.infoway.io/crypto/v2/batch_kline` |
| 外汇、能源、商品、贵金属、期货 | `https://data.infoway.io/common/v2/batch_kline` |

A 股用 `.SH` / `.SZ`，港股 5 位补零，见 标的代码约定。

### 请求头

| 参数             | 类型     | 必填 | 描述                 |
| -------------- | ------ | -- | ------------------ |
| `apiKey`       | String | 是  | 套餐 API Key         |
| `Content-Type` | String | 是  | `application/json` |

### 入参示例

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

| 参数名         | 类型     | 必填 | 描述                                                                        | 示例值               |
| ----------- | ------ | -- | ------------------------------------------------------------------------- | ----------------- |
| `klineType` | int    | 是  | 1：1 分钟；2：5 分钟；3：15 分钟；4：30 分钟；5：1 小时；6：2 小时；7：4 小时；8：日；9：周；10：月；11：季；12：年 | `1`               |
| `klineNum`  | int    | 是  | 正整数。单产品最多 500 根；多产品同时查每产品最多 2 根，较大的请求值会按 2 根处理                            | `500`             |
| `codes`     | String | 是  | 逗号分隔，最多 100 个                                                             | `TSLA.US,AAPL.US` |
| `timestamp` | long   | 否  | 查询结束时间，Unix 秒（包含该秒），所有周期均可传；不传查最新。分钟 / 小时周期的历史范围由套餐决定                     | `1727007864`      |

### 查询与翻页

`codes` 必须是逗号分隔的字符串，不能传 JSON 数组。多个产品时，每个产品最多返回 2 根，不足时按实际可用数据返回。

`timestamp` 指定结束时间，返回 K 线满足 `t <= timestamp`，并按时间从新到旧排列。继续向过去查询时，将本页最早的 `t` 转为整数后减 1，作为下一次请求的 `timestamp`。超过当前时间的 `timestamp` 按查询最新数据处理。

周期 1–7（分钟 / 小时 K）会校验秒时间戳和套餐历史范围；8–12（日及以上 K）仍按 `timestamp` 筛选，但不做这项历史范围校验。最新一根 K 线可能尚未结束，后续查询时会更新。

### 返回示例

```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"
                }
            ]
        }
    ]
}
```

| 字段名        | 类型     | 描述           | 示例值       |
| ---------- | ------ | ------------ | --------- |
| `s`        | String | 标的代码         | `TSLA.US` |
| `respList` | Array  | K 线列表，时间从大到小 |           |

#### respList

| 字段名   | 类型     | 描述                   | 示例值           |
| ----- | ------ | -------------------- | ------------- |
| `t`   | String | 秒时间戳                 | `1751372340`  |
| `h`   | String | 最高价                  | `298.620`     |
| `o`   | String | 开盘价                  | `298.439`     |
| `l`   | String | 最低价                  | `298.100`     |
| `c`   | String | 收盘价                  | `298.310`     |
| `v`   | String | 成交量                  | `24329`       |
| `vw`  | String | **成交额**（不是均价 / VWAP） | `7259092.235` |
| `pc`  | String | 涨跌幅                  | `-0.02%`      |
| `pca` | String | 涨跌额                  | `-0.070`      |

### GET 兼容入口

股票、加密货币和 common 市场也支持以下 GET 入口，使用相同的 `apiKey` 请求头及产品数、K 线根数、周期和历史范围限制。

| 市场               | 完整路径                                                                        |
| ---------------- | --------------------------------------------------------------------------- |
| 股票（美股、港股、A 股）    | `https://data.infoway.io/stock/batch_kline/{klineType}/{klineNum}/{codes}`  |
| 加密货币             | `https://data.infoway.io/crypto/batch_kline/{klineType}/{klineNum}/{codes}` |
| 外汇、能源、商品、贵金属、期货等 | `https://data.infoway.io/common/batch_kline/{klineType}/{klineNum}/{codes}` |

`klineType`、`klineNum` 和 `codes` 放在路径中；可选的秒时间戳 `timestamp` 放在 Query 中。

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

需要按结束时间查询时，在 URL 后添加 `?timestamp=<Unix秒时间戳>`。日本、印度、韩国和台湾市场使用本页前述 POST 入口。

### 数值格式

`/common/v2/batch_kline` 的 `o`、`h`、`l`、`c`、`v`、`vw`、`pca` 保留 5 位小数；`pc` 是含 `%` 的百分比字符串。

加密货币 K 线的 `pca` 按本根收盘价减上一根收盘价计算，`pc` 为该差值除以上一根收盘价的百分比；没有可用上一根时回退为相对本根开盘价计算。分钟 K 线的这两个字段表示该周期的变化。