Subscribe Position

API Description

This Websocket provides real-time information on all current positions (filled orders) across all instrument.

Note: Current positions data is available via both Resful and Websocket APIs. This page describes the RESTful API. For information on the Websocket API, please click here

Precautions

1. This Websocket connection provides real-time update for positions across all instruments.
2. Users must establish a connection first. Once connected, all newly opened and closed positions across all instruments will be streamed in real-time.

Authentication

This is a private interface and requires authentication. For details on using the RESTful API, refer to Common > Authentication & Code Snippet > Futures > Websocket Private Interface.

Websocket URL

wss://ws.futurescw.com/perpum

Frequency limit

The frequency limit for this subscription is 10 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	Data object containing the following fields:
-type	true	String	Defines the function type, e.g., "position".
-biz	true	String	Specifies the channel, e.g., "futures".

Response Parameters

Parameter	Type	Description
biz	String	Specifies the channel, e.g., "futures".
type	String	Function type e.g., "position".
result	boolean	Indicates whether the subscription or unsubscription was successful: true/ false
channel	String	Specifies the action performed: subscribe or unsubscribe.
pairCode	String	Instrument identifier, e.g., BTC (USDT contracts) or BTC_USDC (USDC contracts).
data	Json	Data object containing the following fields:
-baseSize	String	Number of lots in contract
-closedPiece	String	Number of closed contracts
-closedQuantity	String	Quantity closed
-contractType	String	Contract type: 1: Perpetual contract
-createdDate	Long	Creation timestamp
-currentPiece	String	Current number of contracts
-direction	String	Trade direction: long/short
-distId	String	Distributor ID
-fee	String	Fee
-fundingSettle	String	Funding rate settlement amount
-hedgeId	String	Hedge order ID
-id	String	Position ID
-indexPrice	String	Index price at trigger
-instrument	String	Instrument identifier, e.g., BTC (USDT contracts) or BTC_USDC (USDC contracts).
-isProfession	Integer	Professional order:0-No,1-Yes.
-leaderId	String	Trader ID
-leverage	Integer	Position leverage
-margin	String	Position margin
-openPrice	String	Opening price (at which order gets filled)
-orderPrice	String	Order price specified by user
-originalType	String	Original type of order: e.g., plan / planTrigger / execute
-parentId	String	Registered user (invitee) ID: 0: Active registered user 1: Unregistered user
-partnerId	String	Partner ID
-posType	String	Position type e.g.,plan / planTrigger / execute
-positionMargin	String	Position margin
-positionModel	Integer	Position margin mode: 0: Isolated margin, 1: Cross margin
-processStatus	Integer	Processing status : 0: normal status, 1: processing
-quantity	String	Specifies order size based on quantityUnit: If quantityUnit=0, the quantity is measured in the quote currency (e.g., USDT in BTC-USDT / USDC in BTC-USDC), If quantityUnit=1, the quantity is measured in number of contracts, If quantityUnit=2, the quantity is measured in the base currency (e.g., BTC in BTC-USDT)
-quantityUnit	String	Specifies the unit for order size: 0: Denominated in the quote currency (e.g., USDT in BTC-USDT / USDC in BTC-USDC), 1: Denominated in number of contracts, 2: Denominated in the base currency (e.g., BTC in BTC-USDT)
-remainCurrentPiece	String	Remaining number of contracts
-salesId	String	Sales ID
-settlementId	String	Settlement ID
-source	String	Source: api/web
-status	Integer	Status: 0: Open , 1: Close , 2: Cancel
-totalPiece	String	Total number of contracts
-updatedDate	Long	Update timestamp
-userId	String	User ID

Subscription Example

The following Python code shows how to subscribe to the current positions (filled orders) information using Websocket.

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

url = "wss://ws.futurescw.com/perpum"
subscription_payload = {"event": "sub",
                         "params": {"biz": "futures",
                                    "type": "position"}}
api_key= "your_api_key" 
sec_key = "your_sec_key"

FuturesWebsocketPrivate(url, api_key, sec_key, subscription_payload) # function FuturesWebsocketPrivate() is defined in section (Common > Authentication & Code Snippet > Futures > RESTful Private Interface)

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

Response Example

The Websocket will keep updating the current positions data in real time. For brevity, only one position information from above Python subscription is shown below:

{'biz': 'futures',
 'data': {'result': True},
 'channel': 'subscribe',
 'type': 'position'}
{'biz': 'futures',
 'pairCode': 'BTC',
 'data': [{'currentPiece': '1',
   'isProfession': 0,
   'leverage': '1',
   'distId': '0',
   'originalType': 'execute',
   'processStatus': 0,
   'contractType': 1,
   'fee': '0.05328162',
   'openPrice': '88802.7',
   'instrument': 'BTC',
   'quantityUnit': 0,
   'source': 'api',
   'updatedDate': 1740569719634,
   'positionModel': 0,
   'posType': 'execute',
   'leaderId': '1162061',
   'baseSize': '0.001',
   'closedQuantity': '0',
   'salesId': '0',
   'totalPiece': '1',
   'orderPrice': '0',
   'id': '2435521222631981320',
   'fundingSettle': '0',
   'direction': 'short',
   'margin': '88.8027',
   'indexPrice': '88802.8',
   'quantity': '88.8027',
   'userId': '1162061',
   'parentId': '0',
   'closedPiece': '0',
   'createdDate': 1740569719634,
   'hedgeId': '20766171808644102',
   'partnerId': '0',
   'positionMargin': '88.8027',
   'remainCurrentPiece': '1',
   'status': 'open'}],
 'type': 'position'},.......