Skip to main content

​
Streaming Endpoints

All streaming endpoints use the Connect protocol for real-time data delivery. These endpoints are not available via REST - use Connect or gRPC clients.

​
Endpoint Format

Connect endpoints follow this pattern: 
POST https://{host}/{package}.{service}/{method}
Example: 
POST https://api.preprod.polymarketexchange.com/polymarket.v1.MarketDataSubscriptionAPI/CreateMarketDataSubscription

​
Market Data

​
CreateMarketDataSubscription

Real-time L2 order book updates for specified symbols.
PropertyValue
Servicepolymarket.v1.MarketDataSubscriptionAPI
MethodCreateMarketDataSubscription
Scoperead:marketdata
Request: 
{
  "symbols": ["tec-nfl-sbw-2026-02-08-kc"],
  "depth": 5
}
Response Stream: 
{
  "result": {
    "symbol": "tec-nfl-sbw-2026-02-08-kc",
    "bids": [
      {"px": "52000", "qty": "100"}
    ],
    "offers": [
      {"px": "53000", "qty": "50"}
    ],
    "transactTime": "2024-12-27T10:30:00Z"
  }
}

​
Orders

​
CreateOrderSubscription

Real-time order status and execution updates.
PropertyValue
Servicepolymarket.v1.OrderEntryAPI
MethodCreateOrderSubscription
Scoperead:orders
Request: 
{
  "symbols": ["tec-nfl-sbw-2026-02-08-kc"],
  "accounts": ["firms/ISV-Alice/accounts/alice-trading"],
  "snapshotOnly": false
}
Response Stream: 
{
  "result": {
    "snapshot": {
      "orders": [
        {
          "orderId": "order-123",
          "symbol": "tec-nfl-sbw-2026-02-08-kc",
          "side": "SIDE_BUY",
          "orderQty": "100",
          "price": "52000",
          "orderStatus": "ORDER_STATUS_NEW"
        }
      ]
    }
  }
}

​
Positions

​
CreatePositionSubscription

Real-time position and balance updates.
PropertyValue
Servicepolymarket.v1.PositionAPI
MethodCreatePositionSubscription
Scoperead:positions
Request: 
{
  "accounts": ["firms/ISV-Alice/accounts/alice-trading"]
}
Response Stream: 
{
  "result": {
    "snapshot": {
      "positions": [
        {
          "account": "firms/ISV-Alice/accounts/alice-trading",
          "symbol": "tec-nfl-sbw-2026-02-08-kc",
          "netPosition": "100",
          "cost": "5200000"
        }
      ]
    }
  }
}

​
Drop Copy

Drop Copy provides a complete audit trail of all executions for your firm.

​
CreateDropCopySubscription

Main execution feed for all accounts.
PropertyValue
Servicepolymarket.v1.DropCopyAPI
MethodCreateDropCopySubscription
Scoperead:dropcopy
Request: 
{
  "accounts": []
}
Response Stream: 
{
  "result": {
    "executionReport": {
      "orderId": "order-123",
      "execId": "exec-456",
      "execType": "EXEC_TYPE_FILL",
      "lastQty": "50",
      "lastPx": "52000"
    }
  }
}

​
CreateTradeCaptureReportSubscription

Trade capture reports for reconciliation.
PropertyValue
Servicepolymarket.v1.DropCopyAPI
MethodCreateTradeCaptureReportSubscription
Scoperead:dropcopy

​
CreatePositionChangeSubscription

Position change events.
PropertyValue
Servicepolymarket.v1.DropCopyAPI
MethodCreatePositionChangeSubscription
Scoperead:dropcopy

​
CreateInstrumentStateChangeSubscription

Instrument state changes (OPEN, HALTED, EXPIRED, etc.).
PropertyValue
Servicepolymarket.v1.DropCopyAPI
MethodCreateInstrumentStateChangeSubscription
Scoperead:instruments

​
Connection Examples

​
Python with requests

import requests
import json

def stream_orders(token: str, symbols: list[str]):
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "Accept": "application/connect+json",
        "Connect-Protocol-Version": "1"
    }

    url = "https://api.preprod.polymarketexchange.com/polymarket.v1.OrderEntryAPI/CreateOrderSubscription"

    payload = {
        "symbols": symbols,
        "snapshotOnly": False
    }

    with requests.post(url, headers=headers, json=payload, stream=True) as response:
        response.raise_for_status()
        for line in response.iter_lines():
            if line:
                data = json.loads(line)
                yield data

​
Go with Connect

client := polymarketv1connect.NewOrderEntryAPIClient(
    http.DefaultClient,
    "https://api.preprod.polymarketexchange.com",
)

stream, err := client.CreateOrderSubscription(ctx, connect.NewRequest(&polymarketv1.CreateOrderSubscriptionRequest{
    Symbols: []string{"tec-nfl-sbw-2026-02-08-kc"},
}))
if err != nil {
    log.Fatal(err)
}

for stream.Receive() {
    log.Printf("Order update: %+v", stream.Msg())
}

​
Slow Consumer Handling

Streaming endpoints support a slow_consumer_skip_to_head option that controls what happens when your client falls behind the data stream.
ValueBehaviorUse Case
false (default)Disconnect the clientTrading apps that require every message
trueSkip to latest data, dropping missed messagesReal-time displays, dashboards
Supported on:
  • CreateMarketDataSubscription
  • CreateInstrumentStateChangeSubscription
Example Request: 
{
  "symbols": ["tec-nfl-sbw-2026-02-08-kc"],
  "depth": 5,
  "slowConsumerSkipToHead": true
}
If your application requires processing every message (e.g., for order tracking or reconciliation), use the default false setting. Implement reconnection logic to resume from your last known position using the resume_token field.

​
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.

​
Best Practices

Reconnection

Implement automatic reconnection with exponential backoff

Token Refresh

Refresh tokens before the 3-minute expiry

Error Handling

Handle disconnections gracefully

Heartbeats

Monitor stream health with heartbeat messages