# 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

```json
{
  "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

```json
{
  "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](https://www.bejson.com/encrypt/gzip/#google_vignette)

#### Example (Base64 Encoded):

```
H4sIAAAAAAAAAD2NywrCQAxF/yXrYchMkpmkO1EXggtxKyL1AQpapdZV6b87rWB2l3vuSQ+f2xkqymyi...
```

#### Parsed Result:

```json
{
  "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

```json
{
  "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)

```json
{
  "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

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

#### 4. Regular Order Updates

```json
{
  "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

```json
{
  "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**:

```json
{ "ping": 1713338308232 }
```

* **Server response**:

```json
{ "pong": 1713338308233 }
```

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coinlocally.com/websocket/futures.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.