Skip to main content

​
WebSocket API

The WebSocket API provides real-time streaming data for market information and private user data.

​
Endpoints

EndpointDescriptionAuthentication
/v1/ws/privateOrders, positions, account balance updatesAPI Key
/v1/ws/marketsMarket data, order book, tradesAPI Key

​
Connection

Connect to the WebSocket endpoints with your API key credentials: 
wss://api.polymarket.us/v1/ws/private
wss://api.polymarket.us/v1/ws/markets

​
Authentication

WebSocket connections use the same authentication headers as the REST API: 
X-PM-Access-Key: your-api-key-id
X-PM-Timestamp: timestamp-in-milliseconds
X-PM-Signature: ed25519-signature
See Authentication for details on generating signatures.

​
Message Format

All WebSocket messages are JSON formatted with snake_case field names.

​
Request Format

{
  "subscribe": {
    "request_id": "unique-request-id",
    "subscription_type": 1,
    "market_slugs": ["market-slug-1", "market-slug-2"]
  }
}

​
Subscription Types

Private WebSocket (/v1/ws/private):
ValueTypeDescription
1ORDEROrder updates
3POSITIONPosition changes
4ACCOUNT_BALANCEBalance updates
Markets WebSocket (/v1/ws/markets):
ValueTypeDescription
1MARKET_DATAFull order book and market stats
2MARKET_DATA_LITELightweight price data
3TRADEReal-time trade notifications

​
Response Format

{
  "request_id": "unique-request-id",
  "subscription_type": 1,
  "order_subscription_snapshot": {
    "orders": [...],
    "eof": true
  }
}

​
Heartbeats

The server sends periodic heartbeat messages to keep the connection alive: 
{
  "heartbeat": {}
}
Clients should respond to heartbeats or implement their own keep-alive mechanism.

​
Error Handling

If a subscription request fails, the response will include an error field: 
{
  "request_id": "unique-request-id",
  "error": "Error description"
}

​
Unsubscribing

To unsubscribe from a stream: 
{
  "unsubscribe": {
    "request_id": "original-request-id"
  }
}

​
Best Practices

  1. Use unique request IDs - Track subscriptions with unique identifiers
  2. Handle reconnection - Implement automatic reconnection with exponential backoff
  3. Process messages in order - Messages are delivered in sequence
  4. Monitor heartbeats - Reconnect if heartbeats stop
  5. Limit subscriptions - Only subscribe to markets you need