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
- This Websocket connection provides real-time update for positions across all instruments.
- 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 Introduction > Authentication & Code Snippet > Futures > Websocket Private Interface.
Websocket URL
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 | Base currency of the instrument, i.e., BTC |
| 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 | Base currency of the instrument e.g., BTC |
| -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 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) |
| -quantityUnit | String | 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) |
| -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 Introduction > 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 (Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface)
Note: For a complete Java code example, please refer to Introduction > 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'},.......