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