Websocket-Futures Orders Position
The interface supports two connection methods: token connection and apikey connection. Regardless of the connection and subscription method, the returned data message body is the same.
1. Token Connection
Overview: Carry the token in the request header to establish a connection with the backend. After the connection is established, send a message to subscribe. Only after a successful subscription can you receive pushed messages.
1.1 Request URL
wss://futuresws.exchange1.com/position_order/ws1.2 Request Headers
token
string
Yes
Token generated after login
1.3 Message Body to Send
event
string
Yes
`sub` : subscribe message `unsub` : unsubscribe message
token
string
Yes
Token generated after login
broker
Integer
Yes
SaaS merchant ID
Example:
{
"event": "sub",
"token": "9a2fce1e96cb42e76aa9519ee26468cd6d58efddd67d4bc1a9a0fa128734c0fe",
"broker": 1003
}2. Apikey Connection
Overview: Carry the api-key in the request header to establish a connection with the backend. After the connection is established, send a message to subscribe. Only after a successful subscription can you receive pushed messages.
2.1 Request URL
wss://futuresws.exchange1.com/position_order/ws2.2 Request Headers
api-key
string
Yes
User's Apikey
2.3 Message Body to Send
event
string
Yes
`sub` : subscribe message `unsub` : unsubscribe message
apiKey
string
Yes
Token generated after login
broker
Integer
Yes
SaaS merchant ID
Example:
{
"event": "sub",
"apiKey": "70556a7b653367858dfb0e4fc441cf00",
"broker": 1003
}3. Receiving Messages
After a successful connection, the backend returns:
connect successAfter a successful subscription, the backend returns:
sub success
The actual message body is GZIP-compressed binary data, which needs to be parsed before it can be displayed properly. You can implement the parsing tool in your own language. Here is an online reference tool: https://www.bejson.com/encrypt/gzip/#google_vignette
For example, the received binary Base64 data:
H4sIAAAAAAAAAD2NywrCQAxF/yXrYchMkpmkO1EXggtxKyL1AQpapdZV6b87rWB2l3vuSQ+f2xkqymyiDk7Xumkud6hgtlgfNtvVfAkOSt718GihQo+olKKlGCIGplDaDiqVHNSzg2s9QSVpNGVGKlfEdXFEB+OvqEQsycH7OQ3RPDnoXj9L9hh0HJGZSSSL6OD4J4ujnUhG8crZiJIEwZQkpWE/fAGMewQM0AAAAA==After parsing:
{
"uid": 374958,
"channel": "ADL_PRICE",
"l": [
{
"mr": 0.0083629621201431,
"lt": 85718.4,
"ha": 0.0718829844033338,
"al": 2,
"id": 2833456,
"so": 85709.3,
"tp": 85717.0183333399952392,
"bo": 85709.2,
"rp": 85405.8479336515066566
}
]
}Message Field Descriptions
3.1 When Position or Account Changes
{
"channel": "ACCOUNT_UPDATE", // channel: different event types, ACCOUNT_UPDATE is pushed when position or account changes
"uid": 1001, // Contract user ID
"t": "1564745798938", // Timestamp
"d": { // Data
"et": "CREATE", // UPDATE, DELETE, DEFAULT
// CREATE: Add a new position, p is not empty, and all position data is returned
// DELETE: Delete a position, p is not empty, and only the position id is returned
// UPDATE: Update a position, p is not empty, and only the changed fields are returned
// DEFAULT: Position unchanged, only account info changed, p is empty
"a": [ // Account list
{
"c": "USDT", // Currency name
"an": "122624.12345678", // Account balance
"la": "100.12345678", // Frozen account balance
"pn": "50.12345678" // Isolated margin account balance
},
{
"c": "BTC", // Currency
"an": "122624.12345678", // Account balance
"la": "100.12345678", // Frozen account balance
"pn": "50.12345678" // Isolated margin account balance
}
],
"p": { // Position info
"id": 90762, // Position ID
"cid": 127, // Contract ID
"pt": 1, // Position type: 1 Cross, 2 Isolated
"cn": "S-BTC-USDT", // Contract name
"con": "BTCUSDT-EXUSD", // Contract alias
"l": 20, // Leverage
"pv": 12, // Position volume
"op": 98533.6, // Average open price
"rp": 68000.3, // Estimated liquidation price
"hm": 98.22008325596366, // Isolated margin held
"ra": 2, // Realized PnL
"s": "BUY", // Position direction
"mr": 0.0847015132701974, // Margin rate
"oa": 0.0847015132701974, // Opening margin
"ccv": 2 // Closable volume
}
}
}3.2 When User Holds a Position
{
"channel": "ADL_PRICE", // When the user holds a position, ADL_PRICE message is pushed every second
"uid": 1001, // Contract user ID
"l": [
{
"id": 7001, // Position ID
"al": 1, // ADL level
"rp": 68000.3, // Estimated liquidation price
"ha": 98.22008325596366, // Margin
"mr": 0.0847015132701974, // Margin rate
"bo": 79000, // Best bid price
"so": 78000, // Best ask price
"lt": 78500, // Last traded price
"tp": 78000 // Mark price
},
{
"id": 7002, // Position ID
"al": 1, // ADL level
"rp": 68000.3, // Estimated liquidation price
"ha": 98.22008325596366, // Margin
"mr": 0.0847015132701974, // Margin rate
"bo": 79000, // Best bid price
"so": 78000, // Best ask price
"lt": 78500, // Last traded price
"tp": 78000 // Mark price
}
]
}3.3 When the System Closes
A fixed message will be pushed:
{
"channel": "SYSTEM",
"uid": 1001,
"et": "close"
}3.4 Normal Order
{
"channel": "order",
"order": {
"orderId": "2094043912705377045",
"contractId": 127,
"contractName": "E-BTC-USDT",
"symbol": "BTC-USDT",
"contractSide": "exchange1",
"type": 1,
"price": 61001,
"pricePrecision": 3,
"dealVolume": 0,
"volume": 100,
"avgPrice": 0,
"otoOrder": {
"takerProfitStatus": false,
"takerProfitTrigger": 61001,
"takerProfitPrice": 0,
"takerProfitTriggerId": null,
"stopLossStatus": false,
"stopLossTrigger": 61004,
"stopLossPrice": 0,
"stopLossTriggerId": null
},
"orderAction": "1" // 1: New, 2: Cancel, 3: Order change
}
}3.5 Trigger Order Return Data
{
"channel": "trigOrder",
"trigOrder": {
"triggerOrderId": "1322738336974712854",
"type": 1,
"side": "buy",
"triggerPrice": 61001,
"price": 61003,
"volume": 10,
"triggerType": 3,
"ctime": 1709550135000,
"expireTime": 1710759735000,
"orderAction": "1" // 1: New, 2: Cancel
}
}4. Heartbeat
Ping every 30 seconds. If the server does not receive a ping for more than 40 seconds, it will actively disconnect.
Parameter sent:
{"ping":1713338308232}Response:
{"pong":1713338308233}