Futures

This document outlines establishing and maintaining a WebSocket connection for Futures trading using Token-based or API Key-based authentication. The message format is identical for both connection types.

Token-based Connection

1. Overview

• The client includes a token in the request header.

• After a successful connection, a subscription message must be sent.

• Only after successful subscription will the client begin receiving push notifications.

2. Connection Details

• Request URL:

  wss://futuresws.coinlocally.com/position_order/ws

3. Request Headers

Parameter Name	Type	Required	Description
token	string	Yes	Token generated after login

4. Subscription Message Format

{
  "event": "sub",
  "token": "<your_token>",
  "broker": 1003
}

API Key-based Connection

1. Overview

• The client includes an apiKey in the request header.

• After a successful connection, a subscription message must be sent.

• Only after successful subscription will the client begin receiving push notifications.

2. Connection Details

• Request URL:

  wss://futuresws.coinlocally.com/position_order/ws

3. Request Headers

Parameter Name	Type	Required	Description
apiKey	string	Yes	User's API key

4. Subscription Message Format

{
  "event": "sub",
  "apiKey": "<your_api_key>",
  "broker": 1003
}

Receiving Messages

1. Connection Responses

• Connect Success: "connect success"

• Subscribe Success: "sub success"

2. Message Format

• Messages are GZIP-compressed binary data.

• Use a GZIP decompression tool in your language of choice.

• Online Tool

Example (Base64 Encoded):

H4sIAAAAAAAAAD2NywrCQAxF/yXrYchMkpmkO1EXggtxKyL1AQpapdZV6b87rWB2l3vuSQ+f2xkqymyi...

Parsed Result:

{
  "uid": 374958,
  "channel": "ADL_PRICE",
  "l": [
    {
      "mr": 0.0083629621201431,
      "lt": 85718.4,
      "ha": 0.0718829844033338,
      "al": 2,
      "id": 2833456,
      "so": 85709.3,
      "tp": 85717.0183,
      "bo": 85709.2,
      "rp": 85405.8479
    }
  ]
}

Message Field Descriptions

1. Position & Account Updates

{
  "channel": "ACCOUNT_UPDATE",
  "uid": 1001,
  "t": "1564745798938",
  "d": {
    "et": "CREATE",
    "a": [
      {
        "c": "USDT",
        "an": "122624.12345678",
        "la": "100.12345678",
        "pn": "50.12345678"
      },
      {
        "c": "BTC",
        "an": "122624.12345678",
        "la": "100.12345678",
        "pn": "50.12345678"
      }
    ],
    "p": {
      "id": 90762,
      "cid": 127,
      "pt": 1,
      "cn": "S-BTC-USDT",
      "con": "BTCUSDT-EXUSD",
      "l": 20,
      "pv": 12,
      "op": 98533.6,
      "rp": 68000.3,
      "hm": 98.22,
      "ra": 2,
      "s": "BUY",
      "mr": 0.0847,
      "oa": 0.0847,
      "ccv": 2
    }
  }
}

2. ADL Price Push (every second if the user holds the position)

{
  "channel": "ADL_PRICE",
  "uid": 1001,
  "l": [
    {
      "id": 7001,
      "al": 1,
      "rp": 68000.3,
      "ha": 98.22,
      "mr": 0.0847,
      "bo": 79000,
      "so": 78000,
      "lt": 78500,
      "tp": 78000
    },
    {
      "id": 7002,
      "al": 1,
      "rp": 68000.3,
      "ha": 98.22,
      "mr": 0.0847,
      "bo": 79000,
      "so": 78000,
      "lt": 78500,
      "tp": 78000
    }
  ]
}

3. System Shutdown

{
  "channel": "SYSTEM",
  "uid": 1001,
  "et": "close"
}

4. Regular Order Updates

{
  "channel": "order",
  "order": {
    "orderId": "2094043912705377045",
    "contractId": 127,
    "contractName": "E-BTC-USDT",
    "symbol": "BTC-USDT",
    "contractSide": "xxx",
    "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"
  }
}

5. Trigger Order Updates

{
  "channel": "trigOrder",
  "trigOrder": {
    "triggerOrderId": "1322738336974712854",
    "type": 1,
    "side": "buy",
    "triggerPrice": 61001,
    "price": 61003,
    "volume": 10,
    "triggerType": 3,
    "ctime": 1709550135000,
    "expireTime": 1710759735000,
    "orderAction": "1"
  }
}

Heartbeat

• Send every 30 seconds:

{ "ping": 1713338308232 }

• Server response:

{ "pong": 1713338308233 }

• If no ping is received in 40 seconds, the server will disconnect.