Skip to main content

​
gRPC Streaming API

The Polymarket Exchange provides gRPC streaming services for real-time market data and order execution updates. This enables low-latency, efficient data delivery for applications that need continuous updates.

​
Why Use gRPC Streaming?

gRPC streaming offers several advantages:
  • Bidirectional Communication: Server can push updates without client polling
  • Type Safety: Strongly-typed messages defined in Protocol Buffers
  • Real-time Updates: Receive market data and order updates as they happen

​
REST + gRPC Hybrid Approach

Most participants use REST for requests and gRPC for streaming. This hybrid approach combines the simplicity of REST with the efficiency of gRPC streaming.

​
Typical Integration Pattern

  1. REST API - Used for:
    • Placing orders (/v1/trading/orders)
    • Canceling orders (/v1/trading/orders/cancel)
    • Querying account information
    • One-time data requests
  2. gRPC Streaming - Used for:
    • Real-time market data updates
    • Live order execution reports
    • Continuous position monitoring
    • Order book changes

​
Available Streaming Services

​
Market Data Streaming

Subscribe to real-time market data updates including:
  • Order book (bids and offers)
  • Instrument state changes
  • Trade statistics (last price, OHLC, volume)
  • Open interest
Service: MarketDataSubscriptionAPI.CreateMarketDataSubscription Learn more about Market Data Streaming →

​
Order Execution Streaming

Subscribe to real-time order and execution updates:
  • New order confirmations
  • Partial and complete fills
  • Order cancellations and rejections
  • Execution reports with trade details
Service: OrderEntryAPI.CreateOrderSubscription Learn more about Order Streaming →

​
Server Endpoints

​
Pre-Production Environment

grpc-api.preprod.polymarketexchange.com:443

​
Production Environment

grpc-api.polymarketexchange.com:443
Both endpoints use TLS/SSL for secure communication. All connections must be encrypted.

​
Testing Connectivity

From a machine with proper DNS (or after adding to /etc/hosts): 
# Test preprod connectivity
grpcurl -insecure grpc-api.preprod.polymarketexchange.com:443 list
This will list all available gRPC services if your connection is successful.

​
Protocol Buffer Definitions

The exchange uses Protocol Buffers (proto3) to define message structures. Proto files are available:
  • Upon request: Contact onboarding@qcex.com
  • Via server reflection: Use gRPC reflection to discover services at runtime

​
Package Structure

polymarket.v1                       # Core services
├── MarketDataSubscriptionAPI       # Market data streaming
├── OrderEntryAPI                   # Order streaming and entry
├── RefDataAPI                      # Reference data (instruments, symbols)
├── AccountsAPI                     # Account information
├── PositionAPI                     # Positions and balances
├── ReportAPI                       # Order and trade reports
├── DropCopyAPI                     # Trade execution feed

​
Quick Start

Ready to get started? Follow our Getting Started Guide to:
  1. Install Python gRPC libraries
  2. Obtain and compile proto files
  3. Authenticate and connect
  4. Subscribe to your first data stream

​
Architecture Overview

​
Authentication Flow

  1. Obtain JWT Token: Request M2M token using client credentials
  2. Attach Token: Include token in gRPC metadata as authorization header
  3. Stream Data: Receive continuous updates over persistent connection
Learn more about Authentication →

​
Rate Limits

LimitValue
Ingress (client → server)20 messages/sec
Concurrent connections10 per account
Ingress Rate LimitClient-to-server messages are limited to 20 messages per second. This applies to requests you send, not to server-pushed updates like market data. Messages exceeding this rate may be dropped or the connection may be throttled.

​
Key Concepts

​
Heartbeats

Periodic keep-alive messages ensure connection health. If heartbeats stop, the connection may be stale.

​
Snapshots

Initial state of data (e.g., all open orders) sent when subscription starts.

​
Updates

Incremental changes streamed continuously after the snapshot.

​
Session IDs

Unique identifiers for each streaming session, useful for logging and debugging.

​
Next Steps

Getting Started

Set up your first gRPC stream

Authentication

Learn how to authenticate gRPC connections

Market Data

Stream real-time market data

Order Updates

Subscribe to order execution updates