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

Methods

MethodEndpointDescription
private()wss://api.polymarket.us/v1/ws/privateOrders, positions, balance updates
markets()wss://api.polymarket.us/v1/ws/marketsMarket data and trades

private

Connect to the private WebSocket for real-time order, position, and balance updates.
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

TypeDescription
SUBSCRIPTION_TYPE_ORDEROrder updates and snapshots
SUBSCRIPTION_TYPE_POSITIONPosition changes
SUBSCRIPTION_TYPE_ACCOUNT_BALANCEBalance updates

Private Events

EventDescription
orderSnapshotInitial snapshot of all orders
orderUpdateOrder state change
positionSnapshotInitial snapshot of all positions
positionUpdatePosition change
accountBalanceSnapshotInitial balance snapshot
accountBalanceUpdateBalance change

markets

Connect to the markets WebSocket for real-time market data and trades.
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

TypeDescription
SUBSCRIPTION_TYPE_MARKET_DATAFull order book and stats
SUBSCRIPTION_TYPE_MARKET_DATA_LITELightweight price data (BBO)
SUBSCRIPTION_TYPE_TRADEReal-time trade notifications

Market Events

EventDescription
marketDataFull order book update
marketDataLiteBBO and price update
tradeTrade 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