Websocket Reference

Tread exposes WebSocket endpoints for real-time order updates and market data. All endpoints use the wss:// scheme in production.

Endpoints

Endpoint	Purpose	Authentication
wss://<server>/ws/orders/	User order updates	Required
wss://<server>/ws/prices/	Pair prices & order books	Not required

---

/ws/orders/ — Order Stream

Streams real-time updates for the authenticated user's orders, including standalone orders, multi-orders (TWAP, market maker, etc.), chained orders, and batch orders. Also surfaces orders the user can view via trading-group permissions.

Authentication

Two methods are supported. Pick one:

1. Query parameter (recommended for API clients)

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

If a token is provided but invalid, the server closes the connection with code 4001.

2. Post-connect message

Connect without credentials, then send:

{ "command": "authenticate", "token": "<DRF_token_or_JWT>" }

Both DRF tokens and JWT tokens (when EXTERNAL_JWT is enabled) are accepted.

On success:

{ "type": "authenticated", "user_id": "<id>" }

On failure the server replies with an error message and closes with code 4001. Unauthenticated connections cannot send any command other than authenticate and will be closed by the inactivity timer (~30s).

Client → Server commands

Subscribe

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

The user ID is taken from the authenticated session; no user ID is required in the message.

Immediately after subscribing, the server sends a one-time order_snapshot message containing all currently active orders (see below).

Unsubscribe

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

Keep-alive

{ "command": "keep_alive" }

Must be sent within the inactivity window (~30 seconds) to keep the subscription alive. The server replies with:

{ "type": "keep_alive" }

Server → Client messages

order_snapshot

Sent once, right after a successful subscribe. Contains the full set of currently active orders, partitioned by type:

{
  "type": "order_snapshot",
  "data": {
    "orders": [ /* standalone orders */ ],
    "multi_orders": [ /* multi-orders with child orders */ ],
    "chained_orders": [ /* chained orders with children */ ],
    "batch_orders": [ /* batch orders with children */ ]
  }
}

order_update

Sent whenever an order changes state or receives a fill. Shape varies by order type.

Standalone single order:

{
  "type": "order_update",
  "data": {
    "order_id": "<id>",
    "update_type": "order_created" | "order_activated" | "order_canceled" | "order_completed" | "order_fill_received" | "order_paused",
    "order": { /* order detail */ }
  }
}

Multi-order (parent-level event):

{
  "type": "order_update",
  "data": {
    "order_id": "<multi_order_id>",
    "update_type": "order_created" | "order_activated" | "order_canceled" | "order_completed" | "order_paused",
    "order": { /* multi-order detail with child orders */ }
  }
}

Multi-order (child event bubbled up to parent):

{
  "type": "order_update",
  "data": {
    "order_id": "<multi_order_id>",
    "update_type": "child_order_created" | "child_order_activated" | "child_order_canceled" | "child_order_completed" | "child_order_fill_received",
    "child_order_ids": ["<id>", "..."],
    "order": { /* multi-order detail with child orders */ }
  }
}

Chained order (child event):

{
  "type": "order_update",
  "data": {
    "order_id": "<chained_order_id>",
    "update_type": "child_order_*",
    "order_type": "chained_order",
    "child_order_ids": ["<id>", "..."],
    "order": { /* chained-order detail */ }
  }
}

Batch order (child event):

{
  "type": "order_update",
  "data": {
    "order_id": "<batch_order_id>",
    "update_type": "child_order_*",
    "order_type": "batch_order",
    "child_order_ids": ["<id>", "..."],
    "order": { /* batch-order detail */ }
  }
}

Notes:

• Fill broadcasts (order_fill_received / child_order_fill_received) are debounced server-side: rapid fills for the same order produce at most one broadcast per ~1 second.

• Status-change events (created, activated, canceled, completed, paused) are sent immediately.

order_error

Sent when an order encounters a runtime error (e.g., exchange rejection). Same envelope as order_update:

{ "type": "order_error", "data": { /* error detail */ } }

error

Protocol-level errors:

{ "type": "error", "error": "not_authenticated", "message": "Please authenticate first using the 'authenticate' command" }

{ "type": "error", "error": "authentication_failed", "message": "<reason>" }

After an authentication_failed error the server closes with code 4001.

Close codes

Code	Meaning
1000	Normal closure
1011	Internal server error
4001	Authentication failure (custom)
4002	Inactivity timeout (custom)

---

/ws/prices/ — Price & Order Book Stream

Streams live pair prices and order book snapshots from supported exchanges. No authentication required.

Inactivity

The server requires a keep_alive message every ~10 seconds; otherwise the connection is closed.

{ "command": "keep_alive" }

Client → Server commands

Subscribe to a pair price

{
  "command": "subscribe",
  "data_type": "pair_price",
  "exchange": "<exchange_name>",
  "pair": "<pair_name>"
}

Only one pair_price subscription is active at a time per connection. Subscribing again replaces the previous subscription.

Subscribe to an order book

{
  "command": "subscribe",
  "data_type": "order_book",
  "exchanges": ["<exchange1>", "<exchange2>"],
  "pair": "<pair_name>"
}

Note exchanges (plural, array) — you can subscribe to the same pair across multiple exchanges in one command.

Unsubscribe

Same shape as subscribe but with "command": "unsubscribe".

Server → Client messages

price_update

Sent on every price change, and once immediately after subscribing (initial snapshot).

{ "type": "price_update", "price": "<decimal_string>" }

order_book_update

{
  "type": "order_book_update",
  "exchange": "<exchange_name>",
  "book": { /* chart-formatted order book */ }
}

An initial snapshot is sent per-exchange right after subscribing, followed by live updates.

Close codes

Code	Meaning
1000	Normal closure
1011	Internal server error
5000	Inactivity timeout (custom)

---