Markets Stream

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

Low-latency push feed of market rows — same shape GET /polymarket/market returns, including per-outcome price with latest_block + latest_confirmed_at watermarks. The server maintains an in-memory cache of open markets only, refreshed via a slow full poll plus a fast 500ms newest-first poll, and merged live from the prediction_condition_metrics and prediction_trades Kafka streams with per-timeframe block/timestamp ordering. No initial snapshot is pushed on subscribe. Clients seed from GET /polymarket/market and then apply deltas from 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.
Filter mode: same validation as the REST list endpoint (timeframe, search length, list caps). search is a case-insensitive substring match on title. No sort / limit — you get every matching row that changed.
Ids mode: any combination of condition_ids, market_slugs, and event_slugs (matches all child markets of those events). Max 500 ids total 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 market. Quiet markets produce zero messages. Each outcome in outcomes[] carries latest_block and latest_confirmed_at (Unix seconds) — the block/ts of the most recent price write from prediction_position_metrics. Consumers can use these to reject out-of-order price merges locally.

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`	`MarketsStreamFilter`	`mode=filter` only	Filter body; all fields optional.
`condition_ids`	`string[]`	`mode=ids` only	0x-prefixed lowercase 32-byte hex.
`market_slugs`	`string[]`	`mode=ids` only	Market slug strings.
`event_slugs`	`string[]`	`mode=ids` only	Event slugs — matches every child market of each event.

Filter fields (`mode=filter`)

Supports the same filters as the REST markets list: search, categories, exclude_categories, tags, exclude_tags, min_volume / max_volume, min_txns / max_txns, min_unique_traders / max_unique_traders, min_liquidity / max_liquidity, min_holders / max_holders, start_time / end_time, has_rewards, and timeframe (1m, 5m, 30m, 1h, 6h, 24h, 7d, 30d). status is not accepted — the cache only holds open markets.

Example — filter mode

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

{
  "type": "room_message",
  "payload": {
    "room_id": "polymarket_markets_stream",
    "message": {
      "action": "subscribe",
      "interval_ms": 1000,
      "mode": "filter",
      "filter": {
        "search": "bitcoin",
        "categories": ["crypto"],
        "min_volume": 50000,
        "timeframe": "24h",
        "has_rewards": true
      }
    }
  }
}

Example — ids mode

{
  "type": "room_message",
  "payload": {
    "room_id": "polymarket_markets_stream",
    "message": {
      "action": "subscribe",
      "interval_ms": 500,
      "mode": "ids",
      "condition_ids": ["0xabc123..."],
      "market_slugs": ["will-bitcoin-hit-100k"],
      "event_slugs": ["bitcoin-price-markets"]
    }
  }
}

Unsubscribe one slot

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

Response

{
  "type": "markets_stream_subscribe_response",
  "room_id": "polymarket_markets_stream",
  "data": {
    "mode": "ids",
    "interval_ms": 500,
    "condition_ids": ["0xabc123..."],
    "market_slugs": ["will-bitcoin-hit-100k"],
    "event_slugs": ["bitcoin-price-markets"],
    "rejected": [],
    "error": null
  }
}

Events

`markets_stream_update`

Server-pushed event fired only for rows that changed AND matched this subscription since the last flush tick. data contains full market rows — not deltas — so clients should merge by condition_id. Each outcome in data[i].outcomes carries latest_block + latest_confirmed_at price-update watermarks.

Envelope

Field	Type	Description
`type`	`"markets_stream_update"`	Envelope discriminator.
`room_id`	`"polymarket_markets_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`	`MarketResponse[]`	Full market rows, same shape as `GET /polymarket/market`.

`MarketResponse`

Field	Type	Description
`condition_id`	`string`	0x-prefixed condition ID. Required.
`id`	`string \| null`	Market ID.
`market_slug`	`string \| null`	URL-safe market slug.
`question`	`string \| null`	Market question.
`title`	`string \| null`	Market title.
`description`	`string \| null`	Long description.
`image_url`	`string \| null`	CDN image URL.
`oracle`	`string \| null`	Oracle contract address.
`status`	`string`	Market status. Required (cache holds only open markets).
`created_time`	`integer \| null`	Unix seconds.
`start_time`	`integer \| null`	Unix seconds.
`game_start_time`	`integer \| null`	Unix seconds (sports markets).
`closed_time`	`integer \| null`	Unix seconds.
`end_time`	`integer \| null`	Unix seconds.
`accepting_orders`	`boolean \| null`	Whether CLOB is accepting new orders.
`uma_resolution_status`	`string \| null`	UMA oracle resolution status.
`is_neg_risk`	`boolean \| null`	Whether this market uses the neg-risk exchange.
`market_maker_address`	`string \| null`	Market maker contract.
`creator`	`string \| null`	Wallet address of creator.
`category`	`string \| null`	Category label.
`volume_usd`	`number \| null`	Lifetime USD volume.
`liquidity_usd`	`number \| null`	Current USD liquidity.
`highest_probability`	`number \| null`	Highest outcome probability (0 – 1).
`total_holders`	`integer \| null`	Unique holder count.
`total_daily_rate`	`number \| null`	Combined daily reward rate across sponsors.
`winning_outcome`	`MarketOutcome \| null`	Resolved winning outcome, when applicable.
`outcomes`	`MarketOutcome[]`	Market outcomes.
`clob_rewards`	`ClobReward[]`	Active reward configs.
`tags`	`string[]`	Tag labels attached to the market.
`event_slug`	`string \| null`	Parent event slug.
`resolution_source`	`string \| null`	Resolution source URL.
`metrics`	`Record<Timeframe, SimpleTimeframeMetrics>`	Keyed by timeframe (`1m`, `5m`, `30m`, `1h`, `6h`, `24h`, `7d`, `30d`).
`relevance_score`	`number \| null`	Search relevance score, when applicable.

`MarketOutcome`

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.
`latest_block`	`integer \| null`	Block of the most recent price update for this outcome.
`latest_confirmed_at`	`integer \| null`	Unix seconds of the most recent price update.

`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.

`ClobReward`

Field	Type	Description
`id`	`string`	Reward config ID. Required.
`condition_id`	`string`	Market condition ID. Required.
`asset_address`	`string \| null`	Reward token contract.
`rewards_amount`	`number \| null`	Total rewards remaining.
`rewards_daily_rate`	`number \| null`	Rewards emitted per day.
`start_date`	`string \| null`	ISO date the reward starts emitting.
`end_date`	`string \| null`	ISO date the reward stops emitting.
`rewards_max_spread`	`number \| null`	Max spread eligible for rewards (probability).
`rewards_min_size`	`number \| null`	Min order size eligible for rewards (USD).
`native_daily_rate`	`number \| null`	Native (Polymarket) daily rate.
`sponsored_daily_rate`	`number \| null`	Sponsored daily rate.
`total_daily_rate`	`number \| null`	Combined daily rate.
`sponsors_count`	`integer \| null`	Number of active sponsors.

Example

{
  "type": "markets_stream_update",
  "room_id": "polymarket_markets_stream",
  "mode": "ids",
  "interval_ms": 500,
  "data": [
    {
      "condition_id": "0xabc123...",
      "id": "m_1",
      "market_slug": "will-bitcoin-hit-100k",
      "question": "Will Bitcoin hit $100k by Dec 31, 2026?",
      "title": "Bitcoin $100k by EOY 2026",
      "description": "Resolves YES if BTC closes above $100,000 on any day before Dec 31, 2026.",
      "image_url": "https://cdn.struct.to/markets/btc-100k.png",
      "oracle": "0xoracle...",
      "status": "open",
      "created_time": 1743400000,
      "start_time": 1743500000,
      "game_start_time": null,
      "closed_time": null,
      "end_time": 1798761600,
      "accepting_orders": true,
      "uma_resolution_status": null,
      "is_neg_risk": false,
      "market_maker_address": "0xmm...",
      "creator": "0xcreator...",
      "category": "crypto",
      "volume_usd": 125000.5,
      "liquidity_usd": 42000.0,
      "highest_probability": 0.65,
      "total_holders": 312,
      "total_daily_rate": 150.0,
      "winning_outcome": null,
      "outcomes": [
        {
          "name": "Yes",
          "price": 0.65,
          "position_id": "12345678901234567",
          "outcome_index": 0,
          "latest_block": 65000000,
          "latest_confirmed_at": 1743500000
        },
        {
          "name": "No",
          "price": 0.35,
          "position_id": "98765432109876543",
          "outcome_index": 1,
          "latest_block": 65000000,
          "latest_confirmed_at": 1743500000
        }
      ],
      "clob_rewards": [
        {
          "id": "1",
          "condition_id": "0xabc123...",
          "asset_address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
          "rewards_amount": 18250.0,
          "rewards_daily_rate": 50.0,
          "start_date": "2026-01-01",
          "end_date": "2026-12-31",
          "rewards_max_spread": 0.04,
          "rewards_min_size": 20.0,
          "native_daily_rate": 100.0,
          "sponsored_daily_rate": 50.0,
          "total_daily_rate": 150.0,
          "sponsors_count": 1
        }
      ],
      "tags": ["crypto", "bitcoin"],
      "event_slug": "bitcoin-price-markets",
      "resolution_source": "https://example.com/btc-resolution",
      "metrics": {
        "24h": { "volume": 3200.0, "fees": 6.4, "txns": 42, "unique_traders": 18 },
        "7d": { "volume": 22000.0, "fees": 44.0, "txns": 310, "unique_traders": 121 }
      },
      "relevance_score": null
    }
  ]
}

Introduction

Rooms

Alerts

Subscription model

Message fields

Filter fields (`mode=filter`)

Example — filter mode

Example — ids mode

Unsubscribe one slot

Response

Events

`markets_stream_update`

Envelope

`MarketResponse`

`MarketOutcome`

`SimpleTimeframeMetrics`

`ClobReward`

Example

Introduction

Rooms

Alerts

​Subscription model

​Subscribe

​Message fields

​Filter fields (mode=filter)

​Example — filter mode

​Example — ids mode

​Unsubscribe one slot

​Response

​Events

​markets_stream_update

​Envelope

​MarketResponse

​MarketOutcome

​SimpleTimeframeMetrics

​ClobReward

​Example

Subscription model

Subscribe

Message fields

Filter fields (`mode=filter`)

Example — filter mode

Example — ids mode

Unsubscribe one slot

Response

Events

`markets_stream_update`

Envelope

`MarketResponse`

`MarketOutcome`

`SimpleTimeframeMetrics`

`ClobReward`

Example