Events Stream

Room ID: polymarket_events_stream
Endpoint: wss://api.struct.to/ws
Rate: 0.025 credits per message

Low-latency push feed of PolymarketEvent rows — same shape that GET /polymarket/events returns. The server maintains an in-memory cache of open events only, refreshed via a slow full poll plus a fast 500ms newest-first poll, and merged live from the prediction_event_metrics and prediction_trades Kafka streams with per-timeframe block/timestamp ordering. No initial snapshot is pushed on subscribe. Clients seed local state from GET /polymarket/events and then apply deltas from this stream.

Related guide: Building a live trending feed seeds from the events list and pushes deltas through this stream.

Subscription model

Each client has up to 8 active slots per room (4 cadences × 2 modes). Re-subscribing to the same (interval_ms, mode) pair replaces the previous subscription. Unsubscribe one slot with action: "unsubscribe" plus interval_ms and mode, or clear everything with action: "unsubscribe_all".

Cadence (interval_ms): 500, 1000, 3000, or 10000. Each cadence is a separate flush bucket.
Filter mode: evaluated in-memory on every flush against rows that actually changed since the last tick. Same validation as the REST list endpoint.
Ids mode: filter by explicit event_slugs and/or event_ids. Max 500 ids per subscription.

Updates fire only when a cache row is dirtied by (a) a fresh Kafka metric snapshot with latest_block >= cached, (b) a confirmed trade with block >= cached, (c) a slow-poll field diff, or (d) the fast newest-first poll discovering a brand-new event. Quiet events produce zero messages.

Message fields

Field	Type	Required	Description
`action`	`"subscribe" \| "unsubscribe" \| "unsubscribe_all"`	Yes	Slot lifecycle action.
`interval_ms`	`500 \| 1000 \| 3000 \| 10000`	For subscribe / unsubscribe	Flush cadence. Defaults to `1000` if omitted.
`mode`	`"filter" \| "ids"`	No	Subscription mode. Defaults to `filter`.
`filter`	`EventsStreamFilter`	`mode=filter` only	Filter body; all fields optional.
`event_slugs`	`string[]`	`mode=ids` only	Event slugs to watch.
`event_ids`	`string[]`	`mode=ids` only	Event ids to watch.

Filter fields (`mode=filter`)

search is a case-insensitive substring match on title (3–100 chars). All other fields follow the same validation as the REST list endpoint (timeframe, list size caps).

Example — filter mode

{
  "type": "join_room",
  "payload": {
    "room_id": "polymarket_events_stream"
  }
}

{
  "type": "room_message",
  "payload": {
    "room_id": "polymarket_events_stream",
    "message": {
      "action": "subscribe",
      "interval_ms": 1000,
      "mode": "filter",
      "filter": {
        "search": "election",
        "timeframe": "24h",
        "min_volume": 10000
      }
    }
  }
}

Example — ids mode

{
  "type": "room_message",
  "payload": {
    "room_id": "polymarket_events_stream",
    "message": {
      "action": "subscribe",
      "interval_ms": 500,
      "mode": "ids",
      "event_slugs": ["us-election-2028"],
      "event_ids": ["12345"]
    }
  }
}

Unsubscribe one slot

{
  "type": "room_message",
  "payload": {
    "room_id": "polymarket_events_stream",
    "message": {
      "action": "unsubscribe",
      "interval_ms": 500,
      "mode": "ids"
    }
  }
}

Response

{
  "type": "events_stream_subscribe_response",
  "room_id": "polymarket_events_stream",
  "data": {
    "mode": "ids",
    "interval_ms": 500,
    "event_slugs": ["us-election-2028"],
    "rejected": [],
    "error": null
  }
}

Events

`events_stream_update`

Server-pushed event fired only for rows that changed AND matched this subscription since the last flush tick. data contains full PolymarketEvent rows — not deltas — so clients should merge by id.

Envelope

Field	Type	Description
`type`	`"events_stream_update"`	Envelope discriminator.
`room_id`	`"polymarket_events_stream"`	Room identifier.
`mode`	`"filter" \| "ids"`	The mode this subscription was created with.
`interval_ms`	`500 \| 1000 \| 3000 \| 10000`	The cadence slot this event is flushed under.
`data`	`PolymarketEvent[]`	Full event rows, same shape as `GET /polymarket/events`.

`PolymarketEvent`

Field	Type	Description
`id`	`string`	Event ID.
`event_slug`	`string \| null`	URL-safe event slug.
`title`	`string \| null`	Human-readable title.
`ticker`	`string \| null`	Short ticker, when present.
`description`	`string \| null`	Long description.
`resolution_source`	`string \| null`	Resolution source URL.
`category`	`string \| null`	Primary category label.
`image_url`	`string \| null`	CDN image URL.
`market_count`	`integer`	Number of child markets.
`created_time`	`integer \| null`	Unix seconds.
`closed_time`	`integer \| null`	Unix seconds.
`start_time`	`integer \| null`	Unix seconds.
`end_time`	`integer \| null`	Unix seconds.
`neg_risk`	`boolean`	Whether this event uses the neg-risk market.
`neg_risk_market_id`	`string \| null`	Neg-risk market ID, when applicable.
`game_status`	`string \| null`	Sports-event game status.
`show_market_images`	`boolean`	Whether child market images should be shown.
`status`	`string \| null`	`"open"` or `"closed"`.
`metrics`	`Record<Timeframe, SimpleTimeframeMetrics>`	Keyed by timeframe (`1m`, `5m`, `30m`, `1h`, `6h`, `24h`, `7d`, `30d`).
`tags`	`PolymarketTag[]`	Event tags.
`markets`	`EventMarket[]`	Child markets with enriched outcomes.
`series`	`PolymarketSeries \| null`	Parent series, when present.

`SimpleTimeframeMetrics`

Field	Type	Description
`volume`	`number`	USD volume within the window.
`fees`	`number`	USD fees within the window.
`txns`	`integer`	Trade count within the window.
`unique_traders`	`integer`	Unique wallet count within the window.

`PolymarketTag`

Field	Type	Description
`id`	`string`	Tag ID.
`label`	`string`	Display label.
`slug`	`string \| null`	URL-safe slug.

`EventMarket`

Field	Type	Description
`condition_id`	`string`	0x-prefixed condition ID.
`id`	`string \| null`	Market ID.
`title`	`string \| null`	Market title.
`question`	`string`	Market question.
`market_slug`	`string`	URL-safe market slug.
`status`	`string`	Market status.
`created_time`	`integer \| null`	Unix seconds.
`end_time`	`integer \| null`	Unix seconds.
`volume`	`number \| null`	Lifetime USD volume.
`liquidity_usd`	`number \| null`	Current USD liquidity.
`volume_24hr`	`number \| null`	24h USD volume.
`image_url`	`string \| null`	CDN image URL.
`market_maker_address`	`string \| null`	Market maker contract.
`creator`	`string \| null`	Wallet address of creator.
`category`	`string \| null`	Category label.
`accepting_orders`	`boolean \| null`	Whether CLOB is accepting new orders.
`uma_resolution_status`	`string \| null`	UMA oracle resolution status.
`clob_rewards`	`ClobReward[]`	Active reward configs.
`outcomes`	`EventMarketOutcome[]`	Market outcomes.
`winning_outcome`	`EventMarketOutcome \| null`	Resolved winning outcome, when applicable.

`EventMarketOutcome`

Field	Type	Description
`name`	`string`	Outcome label (e.g. `"Yes"`).
`price`	`number \| null`	Latest price (0 – 1).
`position_id`	`string \| null`	ERC-1155 outcome token ID (decimal string).
`outcome_index`	`integer \| null`	0-indexed outcome position.

`PolymarketSeries`

Field	Type	Description
`id`	`string`	Series ID.
`slug`	`string \| null`	URL-safe slug.
`ticker`	`string \| null`	Ticker, when present.
`title`	`string \| null`	Display title.
`description`	`string \| null`	Long description.
`series_type`	`string \| null`	Series type discriminator.
`recurrence`	`string \| null`	Recurrence cadence (e.g. `"daily"`).
`layout`	`string \| null`	UI layout hint.
`image_url`	`string \| null`	CDN image URL.
`icon_url`	`string \| null`	CDN icon URL.
`active`	`boolean`	Whether the series is currently active.
`closed`	`boolean`	Whether the series is closed.
`archived`	`boolean`	Whether archived.
`featured`	`boolean`	Whether featured in discovery surfaces.
`restricted`	`boolean`	Whether the series is region-restricted.
`pyth_token_id`	`string \| null`	Pyth price feed ID, when applicable.
`cg_asset_name`	`string \| null`	CoinGecko asset name, when applicable.
`start_date`	`integer \| null`	Unix seconds.
`event_count`	`integer`	Number of child events.

See the Markets Stream room for the ClobReward shape — it is shared across both stream rooms.

Example

{
  "type": "events_stream_update",
  "room_id": "polymarket_events_stream",
  "mode": "ids",
  "interval_ms": 500,
  "data": [
    {
      "id": "12345",
      "event_slug": "us-election-2028",
      "title": "US Presidential Election 2028",
      "ticker": "PRES28",
      "description": "Who will win the 2028 US presidential election?",
      "resolution_source": "https://example.com/resolution",
      "category": "politics",
      "image_url": "https://cdn.struct.to/events/us-election-2028.png",
      "market_count": 8,
      "created_time": 1743400000,
      "closed_time": null,
      "start_time": 1743500000,
      "end_time": 1893456000,
      "neg_risk": true,
      "neg_risk_market_id": "0xneg...",
      "game_status": null,
      "show_market_images": true,
      "status": "open",
      "metrics": {
        "24h": { "volume": 125000.5, "fees": 250.0, "txns": 340, "unique_traders": 85 },
        "7d": { "volume": 810000.0, "fees": 1620.0, "txns": 2210, "unique_traders": 540 }
      },
      "tags": [{ "id": "42", "label": "Politics", "slug": "politics" }],
      "markets": [
        {
          "condition_id": "0xabc123...",
          "id": "m_1",
          "title": "Candidate A wins",
          "question": "Will Candidate A win the 2028 election?",
          "market_slug": "candidate-a-wins-2028",
          "status": "open",
          "created_time": 1743400000,
          "end_time": 1893456000,
          "volume": 42000.0,
          "liquidity_usd": 15000.0,
          "volume_24hr": 3200.0,
          "image_url": "https://cdn.struct.to/markets/candidate-a.png",
          "market_maker_address": "0xmm...",
          "creator": "0xcreator...",
          "category": "politics",
          "accepting_orders": true,
          "uma_resolution_status": null,
          "clob_rewards": [],
          "outcomes": [
            { "name": "Yes", "price": 0.42, "position_id": "12345678901234567", "outcome_index": 0 },
            { "name": "No",  "price": 0.58, "position_id": "98765432109876543", "outcome_index": 1 }
          ],
          "winning_outcome": null
        }
      ],
      "series": null
    }
  ]
}

Introduction

Rooms

Alerts

Subscription model

Message fields

Filter fields (`mode=filter`)

Example — filter mode

Example — ids mode

Unsubscribe one slot

Response

Events

`events_stream_update`

Envelope

`PolymarketEvent`

`SimpleTimeframeMetrics`

`PolymarketTag`

`EventMarket`

`EventMarketOutcome`

`PolymarketSeries`

Example

​Subscription model

​Subscribe

​Message fields

​Filter fields (mode=filter)

​Example — filter mode

​Example — ids mode

​Unsubscribe one slot

​Response

​Events

​events_stream_update

​Envelope

​PolymarketEvent

​SimpleTimeframeMetrics

​PolymarketTag

​EventMarket

​EventMarketOutcome

​PolymarketSeries

​Example

Subscription model

Subscribe

Message fields

Filter fields (`mode=filter`)

Example — filter mode

Example — ids mode

Unsubscribe one slot

Response

Events

`events_stream_update`

Envelope

`PolymarketEvent`

`SimpleTimeframeMetrics`

`PolymarketTag`

`EventMarket`

`EventMarketOutcome`

`PolymarketSeries`

Example