Go to website

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

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

Keep-Alive

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

{
  "command": "keep_alive"
}

Unsubscribe (optional)

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

Order Updates

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

{
  "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"
    }
  }
}

Multi-Orders 

{
  "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"
        }
      ]
    }
  }
}
{
  "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"
        }
      ]
    }
  }
}

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.

PreviousType ReferenceNextExamples

Last updated

Was this helpful?