# Receive real-time market data

**SUBSCRIBE /market-data**

Real-time market data stream with dynamic topic subscription (order book snapshots/diffs, trades).

Subscription Model (no query parameters):
  - Connection starts with zero markets subscribed
  - Client sends a subscribe frame (MDClientSubscribe) listing market_id values
  - Server replies with exactly one MDBookSnapshot per NEW market, then streams MDBookDiff / MDTrade
  - Client may send unsubscribe (MDClientUnsubscribe) to stop updates for specific markets
  - Repeated subscription for already active market without force_snapshot is idempotent (no extra snapshot)

Ordering / Monotonicity:
  - md_seq is dense and strictly increasing per market_id ONLY on data frames (book_snapshot, book_diff, trade)
  - heartbeat does not advance md_seq
  - Gaps in md_seq per market indicate operational incident; client SHOULD resync (fresh snapshot + re-subscribe)

Initial Snapshots:
  - Snapshot sent only upon successful subscription (or re-subscription with force_snapshot=true)

Snapshots Cadence:
  - Periodic server-initiated book_snapshot frames limit diff chain length
  - Clients MUST apply snapshot then contiguous diffs/trades with md_seq = snapshot.md_seq+1 … without gaps


## Messages

### Order Book Snapshot

Full order book snapshot for a market

#### Payload

- **type** (string)

- **market_id** (string)

- **md_seq** (integer(int64))

- **ts_ns** (integer(int64))

- **bids** (array[object])

- **asks** (array[object])





### Order Book Diff

Incremental order book update (delta)

#### Payload

- **type** (string)

- **market_id** (string)

- **md_seq** (integer(int64))

- **ts_ns** (integer(int64))

- **bids** (array[object])
  Price level deltas (upsert or delete if qty=0)

- **asks** (array[object])
  Price level deltas (upsert or delete if qty=0)





### Trade Event

Trade execution notification

#### Payload

- **type** (string)

- **market_id** (string)

- **md_seq** (integer(int64))

- **ts_ns** (integer(int64))

- **trade_id** (string)

- **price** (object)

- **qty** (object)

- **taker_side** (string)





### Market Data Heartbeat

Keep-alive heartbeat (does not advance md_seq)

#### Payload

- **type** (string)

- **ts_ns** (integer(int64))

- **market_id** (string | null)
  Optional; may be omitted for aggregated heartbeat across all subscribed markets

- **md_seq** (integer(int64) | null)
  Repeats last data md_seq for the specific market if market_id present; absent for aggregated heartbeat





### Market Data Error

Market data stream error notification

#### Payload

- **type** (string)

- **ts_ns** (integer(int64))

- **payload** (object)






## Bindings
#### Operation WebSockets-specific information

- **headers** (object)