获取指定交易品种的历史K线数据

API说明

该接口用于查询指定交易品种的历史和最新K线数据，返回包括最高价、最低价、开盘价、收盘价、时间戳以及成交量等信息。

注意：K线数据可通过RESTful和Websocket接口获取。本页是RESTful接口的描述， 支持查询 最新和历史 K 线数据。如需实时 K 线更新，请参阅 WebSocket API，UTC+0 时区请点击 跳转，UTC+8 时区请点击 跳转

注意事项

1. 单次请求最多返回1500条记录。 建议在查询历史K线数据时，合理使用 ‘sinceStr’（起始时间戳）与 ‘sinceEndStr’（结束时间戳）进行分页。同时需遵守接口的频率限制。
2. 本接口返回的数据与 CoinW 网站显示一致，K线起始时间为该交易品种上线 CoinW 的时间。例如：BTC 永续合约数据自 2019-10-26 起提供。部分时间段因交易所数据缺失或系统维护，可能存在遗漏，建议用户进行数据完整性校验。
3. 若查询时间区间包含当前尚未结束的K线，返回的该条K线为非完整K线。

认证

这是一个公共接口，不需要认证。有关使用RESTful API的详细信息，请参考简介 > 认证和代码示例 > 合约 > RESTful公共接口。

请求方法

GET

接口地址

/v1/perpumPublic/klines

频率限制

该接口的调用频率限制为：每个 IP 和用户 ID 每2秒最多请求20次。
此外，该接口还受到全局频率限制的约束。
有关"全局速率限制"和"多阶段风控限频机制"的详细信息，请参阅“频率限制”部分，跳转

请求参数

参数	必填	类型	描述
currencyCode	true	String	注意：USDT 合约只需传入基础货币名称，如 BTCUSDT 传 BTC 即可；USDC 合约请传完整交易对，如 BTC_USDC。此参数不区分大小写。 注意：对于以数字开头的交易品种（例如，1000PEPE），大写和小写格式均有效。
granuality	true	String	K线时间间隔，由整数0到9表示，其中0：1分钟，1：5分钟，2：15分钟，3：1小时，4：4小时，5：1天，6：1周，7：3分钟，8：30分钟，9：1个月。
limit	false	Integer	指定返回的 K 线记录（蜡烛图）数量，有效范围为 1 到 1,500。无论选择的 granularity 如何，默认返回记录数为 100，且最大不能超过 1,500 条。 注意: 此外，如果无法获取请求的全部记录数的历史数据，则响应将仅包含截至该时间点的可用数据。
klineType	false	String	时区类型： "0" = UTC， "1" = UTC+8。 注意: 默认值为 UTC+8。
sinceStr	false	String	起始时间戳（毫秒）。 注意: 获取最新 K 线时可不传该参数。
sinceEndStr	false	String	结束时间戳（毫秒）。 注意: 获取最新 K 线时可不传该参数。

响应参数

参数	类型	描述
-	Long	时间戳
-	BigDecimal	最高价格
-	BigDecimal	开盘价格
-	BigDecimal	最低价格
-	BigDecimal	收盘价格
-	BigDecimal	交易量

请求示例

获取历史 K 线数据示例：

以下 Python 示例展示了如何查询 BTC 从 "2023-01-01 00:00:00"（时间戳：1672516800000）到 "2023-01-31 23:59:00"（时间戳：1675195140000）之间的历史 1 分钟 K 线数据（granularity = 0）。

此时间区间共计 44,640 分钟，因此预期返回 44,640 条记录。建议用户在本地对数据进行完整性校验和补全处理。 由于接口单次调用存在条数限制（最大 1500 条记录，合 1500 分钟），代码会将目标时间范围拆分为多段，依次向 API 发送请求，并将每段结果在本地按时间顺序拼接成完整数据。

import requests
import time
import json
from datetime import datetime, timedelta

# Configuration
url = "https://api.coinw.com/v1/perpumPublic/klines"
currency_code = "btc"
granularity = "0"  # 1-minute kline
kline_type = "0"   # UTC time
limit = 1500       # Max number of klines per request

# Set your start and end time. Assuming the following datetimes are in UTC time.
start_date = "2023-01-1 00:00:00"
end_date = "2023-01-31 23:59:00"

start_time = datetime.strptime(start_date, "%Y-%m-%d %H:%M:%S")
end_time = datetime.strptime(end_date, "%Y-%m-%d %H:%M:%S")


start_ms = int(start_time.timestamp() * 1000)
end_ms = int(end_time.timestamp() * 1000)
step_ms = 1500 * 60 * 1000  # 1500 minutes in milliseconds

# Collect all klines
all_klines = []

# Iterate over time chunks
while start_ms < end_ms:
    next_end = min(start_ms + step_ms, end_ms)

    params = {
        "currencyCode": currency_code,
        "granularity": granularity,
        "klineType": kline_type,
        "limit": str(limit),
        "sinceStr": str(start_ms),
        "sinceEndStr": str(next_end)
    }

    try:
        response = requests.get(url, params=params)
        response.raise_for_status()
        data = response.json()

        # Log the response to file
        with open("kline_logs.json", "a") as log_file:
            json.dump({"start": start_ms, "end": next_end, "data": data}, log_file)
            log_file.write("\n")

        if data.get("data"):
            all_klines.extend(data["data"])
            print(f"Fetched {len(data['data'])} records from {start_ms} to {next_end}")
        else:
            print(f"No data for range {start_ms} to {next_end}")

    except Exception as e:
        print(f" Error fetching data: {e}")

    start_ms = next_end
    time.sleep(0.2)  # To avoid hitting API rate limits


print(" Done! All klines saved in kline_logs.json")

获取最新 K 线数据示例：

以下Python代码展示了如何获取BTC的1分钟K线数据（granularity=0），限制为5条记录。

注意: 完整代码示例请参考简介 > 认证和代码示例 > 合约 > Restful公共接口。

api_url = "/v1/perpumPublic/klines"
params = {
    		"currencyCode": "BTC",  
    		"granularity": "0",     
    		"limit": 5            
			}    
FuturesRestfulPublic(api_url, params) 	# function FuturesRestfulPublic() is defined in section (Introduction > Authentication & Code Snippet > Futures > RESTful Public Interface)

注意: 完整Java代码示例请参考简介 > 认证和代码示例 > 合约 > RESTful公共接口。

响应示例

以下是上述Python请求返回的示例响应：

{'code': 0,
 'data': [[1752832500000, 118815.0, 118882.6, 118808.3, 118882.6, 61.333],
  [1752832560000, 118882.4, 118910.7, 118882.3, 118882.7, 46.582],
  [1752832620000, 118882.7, 118922.8, 118882.5, 118911.9, 43.613],
  [1752832680000, 118911.8, 118936.1, 118875.2, 118888.3, 48.924],
  [1752832740000, 118888.3, 118888.4, 118885.0, 118885.0, 11.688]],
 'msg': ''}