Subscribe Position Change

API Description

This Websocket provides real-time updates on position changes (filled orders) across all instrument. This websocket also provides updates on net realized profit or loss.

Note: Position change data is only available via Websocket API.

Precautions

1. Users must establish a connection first. Once connected, all changes in positions across all instruments will be streamed in real-time.

Authentication

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

Websocket URL

wss://ws.futurescw.com/perpum

Frequency limit

None

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_change".
-- 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_change".
result	boolean	Indicates whether the subscription or unsubscription was 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:
-currentPiece	String	Current number of contracts
-isProfession	Integer	Indicates match server processing status
-leverage	String	Leverage applied to the position.
-originalType	String	Original type of order, e.g., "execute".
-orderId	String	Order ID.
-contractType	Integer	Type of contract: 1 : Perpetual contract.
-openId	String	Unique ID for the opened position.
-fee	String	Fee
-openPrice	String	Opening price (at which order gets filled)
-orderStatus	String	Status of the order, e.g., "finish".
-instrument	String	Base currency of the instrument, e.g., "BTC".
-quantityUnit	Integer	Specifies the unit for order size: 0: Denominated in the quote currency (e.g., USDT in BTC-USDT), 1: Denominated in number of contracts, 2: Denominated in the base currency (e.g., BTC in BTC-USDT)
-source	String	Source: api/web
-updatedDate	Long	Timestamp Update timestamp (in ms).
-positionModel	Integer	Position margin mode: 0: Isolated margin, 1: Cross margin
-feeRate	String	The rate at which fees are calculated.
-netProfit	String	Net realized profit or loss.
-baseSize	String	Order size in base currency
-liquidateBy	String	Position closing event e.g., "manual".
-totalPiece	String	Total number of contracts.
-orderPrice	String	Order price specified by user.
-id	String	Unique identifier of the trade entry.
-fundingSettle	String	Amount of funding settled on this position.
-direction	String	Trade direction: long/short
-margin	String	Margin used for the position.
-takerMaker	Integer	1 for taker, 2 for maker.
-indexPrice	String	Index price
-quantity	String	Specifies order size based on quantityUnit: If quantityUnit=0, the quantity is measured the quote currency (e.g., USDT in BTC-USDT), 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)
-userId	String	User ID
-closedPiece	String	Number of contracts that have been closed.
-createdDate	Long	Creation timestamp
-hedgeId	String	Hedge ID.
-closePrice	String	Price at which the position gets closed
-positionMargin	String	Margin allocated to the position.
-realPrice	String	Executed price of the order.
-status	String	Status: 0: Open , 1: Close , 2: Cancel

Subscription Example

The following Python code shows how to subscribe to position changes.

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

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

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

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

Response Example

The Websocket will keep updating position changes in real time. For brevity, only one position change from above Python subscription is shown below:

{'biz': 'futures',
 'data': {'result': true},
 'channel': 'subscribe',
 'type': 'position_change'}
{'biz': 'futures',
 'pairCode': 'BTC',
 'data': [{'currentPiece': '1',
   'isProfession': 0,
   'leverage': '5',
   'originalType': 'execute',
   'orderId': '33308809187064313',
   'contractType': 1,
   'openId': '2435521222633466843',
   'fee': '0.055707',
   'openPrice': '92845',
   'orderStatus': 'finish',
   'instrument': 'BTC',
   'quantityUnit': 1,
   'source': 'api',
   'updatedDate': 1745501769376,
   'positionModel': 0,
   'feeRate': '0.0006',
   'netProfit': '0',
   'baseSize': '0.001',
   'liquidateBy': 'manual',
   'totalPiece': '1',
   'orderPrice': '2147483647',
   'id': '21412625432427527',
   'fundingSettle': '0',
   'direction': 'long',
   'margin': '18.513293',
   'takerMaker': 1,
   'indexPrice': '92844.9',
   'quantity': '18.569',
   'userId': '1162061',
   'closedPiece': '0',
   'createdDate': 1745501769376,
   'hedgeId': '21412625432427528',
   'closePrice': '0',
   'positionMargin': '18.569',
   'realPrice': '92845',
   'status': 'open'}],
 'type': 'position_change'},.....