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

> [!NOTE]
>
> WebSocket is async-only. Use `asyncio.run()` or `AsyncPolymarketUS`.

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.

```python theme={null}
import asyncio
from polymarket_us import PolymarketUS

async def main():
    client = PolymarketUS(
        key_id="your-key-id",
        secret_key="your-secret-key",
    )

    ws = client.ws.private()

    # Register event handlers
    ws.on("order_snapshot", lambda d: print(f"Orders: {d}"))
    ws.on("order_update", lambda d: print(f"Order update: {d}"))
    ws.on("position_snapshot", lambda d: print(f"Positions: {d}"))
    ws.on("position_update", lambda d: print(f"Position update: {d}"))
    ws.on("account_balance_snapshot", lambda d: print(f"Balance: {d}"))
    ws.on("error", lambda e: print(f"Error: {e}"))

    await ws.connect()
    
    # Subscribe to order updates
    await ws.subscribe("my-orders", "SUBSCRIPTION_TYPE_ORDER")
    
    # Subscribe to position updates
    await ws.subscribe("my-positions", "SUBSCRIPTION_TYPE_POSITION")
    
    # Subscribe to balance updates
    await ws.subscribe("my-balance", "SUBSCRIPTION_TYPE_ACCOUNT_BALANCE")

    await asyncio.sleep(3600)
    await ws.close()

asyncio.run(main())
```

### 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 |
| - | - |
| `order_snapshot` | Initial snapshot of all orders |
| `order_update` | Order state change |
| `position_snapshot` | Initial snapshot of all positions |
| `position_update` | Position change |
| `account_balance_snapshot` | Initial balance snapshot |
| `account_balance_update` | Balance change |

***

## markets

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

```python theme={null}
import asyncio
from polymarket_us import PolymarketUS

async def main():
    client = PolymarketUS(
        key_id="your-key-id",
        secret_key="your-secret-key",
    )

    ws = client.ws.markets()

    # Register event handlers
    ws.on("market_data", lambda d: print(f"Book: {d}"))
    ws.on("market_data_lite", lambda d: print(f"BBO: {d}"))
    ws.on("trade", lambda d: print(f"Trade: {d}"))

    await ws.connect()
    
    # Subscribe to full order book updates
    await ws.subscribe("book", "SUBSCRIPTION_TYPE_MARKET_DATA", ["btc-100k-2025"])
    
    # Subscribe to lightweight price updates
    await ws.subscribe("prices", "SUBSCRIPTION_TYPE_MARKET_DATA_LITE", ["btc-100k-2025"])
    
    # Subscribe to trade notifications
    await ws.subscribe("trades", "SUBSCRIPTION_TYPE_TRADE", ["btc-100k-2025"])

    await asyncio.sleep(3600)
    await ws.close()

asyncio.run(main())
```

### 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 |
| - | - |
| `market_data` | Full order book update |
| `market_data_lite` | 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.