# Receive real-time event/market lifecycle updates

**SUBSCRIBE /events**

Real-time lifecycle events stream for events and markets with resume capability.

Query Parameters:
  - since=<uint64>   Last applied seq for resume (optional; must be >0; absent or 0 → start from live tail)
  - event_id=<id>    Repeatable; filter by event_id (includes all markets of the event)
  - market_id=<id>   Repeatable; filter by market_id
  - lang=<code>      Repeatable; filter by language code (en, pt, id). Filters LocalizedText fields in payloads. If omitted, all available locales are included.

Resume Semantics:
  1. Client connects with since=S (last applied seq)
  2. Server replays frames with seq >= S in order
  3. Sends backlog_end (last_seq = current max)
  4. Continues live streaming
  If S > current max → immediate live (no backlog)
  If S too old (retention gap) → error frame (code=resume_too_old) then close (4009)

Idempotency / Ordering:
  - seq strictly monotonic; no gaps (gap ⇒ operational incident)
  - Client drops any frame with seq <= last_applied_seq
  - Expected next seq = last_applied_seq + 1 (else trigger reconnect + resume)

Event Types:
  - event.created: New event created with full definition
  - event.status_changed: Event status changed (only status fields)
  - event.settled: Event resolved (includes expiration_value and resolved_market_id; either may be null)
  - event.voided: Event cancelled (includes void_reason)
  - market.created: New market created with full definition
  - market.status_changed: Market status changed (only status fields)
  - market.details_changed: Market details changed (title, subtitles, floor_strike)
  - market.settled: Market resolved (includes result, settlement_price, expiration_value)
  - market.voided: Market cancelled

Market Details At Resolution:
  - market.details_changed can arrive on a closed market at resolution, with a new floor_strike
  - It always comes before market.settled and event.settled of the same event
  - expiration_value in those two events matches the new floor_strike, and can carry more decimals than usual

Heartbeats:
  - Sent when no lifecycle_update within configured interval
  - Heartbeat does NOT advance seq; only lifecycle_update frames advance seq
  - Heartbeat and backlog_end both repeat the last data seq

Flow Control:
  - Server may enforce max_pending_frames/bytes and close with code 4008 (flow_control)

Close Codes:
  1000 normal
  1001 going_away
  1011 internal_error
  4008 flow_control
  4009 resume_too_old / protocol_version
  4401 unauthorized


## Messages

### Event/Market Lifecycle Update Frame

Event or market lifecycle state change notification

#### Payload

- **type** (string)

- **seq** (integer(int64))
  Monotonic sequence for lifecycle events

- **ts_ns** (integer(int64))
  Timestamp in nanoseconds

- **event_id** (string | null)
  Event ID (if applicable)

- **market_id** (string | null)
  Market ID (if applicable)

- **event_type** (string)
  Lifecycle event type

- **payload** (object)





### Heartbeat Frame

Keep-alive heartbeat (does not advance seq)

#### Payload

- **type** (string)

- **seq** (integer(int64))
  Repeats last delivered data seq; heartbeat does not advance global seq

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

- **payload** (object)





### Backlog End Marker

Signals end of historical replay; live streaming begins

#### Payload

- **type** (string)

- **seq** (integer(int64))

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

- **payload** (object)





### Error Frame

Error notification before close

#### Payload

- **type** (string)

- **seq** (integer(int64))

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

- **payload** (object)






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

- **headers** (object)

- **query** (object)