Subscribe K-Line(UTC+8)

API Description

This Websocket API provides K-line data for a specified instrument, including the timestamp, high price, low price, open price, close price and trading volume. Each candle is timestamped according to the UTC+8 time zone.

Note: K-Line(UTC+8) data is available via both Resful and Websocket APIs. This page describes the Websocket API. For information on the RESTful API, please click here

Precautions

1. Each candle is timestamped according to the UTC+8 time zone.
2. The WebSocket API does not support specifying a time span for querying K-line data.
3. It provides real-time K-line data but does not explicitly indicate when an interval has concluded. Users must monitor changes in the opening price to determine the start of a new interval.
4. Additionally, the timestamp updates at the end of each interval, serving as an indication that the previous interval has concluded.

Authentication

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

Websocket URL

wss://ws.futurescw.com/perpum

Frequency limit

The frequency limit for this subscription is 20 requests/2s per IP.

Subscription Parameters

Parameter	Mandatory	Type	Description
event	true	String	Subscribe or unsubscribe. sub: subscribe; unsub: unsubscribe. Note: This parameter is case-sensitive.
params	true	Json	Requested parameter objects including:
-biz	true	String	Specifies the channel, e.g., "futures". Note: Lowercase is recommended.
-type	true	String	Defines the function type, e.g., "candles_swap". Note: Lowercase is recommended.
-pairCode	true	String	Note: for USDT contracts, pass only the base currency name, for example BTCUSDT can use BTC; for USDC contracts, pass the full trading pair, for example BTC_USDC. This parameter is case-insensitive. Note: For instruments that start with numbers (e.g., 1000PEPE), both uppercase and lowercase formats are valid.
-interval	true	String	K-line interval, represented as: "1" (1 min), "3" (3 min), "5" (5 min), "15" (15 min), "30" (30 min), "1H" (1 hour), "4H" (4 hours), "1D" (1 day), "1W" (1 week), "1M" (1 month). Note: This parameter is case-insensitive. Both 1H and 1h are valid.

Response Parameters

Parameter	Type	Description
biz	String	Specifies the channel, e.g., "futures".
type	String	Defines the function type, e.g., "candles_swap".
result	boolean	Indicates whether the subscription or unsubscription is successful: true, false
channel	String	Specifies the action performed: subscribe or unsubscribe.
pairCode	String	Base currency of the instrument, i.e., BTC.
data	Json	Data object, containing the following fields:
-	BigDecimal	Creation time (timestamp)
-	BigDecimal	Opening price of the interval.
-	BigDecimal	Highest price within the intterval.
-	BigDecimal	Lowest price within the interval.
-	BigDecimal	Closing price of the interval.
-	BigDecimal	Trading volume of the interval (in base currency)
interval	String	K-line interval, represented as: "1" (1 min), "3" (3 min), "5" (5 min), "15" (15 min), "30" (30 min), "1H" (1 hour), "4H" (4 hours), "1D" (1 day), "1W" (1 week), "1M" (1 month).

Subscription Example

The following Python code shows how to subscribe to the K-line data.

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

subscription_params =  {
              "event": "sub",
              "params": {
                  "biz": "futures",
                  "pairCode": "btc",
                  "type": "candles_swap",
                  "interval":"1"
              }}
url = "wss://ws.futurescw.com/perpum"
FuturesWebsocketPublic(url, subscription_params)  # function FuturesWebsocketPublic() is defined in section (Common > Authentication & Code Snippet > Futures > Websocket Public Interface)

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

Response Example

The Websocket will keep updating the 1-minute K-line data for BTC in real time. For brevity, only one K-line from Python subscription is shown below:

{'biz': 'futures',
 'pairCode': 'BTC',
 'data': {'result': True},
 'channel': 'subscribe',
 'interval': '1',
 'type': 'candles_swap'}
{'biz': 'futures',
 'pairCode': 'BTC',
 'data': ['1740333420000',
  '95585.5',
  '95616.1',
  '95583.3',
  '95583.5',
  '32.661'],
 'interval': '1',
 'type': 'candles_swap'},........