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

> Real-time streaming data

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

## Methods

| Method | Endpoint | Description |
| - | - | - |
| `private()` | `wss://api.polymarket.us/v1/ws/private` | Orders, positions, balance updates |
| `markets()` | `wss://api.polymarket.us/v1/ws/markets` | Market data and trades |

***

## private

Connect to the private WebSocket for real-time order, position, and balance updates.

```typescript theme={null}
import { PolymarketUS } from 'polymarket-us';

const client = new PolymarketUS({
  keyId: process.env.POLYMARKET_KEY_ID,
  secretKey: process.env.POLYMARKET_SECRET_KEY,
});

const ws = client.ws.private();

// Register event handlers
ws.on('orderSnapshot', (data) => console.log('Orders:', data));
ws.on('orderUpdate', (data) => console.log('Order update:', data));
ws.on('positionSnapshot', (data) => console.log('Positions:', data));
ws.on('positionUpdate', (data) => console.log('Position update:', data));
ws.on('accountBalanceSnapshot', (data) => console.log('Balance:', data));
ws.on('error', (e) => console.error('Error:', e));

await ws.connect();

// Subscribe to updates
ws.subscribeOrders('my-orders');
ws.subscribePositions('my-positions');
ws.subscribeAccountBalance('my-balance');
```

### Private Subscription Types

| Type | Description |
| - | - |
| `SUBSCRIPTION_TYPE_ORDER` | Order updates and snapshots |
| `SUBSCRIPTION_TYPE_POSITION` | Position changes |
| `SUBSCRIPTION_TYPE_ACCOUNT_BALANCE` | Balance updates |

### Private Events

| Event | Description |
| - | - |
| `orderSnapshot` | Initial snapshot of all orders |
| `orderUpdate` | Order state change |
| `positionSnapshot` | Initial snapshot of all positions |
| `positionUpdate` | Position change |
| `accountBalanceSnapshot` | Initial balance snapshot |
| `accountBalanceUpdate` | Balance change |

***

## markets

Connect to the markets WebSocket for real-time market data and trades.

```typescript theme={null}
const ws = client.ws.markets();

// Register event handlers
ws.on('marketData', (data) => console.log('Book:', data));
ws.on('marketDataLite', (data) => console.log('BBO:', data));
ws.on('trade', (data) => console.log('Trade:', data));

await ws.connect();

// Subscribe to market data
ws.subscribeMarketData('book', ['btc-100k-2025']);
ws.subscribeMarketDataLite('prices', ['btc-100k-2025']);
ws.subscribeTrades('trades', ['btc-100k-2025']);
```

### Market Subscription Types

| Type | Description |
| - | - |
| `SUBSCRIPTION_TYPE_MARKET_DATA` | Full order book and stats |
| `SUBSCRIPTION_TYPE_MARKET_DATA_LITE` | Lightweight price data (BBO) |
| `SUBSCRIPTION_TYPE_TRADE` | Real-time trade notifications |

### Market Events

| Event | Description |
| - | - |
| `marketData` | Full order book update |
| `marketDataLite` | BBO and price update |
| `trade` | Trade execution |

***

## 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. **Limit subscriptions** - Only subscribe to markets you need


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