# Websocket Reference

The *Order Status WebSocket* allows you to receive real-time updates about your single/multi orders directly into your application or script. You can subscribe using your API access token and get instant notifications when an order event occurs.

`wss://<server>/ws/orders/`

### Authentication

Pass your API token as a query parameter in the WebSocket URL. *If authentication fails, the connection will be automatically closed*.

```
wss://<server>/ws/orders/?token=<API_token>
```

### Subscribing to Order Updates

After connecting, you must send a subscription message to start receiving updates.

#### **Subscribe**

```json
{
  "command": "subscribe",
  "data_type": "user_orders"
}
```

**Keep-Alive**

*To prevent disconnects (after 30s inactivity), send this message every 5–10 seconds:*

```json
{
  "command": "keep_alive"
}
```

**Unsubscribe (optional)**

```json
{
  "command": "unsubscribe",
  "data_type": "user_orders"
}
```

### Order Updates

```json
{
  "type": "order_update",
  "data": {
    "order_id": "<order_id>",
    "update_type": "<event_type>",
    "order": { /* order details */ }
  }
}
```

After successfully subscribing, you will receive `order_update` messages with an `update_type` field for your orders. The possible values depend on whether the update is for a single order or a multi-order (parent/child).

#### Single Orders Update Types

* `order_created` — The order was created.
* `order_activated` — The order became active.
* `order_canceled` — The order was canceled.
* `order_completed` — The order was fully completed.
* `order_fill_received` — The order received a fill (partial or full execution).
* `order_paused` — The order was paused.

#### Multi-Orders Update Types

* `order_created` — The parent order was created.
* `order_activated` — The parent order became active.
* `order_canceled` — The parent order was canceled.
* `order_completed` — The parent order was completed (all child orders finished).
* `order_paused` — The parent order was paused.
* `child_order_created` — A child order was created.
* `child_order_activated` — A child order became active.
* `child_order_canceled` — A child order was canceled.
* `child_order_completed` — A child order was completed.
* `child_order_fill_received` — A child order received a fill.

### Example Update

#### Single Orders

{% code lineNumbers="true" %}

```json
{
  "type": "order_update",
  "data": {
    "order_id": "0c31d512-f2c8-4600-9002-493bada22b39",
    "update_type": "order_fill_received",
    "order": {
      "id": "0c31d512-f2c8-4600-9002-493bada22b39",
      "custom_order_id": "",
      "parent_order_id": null,
      "notes": "",
      "pair": "BTC:PERP-USDT",
      "side": "buy",
      "exchanges": [
        "Bybit"
      ],
      "buy_token": "BTC:PERP",
      "buy_token_amount": "1",
      "sell_token": "USDT",
      "sell_token_amount": "118841.3044",
      "executed_qty": "9388.5216",
      "executed_buy_qty": "0.079",
      "average_executed_price": "118842.0455696411",
      "executed_notional": "9388.5216",
      "target_order_qty": "1",
      "target_remaining_qty": "0.921",
      "target_token": "BTC:PERP",
      "target_executed_qty": "0.079",
      "pct_filled": "7.9",
      "total_fee": "3.37511478",
      "strategy": "VWAP",
      "super_strategy": "Impact Minimization",
      "duration": 120,
      "accounts": [
        "f574fe0f-f188-47d0-a348-9ea8fefb9d37"
      ],
      "account_names": [
        "test_bybit"
      ],
      "engine_passiveness": "0.02",
      "schedule_discretion": "0.06",
      "pov_limit": null,
      "pov_target": null,
      "alpha_tilt": "0",
      "strategy_params": {
        "ool_pause": false,
        "max_clip_size": null
      },
      "user": "2",
      "status": "ACTIVE",
      "active": true,
      "is_simple": false,
      "failure_reason": "",
      "limit_price": "",
      "is_reverse_limit_price": false,
      "time_start": "2025-07-15T01:21:45.448162+00:00",
      "time_end": "2025-07-15T01:23:45.448162+00:00",
      "created_at": "2025-07-15T01:21:45.481837+00:00",
      "updated_at": "2025-07-15T01:21:45.499214+00:00"
    }
  }
}
```

{% endcode %}

#### Multi-Orders&#x20;

{% code lineNumbers="true" %}

```json
{
  "type": "order_update",
  "data": {
    "order_id": "5092dba5-ec3c-4ae9-84ad-43aa29090bb0",
    "update_type": "order_activated",
    "order": {
      "id": "5092dba5-ec3c-4ae9-84ad-43aa29090bb0",
      "created_at": "2025-07-15T01:23:07.588678+00:00",
      "updated_at": "2025-07-15T01:23:07.588700+00:00",
      "time_start": "2025-07-15T01:23:07.567613+00:00",
      "duration": 60,
      "exposure_tolerance": "0.1",
      "notional_exposure": "0.462",
      "executed_notional": "14255.514",
      "child_order_ids": [
        "4c1b8f6b-a204-43f6-aac9-4ed06198fe27",
        "f0a78f07-f52c-4a7f-aa32-5b80fa0ff78e"
      ],
      "accounts": [
        "test_bybit"
      ],
      "strategy": "TWAP",
      "strategy_params": {
        "max_clip_size": 10000
      },
      "engine_passiveness": "0.02",
      "schedule_discretion": "0.06",
      "alpha_tilt": "0",
      "limit_price_spread": null,
      "failure_reason": "",
      "pct_filled": "6",
      "account_names": [
        "test_bybit"
      ],
      "pairs": "BTC:PERP-USDT,BTC-USDT",
      "status": "ACTIVE",
      "is_active": true,
      "is_paused": false,
      "fee_notional": "8.5531236",
      "order_condition": "",
      "child_orders": [
        {
          "id": "4c1b8f6b-a204-43f6-aac9-4ed06198fe27",
          "custom_order_id": "",
          "parent_order_id": "5092dba5-ec3c-4ae9-84ad-43aa29090bb0",
          "notes": "",
          "pair": "BTC:PERP-USDT",
          "side": "buy",
          "exchanges": [
            "Bybit"
          ],
          "buy_token": "BTC:PERP",
          "buy_token_amount": "1",
          "sell_token": "USDT",
          "sell_token_amount": "118799.9",
          "executed_qty": "7127.988",
          "executed_buy_qty": "0.06",
          "average_executed_price": "118799.8",
          "executed_notional": "7127.988",
          "target_order_qty": "1",
          "target_remaining_qty": "0.94",
          "target_token": "BTC:PERP",
          "target_executed_qty": "0.06",
          "pct_filled": "6",
          "total_fee": "1.4255976",
          "strategy": "TWAP",
          "super_strategy": null,
          "duration": 73,
          "accounts": [
            "f574fe0f-f188-47d0-a348-9ea8fefb9d37"
          ],
          "account_names": [
            "test_bybit"
          ],
          "engine_passiveness": "0.02",
          "schedule_discretion": "0.06",
          "pov_limit": null,
          "pov_target": null,
          "alpha_tilt": "0",
          "strategy_params": {
            "max_clip_size": 10000
          },
          "user": "2",
          "status": "ACTIVE",
          "active": true,
          "is_simple": false,
          "failure_reason": "",
          "limit_price": "",
          "is_reverse_limit_price": false,
          "time_start": "2025-07-15T01:23:07.639390+00:00",
          "time_end": "2025-07-15T01:24:20.639390+00:00",
          "created_at": "2025-07-15T01:23:07.722411+00:00",
          "updated_at": "2025-07-15T01:23:07.725840+00:00"
        },
        {
          "id": "f0a78f07-f52c-4a7f-aa32-5b80fa0ff78e",
          "custom_order_id": "",
          "parent_order_id": "5092dba5-ec3c-4ae9-84ad-43aa29090bb0",
          "notes": "",
          "pair": "BTC-USDT",
          "side": "sell",
          "exchanges": [
            "Bybit"
          ],
          "buy_token": "USDT",
          "buy_token_amount": null,
          "sell_token": "BTC",
          "sell_token_amount": "1",
          "executed_qty": "0.06",
          "executed_buy_qty": "7127.526",
          "average_executed_price": "118792.1",
          "executed_notional": "7127.526",
          "target_order_qty": "1",
          "target_remaining_qty": "0.94",
          "target_token": "BTC",
          "target_executed_qty": "0.06",
          "pct_filled": "6",
          "total_fee": "7.127526",
          "strategy": "TWAP",
          "super_strategy": null,
          "duration": 73,
          "accounts": [
            "f574fe0f-f188-47d0-a348-9ea8fefb9d37"
          ],
          "account_names": [
            "test_bybit"
          ],
          "engine_passiveness": "0.02",
          "schedule_discretion": "0.06",
          "pov_limit": null,
          "pov_target": null,
          "alpha_tilt": "0",
          "strategy_params": {
            "max_clip_size": 10000
          },
          "user": "2",
          "status": "ACTIVE",
          "active": true,
          "is_simple": false,
          "failure_reason": "",
          "limit_price": "",
          "is_reverse_limit_price": false,
          "time_start": "2025-07-15T01:23:07.643916+00:00",
          "time_end": "2025-07-15T01:24:20.643916+00:00",
          "created_at": "2025-07-15T01:23:07.914559+00:00",
          "updated_at": "2025-07-15T01:23:07.916364+00:00"
        }
      ]
    }
  }
}
```

{% endcode %}

{% code lineNumbers="true" %}

```json
{
  "type": "order_update",
  "data": {
    "order_id": "5092dba5-ec3c-4ae9-84ad-43aa29090bb0",
    "update_type": "child_order_fill_received",
    "order": {
      "id": "5092dba5-ec3c-4ae9-84ad-43aa29090bb0",
      "created_at": "2025-07-15T01:23:07.588678+00:00",
      "updated_at": "2025-07-15T01:23:07.588700+00:00",
      "time_start": "2025-07-15T01:23:07.567613+00:00",
      "duration": 60,
      "exposure_tolerance": "0.1",
      "notional_exposure": "-7523.5824552",
      "executed_notional": "21779.5584552",
      "child_order_ids": [
        "4c1b8f6b-a204-43f6-aac9-4ed06198fe27",
        "f0a78f07-f52c-4a7f-aa32-5b80fa0ff78e"
      ],
      "accounts": [
        "test_bybit"
      ],
      "strategy": "TWAP",
      "strategy_params": {
        "max_clip_size": 10000
      },
      "engine_passiveness": "0.02",
      "schedule_discretion": "0.06",
      "alpha_tilt": "0",
      "limit_price_spread": null,
      "failure_reason": "",
      "pct_filled": "9.1668",
      "account_names": [
        "test_bybit"
      ],
      "pairs": "BTC:PERP-USDT,BTC-USDT",
      "status": "ACTIVE",
      "is_active": true,
      "is_paused": false,
      "fee_notional": "16.0771680552",
      "order_condition": "",
      "child_orders": [
        {
          "id": "4c1b8f6b-a204-43f6-aac9-4ed06198fe27",
          "custom_order_id": "",
          "parent_order_id": "5092dba5-ec3c-4ae9-84ad-43aa29090bb0",
          "notes": "",
          "pair": "BTC:PERP-USDT",
          "side": "buy",
          "exchanges": [
            "Bybit"
          ],
          "buy_token": "BTC:PERP",
          "buy_token_amount": "1",
          "sell_token": "USDT",
          "sell_token_amount": "118794.442",
          "executed_qty": "7127.988",
          "executed_buy_qty": "0.06",
          "average_executed_price": "118799.8",
          "executed_notional": "7127.988",
          "target_order_qty": "1",
          "target_remaining_qty": "0.94",
          "target_token": "BTC:PERP",
          "target_executed_qty": "0.06",
          "pct_filled": "6",
          "total_fee": "1.4255976",
          "strategy": "TWAP",
          "super_strategy": null,
          "duration": 73,
          "accounts": [
            "f574fe0f-f188-47d0-a348-9ea8fefb9d37"
          ],
          "account_names": [
            "test_bybit"
          ],
          "engine_passiveness": "0.02",
          "schedule_discretion": "0.06",
          "pov_limit": null,
          "pov_target": null,
          "alpha_tilt": "0",
          "strategy_params": {
            "max_clip_size": 10000
          },
          "user": "2",
          "status": "ACTIVE",
          "active": true,
          "is_simple": false,
          "failure_reason": "",
          "limit_price": "",
          "is_reverse_limit_price": false,
          "time_start": "2025-07-15T01:23:07.639390+00:00",
          "time_end": "2025-07-15T01:24:20.639390+00:00",
          "created_at": "2025-07-15T01:23:07.722411+00:00",
          "updated_at": "2025-07-15T01:23:07.725840+00:00"
        },
        {
          "id": "f0a78f07-f52c-4a7f-aa32-5b80fa0ff78e",
          "custom_order_id": "",
          "parent_order_id": "5092dba5-ec3c-4ae9-84ad-43aa29090bb0",
          "notes": "",
          "pair": "BTC-USDT",
          "side": "sell",
          "exchanges": [
            "Bybit"
          ],
          "buy_token": "USDT",
          "buy_token_amount": null,
          "sell_token": "BTC",
          "sell_token_amount": "1",
          "executed_qty": "0.123336",
          "executed_buy_qty": "14651.5704552",
          "average_executed_price": "118793.9486865149",
          "executed_notional": "14651.5704552",
          "target_order_qty": "1",
          "target_remaining_qty": "0.876664",
          "target_token": "BTC",
          "target_executed_qty": "0.123336",
          "pct_filled": "12.3336",
          "total_fee": "14.6515704552",
          "strategy": "TWAP",
          "super_strategy": null,
          "duration": 73,
          "accounts": [
            "f574fe0f-f188-47d0-a348-9ea8fefb9d37"
          ],
          "account_names": [
            "test_bybit"
          ],
          "engine_passiveness": "0.02",
          "schedule_discretion": "0.06",
          "pov_limit": null,
          "pov_target": null,
          "alpha_tilt": "0",
          "strategy_params": {
            "max_clip_size": 10000
          },
          "user": "2",
          "status": "ACTIVE",
          "active": true,
          "is_simple": false,
          "failure_reason": "",
          "limit_price": "",
          "is_reverse_limit_price": false,
          "time_start": "2025-07-15T01:23:07.643916+00:00",
          "time_end": "2025-07-15T01:24:20.643916+00:00",
          "created_at": "2025-07-15T01:23:07.914559+00:00",
          "updated_at": "2025-07-15T01:23:07.916364+00:00"
        }
      ]
    }
  }
}
```

{% endcode %}

### Troubleshooting

* **Connection closes immediately**
  * Check your API token and WebSocket URL.
* **No updates received**
  * Make sure you sent the subscription message after connecting.
* **Timeouts**
  * Ensure you are sending keep-alive messages regularly.

### Best Practices

* Send keep-alive messages to avoid disconnects.
* Subscribe after connecting; unsubscribe when done.
* Handle disconnection properly in your client.


---

# 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.tread.fi/interacting-with-the-api/websocket-reference.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.