WebSocket

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.

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.

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

Use unique request IDs - Track subscriptions with unique identifiers
Handle reconnection - Implement automatic reconnection with exponential backoff
Process messages in order - Messages are delivered in sequence
Limit subscriptions - Only subscribe to markets you need

Overview

Python

TypeScript

Methods

private

Private Subscription Types

Private Events

markets

Market Subscription Types

Market Events

Best Practices

​Methods

​private

​Private Subscription Types

​Private Events

​markets

​Market Subscription Types

​Market Events

​Best Practices

Methods

private

Private Subscription Types

Private Events

markets

Market Subscription Types

Market Events

Best Practices