Subscribe Trade Data

API Description

This Websocket API provides trade data for a specified instrument, including contract size, direction, trade ID, timestamp, and price.

Note: Trade data 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

None

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 50 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., "fills". 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.

Response Parameters

Parameter	Type	Description
biz	String	Specifies the channel, e.g., "futures".
type	String	Function type e.g., "fills".
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:
-createdDate	Long	Timestamp when the trade occurred
-quantity	BigDecimal	Order size in base currency
-piece	BigDecimal	The number of contracts
-price	BigDecimal	The executed transaction price.
-id	Long	Primary key ID
-direction	String	Trade direction: long, short.

Subscription Example

The following Python code shows how subscribe to the trade 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": "fills"}}
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 trade data in real time. For brevity, only one trade is shown below from Python subscription:

{'biz': 'futures',
 'pairCode': 'BTC',
 'data': {'result': True},
 'channel': 'subscribe',
 'type': 'fills'}
{'biz': 'futures',
 'pairCode': 'BTC',
 'data': [{'createdDate': 1740386094525,
   'quantity': 0.007,
   'piece': 7,
   'price': 95449,
   'id': 20742103698619397,
   'direction': 'long'}],
 'type': 'fills'},...........