Get Historical K-Line of an Instrument

API Description

This interface allows querying the historical and recent K-line data for a specified instrument including the high price, low price, open price, close price, timestamp and trading volume.

Note: K-line data is available via both Resful and Websocket APIs. This page describes the RESTful API, which supports retrieval of both recent and historical K-line data. For real-time K-line updates, please refer to the WebSocket API at click here for UTC+0 and click here for UTC+8.

Precautions

1. Max number of K-line records per request is 1500 records. To retrieve historical K-line data, clients should implement proper pagination by specifying both start (sinceStr) and end (sinceEndStr) timestamps. It is important to respect the interface’s frequency limit while retrieving historical data.
2. The API reflects the same data shown on the CoinW webpage i.e., K-line data starts from the time a specific instrument was launched on CoinW. For example, BTC perpetual contracts are available from 2019-10-26. However, due to exchange data inconsistencies or system maintenance, some K-lines may be missing or incomplete for certain intervals. Clients should implement data integrity checks when using the data for analysis or backtesting.
3. If the specified interval is still in progress, an incomplete K-line may be returned.

Authentication

This is a public interface and does not require authentication. For details on using the RESTful API, please refer to Introduction > Authentication & Code Snippet > Futures > RESTful Public Interface.

Request Method

GET

Endpoint

/v1/perpumPublic/klines

Frequency Limit

The frequency limit for this interface is 20 requests/2s per user ID and IP. In addition to this per-interface limit, a global rate limit is also enforced.

For detailed information on Global rate limits and API Rate Limiting Policy, please refer to the "Frequency Limit" section at click here

Request Parameters

Parameter	Mandatory	Type	Description
currencyCode	true	String	The base currency of the instrument. (e.g., BTC or btc). This parameter is case-insensitive. Note: For instruments that start with numbers (e.g., 1000PEPE), both uppercase and lowercase formats are valid.
granuality	true	String	The K-line time interval represented by integers 0 to 9, where 0: 1-minute, 1: 5-minute, 2: 15-minute, 3:1-hour, 4:4-hours, 5: 1-day, 6: 1-week, 7: 3-minute, 8: 30-minute, and 9: 1-month.
limit	false	Integer	Specifies the number of K-line records (candles) to return, with a valid range from 1 to 1,500. Regardless of the selected granularity, maximum number of records returned cannot exceed 1,500. Note: 1. Default value for limit is 100 records. 2. Additionally, if historical data is not available for the full requested number of records, the response will include only the available data up to that point.
klineType	false	string	Timezone type: "0" = UTC, "1" = UTC+8 Note: Default value for timezone is UTC+8
sinceStr	false	string	Start timestamp (milliseconds) Note: This parameter can be ignored when retrieving the most recent K-line data.
sinceEndStr	false	string	End timestamp (milliseconds) Note: This parameter can be ignored when retrieving the most recent K-line data.

Response Parameters

Parameter	Type	Description
-	Long	K-line timestamp
-	BigDecimal	Highest price within the interval.
-	BigDecimal	Opening price of the interval.
-	BigDecimal	Lowest price within the interval.
-	BigDecimal	Closing price of the interval.
-	BigDecimal	Trading volume of the interval.

Request Examples

Request Example for Retrieveing Historical -Kline Data:

The following Python code example demonstrates how to retrieve historical 1-minute K-line data (granularity = 0) for BTC within the time range from "2023-01-01 00:00:00" (timestamp: 1672516800000) to "2023-01-31 23:59:00" (timestamp: 1675195140000).

This period spans 44,640 minutes, and therefore, 44,640 records are expected to be returned. Users are advised to verify and handle any missing data on their end. Due to the maximum limit of 1,500 records per request (approximately 1,500 minutes), the code splits the target time range into multiple segments, sends requests to the API sequentially, and merges the results locally in chronological order to form a complete dataset.

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

Request Example for Retrieving Recent k-line data :

The following Python code shows how to get the recent 5 records of 1-minute k-line data (granularity=0) for BTC.

Note: For a complete code example, please refer to Introduction > Authentication & Code Snippet > Futures > RESTful Public Interface.

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)

Note: For a complete Java code example, please refer to Introduction > Authentication & Code Snippet > Futures > RESTful Public Interface.

Response Example

The following is an example response returned by the above Python request:

{'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': ''}