Skip to main content
Subscribe to real-time market data updates including order book depth, instrument states, and trade statistics using Python and gRPC.
No Participant ID RequiredThis streaming endpoint only requires Auth0 JWT authentication with read:marketdata scope. You do not need to provide the x-participant-id header or complete KYC onboarding to access market data streams.

Service Definition

Service: polymarket.v1.MarketDataSubscriptionAPI The service provides two streaming methods:
  1. CreateMarketDataSubscription - Server-side streaming with fixed symbols at subscription time
  2. BiDirectionalStreamMarketData - Bidirectional streaming with dynamic symbol management
When to use which method:
  • Use CreateMarketDataSubscription for simple subscriptions where symbols are known upfront
  • Use BiDirectionalStreamMarketData when you need to dynamically add/remove symbols without reconnecting

Request Parameters

CreateMarketDataSubscriptionRequest

Symbol Limit: Each gRPC stream is limited to 1000 symbols maximum. If you need to subscribe to more than 1000 symbols, create multiple streams.

Example Request

Response Messages

The stream returns CreateMarketDataSubscriptionResponse messages with two possible event types:

1. Heartbeat Messages

Keep-alive messages to confirm connection is active.
If you stop receiving heartbeats, the connection may be stale. Consider reconnecting.

2. Market Data Updates

Real-time market data changes.

Update Message Structure

Fields

Instrument State Tracking: The state field in MarketDataUpdate is optional and should not be relied upon for tracking instrument state changes. The preferred approach is to use ListInstruments to get and cache the initial state for each instrument, then subscribe to the instrument state change subscription for real-time state updates.

BookEntry Structure

Each price level in the order book contains:
Price Representation: All prices are int64 values. Divide by the instrument’s price_scale to get the decimal value.price_scale varies by instrument. Query instrument metadata to get the correct value.

InstrumentStats Structure

Market statistics include:
Stats fields use protobuf oneof, so they may not always be present. Always check with HasField() before accessing.

Settlement Fields

Settlement Price Calculation Methods:
For Polymarket event markets, settlement_price_calculation_method will be SETTLEMENT_PRICE_CALCULATION_METHOD_EVENT_TIER_1. If you see a different method, you can treat it as a daily mark rather than final resolution.
Example: Settled Market (YES wins)
In this example, settlement_px = 1000 with a price_scale of 1000 equals $1.00 (YES won, Buffalo won the game). Example: Settled Market (NO wins)
In this example, settlement_px = 0 equals $0.00 (NO won, Kansas City won so Buffalo did not win).

Instrument States

Preferred approach: Use ListInstruments to get and cache the initial state for each instrument, then subscribe to the instrument state change stream for ongoing state updates. The state field on MarketDataUpdate is now optional.

Primary State Flow

Exception States

Other Possible States

Complete Example (from stream.py)

This example matches the implementation from the Python examples repository:

Bidirectional Streaming

The BiDirectionalStreamMarketData RPC allows you to dynamically add and remove symbols during the subscription lifetime without reconnecting.

Request Messages

Send BiDirectionalStreamMarketDataRequest messages to manage your subscription:

Commands

ALB Idle Timeout & KeepalivesLong-lived bidirectional streams that send no client-to-server traffic for ~1 hour will be terminated with RST_STREAM by the AWS Application Load Balancer (idle timeout is 3600 seconds by default).To keep an otherwise-quiet stream alive, send a KeepAliveCommand every 30–60 minutes. The server treats it as a no-op: no response, no change to subscription state or symbol list.This only applies to BiDirectionalStreamMarketData. Server-streaming RPCs like CreateMarketDataSubscription are not affected.

Response Messages

The stream returns BiDirectionalStreamMarketDataResponse messages with four possible event types:

Error Codes

Python Example

Go Example


Next Steps

Order Streaming

Subscribe to order execution updates

Proto Reference

Detailed protocol buffer reference

Error Handling

Handle errors and reconnections