Markets WebSocket

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

Authentication RequiredThis WebSocket endpoint requires API key authentication in the connection handshake. See the Authentication guide for details.

Endpoint

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

Subscription Types

Value	Description
`SUBSCRIPTION_TYPE_MARKET_DATA`	Full order book and market stats
`SUBSCRIPTION_TYPE_MARKET_DATA_LITE`	Lightweight price data only
`SUBSCRIPTION_TYPE_TRADE`	Real-time trade notifications

Market Data Subscription

{
  "subscribe": {
    "requestId": "md-sub-1",
    "subscriptionType": "SUBSCRIPTION_TYPE_MARKET_DATA",
    "marketSlugs": ["market-slug-1", "market-slug-2"]
  }
}

Market Data Response

Full order book with market statistics:

{
  "requestId": "md-sub-1",
  "subscriptionType": "SUBSCRIPTION_TYPE_MARKET_DATA",
  "marketData": {
    "marketSlug": "market-slug-1",
    "bids": [
      {"px": {"value": "0.555", "currency": "USD"}, "qty": "0.50"},
      {"px": {"value": "0.550", "currency": "USD"}, "qty": "2.50"}
    ],
    "offers": [
      {"px": {"value": "0.560", "currency": "USD"}, "qty": "0.80"},
      {"px": {"value": "0.565", "currency": "USD"}, "qty": "1.50"}
    ],
    "state": "MARKET_STATE_OPEN",
    "stats": {
      "lastTradePx": {"value": "0.55", "currency": "USD"},
      "sharesTraded": "150000",
      "openInterest": "500000",
      "highPx": {"value": "0.58", "currency": "USD"},
      "lowPx": {"value": "0.52", "currency": "USD"}
    },
    "transactTime": "2024-01-15T10:30:00Z"
  }
}

Market Data Lite Subscription

For reduced bandwidth, use the lite subscription:

{
  "subscribe": {
    "requestId": "mdl-sub-1",
    "subscriptionType": "SUBSCRIPTION_TYPE_MARKET_DATA_LITE",
    "marketSlugs": ["market-slug-1"]
  }
}

Market Data Lite Response

{
  "requestId": "mdl-sub-1",
  "subscriptionType": "SUBSCRIPTION_TYPE_MARKET_DATA_LITE",
  "marketDataLite": {
    "marketSlug": "market-slug-1",
    "currentPx": {"value": "0.55", "currency": "USD"},
    "lastTradePx": {"value": "0.55", "currency": "USD"},
    "bestBid": {"value": "0.54", "currency": "USD"},
    "bestAsk": {"value": "0.56", "currency": "USD"},
    "bidDepth": 5,
    "askDepth": 4,
    "sharesTraded": "150000",
    "openInterest": "500000"
  }
}

Trade Subscription

{
  "subscribe": {
    "requestId": "trade-sub-1",
    "subscriptionType": "SUBSCRIPTION_TYPE_TRADE",
    "marketSlugs": ["market-slug-1"]
  }
}

Trade Response

{
  "requestId": "trade-sub-1",
  "subscriptionType": "SUBSCRIPTION_TYPE_TRADE",
  "trade": {
    "marketSlug": "market-slug-1",
    "price": {"value": "0.555", "currency": "USD"},
    "quantity": {"value": "0.50", "currency": "USD"},
    "tradeTime": "2024-01-15T10:30:00Z",
    "maker": {
      "side": "ORDER_SIDE_BUY",
      "intent": "ORDER_INTENT_BUY_LONG"
    },
    "taker": {
      "side": "ORDER_SIDE_SELL",
      "intent": "ORDER_INTENT_SELL_LONG"
    }
  }
}

Market States

Value	Description
`MARKET_STATE_OPEN`	Market open for trading
`MARKET_STATE_PREOPEN`	Market in pre-open phase
`MARKET_STATE_SUSPENDED`	Trading temporarily suspended
`MARKET_STATE_HALTED`	Trading halted
`MARKET_STATE_EXPIRED`	Market has expired
`MARKET_STATE_TERMINATED`	Market terminated
`MARKET_STATE_MATCH_AND_CLOSE_AUCTION`	Market in closing auction

Order Side

Value	Description
`ORDER_SIDE_BUY`	Buy order
`ORDER_SIDE_SELL`	Sell order

Order Intent

Value	Description
`ORDER_INTENT_BUY_LONG`	Buy YES contracts
`ORDER_INTENT_SELL_LONG`	Sell YES contracts
`ORDER_INTENT_BUY_SHORT`	Buy NO contracts
`ORDER_INTENT_SELL_SHORT`	Sell NO contracts

Debouncing

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

{
  "subscribe": {
    "requestId": "md-sub-1",
    "subscriptionType": "SUBSCRIPTION_TYPE_MARKET_DATA",
    "marketSlugs": ["market-slug-1"],
    "responsesDebounced": true
  }
}

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

Subscription LimitsYou 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. May contain decimals for partial-contract markets.

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

​Markets WebSocket

​Endpoint

​Subscription Types

​Market Data Subscription

​Subscribe to Full Market Data

​Market Data Response

​Market Data Lite Subscription

​Subscribe to Lightweight Data

​Market Data Lite Response

​Trade Subscription

​Subscribe to Trades

​Trade Response

​Market States

​Order Side

​Order Intent

​Debouncing

​Order Book Depth

Markets WebSocket

Endpoint

Subscription Types

Market Data Subscription

Subscribe to Full Market Data

Market Data Response

Market Data Lite Subscription

Subscribe to Lightweight Data

Market Data Lite Response

Trade Subscription

Subscribe to Trades

Trade Response

Market States

Order Side

Order Intent

Debouncing

Order Book Depth