Envelope

Every event delivered on /v1/ws shares the same outer envelope. Routing is done on (entity, event); service-specific payload lives in data.

Shape

{
  "schema": "ws.user.v1",
  "entity": "orders",
  "event": "state",
  "occurred_at": "2026-04-09T14:00:00.000Z",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "firm_id": "660e8400-e29b-41d4-a716-446655440001",
  "source_subject": "orders.state.events",
  "source_service": "orders",
  "data": { }
}

Field	Description
`schema`	Always `ws.user.v1`. Use this to discriminate live envelopes from control replies (`pong`, news acks).
`entity`	Domain bucket: `accounts`, `orders`, `fills`, `positions`, `trades`, `balances`, `stats`.
`event`	Event suffix inside the entity (e.g. `state`, `persisted`, `updated`).
`occurred_at`	Publisher timestamp, RFC3339 with nanoseconds.
`user_id`	The authenticated user. Always present.
`account_id`	Account the event belongs to. Always present for trading entities; may be empty for user-level account meta events.
`firm_id`	Firm that owns the account.
`source_subject`	Internal NATS subject — useful when filing support tickets.
`source_service`	Tradara service that emitted the event (`orders`, `fills`, `trades`, `balances`, …).
`data`	Service-defined payload. Field shapes mirror the matching REST response — see each row in the event catalog for the link.

Routing on the client

The canonical key for a router is {entity}.{event}:

function route(env) {
  if (env.schema !== "ws.user.v1") return; // ignore control / news frames
  const key = `${env.entity}.${env.event}`;
  switch (key) {
    case "orders.state":     return applyOrderState(env);
    case "orders.ack":       return applyOrderAck(env);
    case "fills.persisted":  return applyFill(env);
    case "positions.updated":return applyPosition(env);
    case "balances.updated": return applyBalance(env);
    // …
  }
}

Sequencing

A monotonically increasing sequence number may be present on the inner data payload (sequence, seq, or offset depending on service). Clients that need exactly-once application semantics should treat any of these as authoritative for the (account_id, entity) pair they appear on, and ignore older sequences after a re-hydration. For most clients, applying envelopes in arrival order on top of REST-hydrated state is sufficient.

Overview

Orders

Fills

Positions

Trades

Balances

Realtime WebSocket

Shape

Routing on the client

Sequencing

​Shape

​Routing on the client

​Sequencing

Shape

Routing on the client

Sequencing