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

# WebSocket API Overview

> Real-time streaming data via WebSocket

# WebSocket API

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

## Endpoints

| Endpoint | Description | Authentication |
| - | - | - |
| `/v1/ws/private` | Orders, positions, account balance updates | API Key |
| `/v1/ws/markets` | Market data, order book, trades | API 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 API key authentication as the REST API.

Include these headers in the WebSocket handshake:

```
X-PM-Access-Key: <your-api-key-id>
X-PM-Timestamp: <timestamp-in-milliseconds>
X-PM-Signature: <base64-encoded-signature>
```

The signature is constructed from: `timestamp + "GET" + path` where path is `/v1/ws/private` or `/v1/ws/markets`.

See [Authentication](https://docs.polymarket.us/api/authentication.md) for details on request signing.

## Message Format

All WebSocket messages are JSON formatted with snake\_case field names.

### Request Format

```json theme={null}
{
  "subscribe": {
    "request_id": "unique-request-id",
    "subscription_type": 1,
    "market_slugs": ["market-slug-1", "market-slug-2"]
  }
}
```

### Subscription Types

**Private WebSocket (`/v1/ws/private`):**

| Value | Type | Description |
| - | - | - |
| 1 | ORDER | Order updates |
| 3 | POSITION | Position changes |
| 4 | ACCOUNT\_BALANCE | Balance updates |

**Markets WebSocket (`/v1/ws/markets`):**

| Value | Type | Description |
| - | - | - |
| 1 | MARKET\_DATA | Full order book and market stats |
| 2 | MARKET\_DATA\_LITE | Lightweight price data |
| 3 | TRADE | Real-time trade notifications |

### Response Format

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "request_id": "unique-request-id",
  "error": "Error description"
}
```

## Unsubscribing

To unsubscribe from a stream:

```json theme={null}
{
  "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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.