Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.polymarket.us/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Public market data available to all users:
  • Best Bid/Offer (BBO) - Current best prices
  • L2 Order Book - Full depth of market
Private trade data (requires account access):
  • Trades - Executed transactions for your account

​
Required Scopes

ScopeData Access
read:marketdataBBO, streaming market data
read:l2marketdataFull L2 order book depth

​
REST API Endpoints

​
Get Best Bid/Offer

Retrieve the current best bid and offer for a symbol: 
curl -X GET "https://api.preprod.polymarketexchange.com/v1/orderbook/{symbol}/bbo" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "symbol": "aec-nfl-buf-nyj-2025-01-15",
  "bestBid": {
    "px": "650",
    "qty": "1000"
  },
  "bestOffer": {
    "px": "670",
    "qty": "500"
  },
  "spread": "20",
  "midPrice": "660",
  "state": "INSTRUMENT_STATE_OPEN",
  "transactTime": "2025-01-15T10:30:00Z"
}

​
Get L2 Order Book

Retrieve the full order book depth: 
curl -X GET "https://api.preprod.polymarketexchange.com/v1/orderbook/{symbol}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "symbol": "aec-nfl-buf-nyj-2025-01-15",
  "bids": [
    {"px": "650", "qty": "1000"},
    {"px": "640", "qty": "2000"},
    {"px": "630", "qty": "1500"}
  ],
  "offers": [
    {"px": "670", "qty": "500"},
    {"px": "680", "qty": "800"},
    {"px": "690", "qty": "1200"}
  ],
  "state": "INSTRUMENT_STATE_OPEN",
  "transactTime": "2025-01-15T10:30:00Z"
}
For OHLC/candlestick data generation, see the Candlestick Data Guide.

​
Streaming Market Data (gRPC)

For real-time updates, use the gRPC Market Data Stream.

​
Subscribe to Market Data

import grpc
from polymarket_pb2 import MarketDataRequest
from polymarket_pb2_grpc import MarketDataServiceStub

# Create channel with credentials
channel = grpc.secure_channel(
    'grpc.preprod.polymarketexchange.com:443',
    grpc.ssl_channel_credentials()
)

stub = MarketDataServiceStub(channel)

# Subscribe to symbols
request = MarketDataRequest(
    symbols=["aec-nfl-buf-nyj-2025-01-15", "aec-nba-bos-lal-2025-01-20"]
)

# Stream updates
for update in stub.Subscribe(request, metadata=[('authorization', f'Bearer {token}')]):
    print(f"Symbol: {update.symbol}, Bid: {update.bid}, Ask: {update.ask}")

​
Best Practices

​
Rate Limits

  • REST endpoints are subject to rate limits
  • Use streaming (gRPC) for real-time data to reduce API calls
  • Cache reference data locally

​
Connection Management

  • Implement reconnection logic for streaming connections
  • Handle network interruptions gracefully
  • Use heartbeats to detect connection issues

​
Data Handling

  • Validate timestamps to detect stale data
  • Handle gaps in sequence numbers appropriately
  • Store historical data locally for analysis