Markets WebSocket

Real-time market data, order book, and trades

Markets WebSocket

The Markets WebSocket endpoint provides real-time market data including order book updates, price changes, and trade notifications.

Endpoint

wss://api.polymarket.us/v1/ws/markets

Subscription Types

Value	Type	Description
1	MARKET_DATA	Full order book and market stats
2	MARKET_DATA_LITE	Lightweight price data only
3	TRADE	Real-time trade notifications

Market Data Subscription

Subscribe to Full Market Data

{
  "subscribe": {
    "request_id": "md-sub-1",
    "subscription_type": 1,
    "market_slugs": ["market-slug-1", "market-slug-2"]
  }
}

Market Data Response

Full order book with market statistics:

{
  "request_id": "md-sub-1",
  "subscription_type": 1,
  "market_data": {
    "market_slug": "market-slug-1",
    "bids": [
      {"px": {"value": "0.54", "currency": "USD"}, "qty": "1000"},
      {"px": {"value": "0.53", "currency": "USD"}, "qty": "2500"}
    ],
    "offers": [
      {"px": {"value": "0.56", "currency": "USD"}, "qty": "800"},
      {"px": {"value": "0.57", "currency": "USD"}, "qty": "1500"}
    ],
    "state": 1,
    "stats": {
      "last_trade_px": {"value": "0.55", "currency": "USD"},
      "shares_traded": "150000",
      "open_interest": "500000",
      "high_px": {"value": "0.58", "currency": "USD"},
      "low_px": {"value": "0.52", "currency": "USD"}
    },
    "transact_time": "2024-01-15T10:30:00Z"
  }
}

Market Data Lite Subscription

Subscribe to Lightweight Data

For reduced bandwidth, use the lite subscription:

{
  "subscribe": {
    "request_id": "mdl-sub-1",
    "subscription_type": 2,
    "market_slugs": ["market-slug-1"]
  }
}

Market Data Lite Response

{
  "request_id": "mdl-sub-1",
  "subscription_type": 2,
  "market_data_lite": {
    "market_slug": "market-slug-1",
    "current_px": {"value": "0.55", "currency": "USD"},
    "last_trade_px": {"value": "0.55", "currency": "USD"},
    "best_bid": {"value": "0.54", "currency": "USD"},
    "best_ask": {"value": "0.56", "currency": "USD"},
    "bid_depth": 5,
    "ask_depth": 4,
    "shares_traded": "150000",
    "open_interest": "500000"
  }
}

Trade Subscription

Subscribe to Trades

{
  "subscribe": {
    "request_id": "trade-sub-1",
    "subscription_type": 3,
    "market_slugs": ["market-slug-1"]
  }
}

Trade Response

{
  "request_id": "trade-sub-1",
  "subscription_type": 3,
  "trade": {
    "market_slug": "market-slug-1",
    "price": {"value": "0.55", "currency": "USD"},
    "quantity": {"value": "100", "currency": "USD"},
    "trade_time": "2024-01-15T10:30:00Z",
    "maker": {
      "side": 1,
      "intent": 1
    },
    "taker": {
      "side": 2,
      "intent": 2
    }
  }
}

Market States

Value	State	Description
1	OPEN	Market open for trading
2	PREOPEN	Market in pre-open phase
3	SUSPENDED	Trading temporarily suspended
4	HALTED	Trading halted
5	EXPIRED	Market has expired
6	TERMINATED	Market terminated

Debouncing

For high-frequency markets, enable response debouncing to reduce message volume:

{
  "subscribe": {
    "request_id": "md-sub-1",
    "subscription_type": 1,
    "market_slugs": ["market-slug-1"],
    "responses_debounced": true
  }
}

When debouncing is enabled, updates are batched and sent at regular intervals rather than on every change.

Subscription Limits

You can subscribe to a maximum of 100 markets per subscription. Use multiple subscriptions if you need more.

Order Book Depth

The full market data subscription includes the top levels of the order book. Each level shows:

Field	Description
px	Price level
qty	Total quantity at this price

Order book levels are sorted best-to-worst (highest bid first, lowest ask first).