polymarket-websocket-client

Zero-dependency TypeScript WebSocket client for Polymarket CLOB and RTDS APIs. Supports all WebSocket channels with automatic reconnection, heartbeat, and comprehensive error handling.

Features

• Zero Dependencies: Uses only Node.js native WebSocket (requires Node.js 22+)
• Full Channel Support: CLOB Market, CLOB User, and RTDS channels
• Auto Reconnection: Exponential backoff with configurable retries
• Heartbeat: Automatic ping/pong to maintain connections
• TypeScript First: Complete type definitions for all events
• Dual Module Output: ESM and CommonJS support

Installation

npm install polymarket-websocket-client
# or
pnpm add polymarket-websocket-client
# or
yarn add polymarket-websocket-client

Quick Start

CLOB Market Channel (Public Orderbook Data)

import { ClobMarketClient } from 'polymarket-websocket-client';

const client = new ClobMarketClient();

// Subscribe to orderbook updates
client.onBook((event) => {
  console.log('Orderbook:', event.asset_id, event.bids, event.asks);
});

client.onPriceChange((event) => {
  console.log('Price change:', event.price_changes);
});

client.onLastTradePrice((event) => {
  console.log('Trade:', event.asset_id, event.price, event.size);
});

// Connect and subscribe to assets
await client.connect();
client.subscribe(['71321045679252212594626385532706912750332728571942532289631379312455583992563']);

CLOB User Channel (Authenticated Trading Data)

import { ClobUserClient } from 'polymarket-websocket-client';

const client = new ClobUserClient({
  apiKey: 'your-api-key',
  secret: 'your-secret',
  passphrase: 'your-passphrase',
});

// Listen for your trades and orders
client.onTrade((event) => {
  console.log('Trade:', event.id, event.status, event.price, event.size);
});

client.onOrder((event) => {
  console.log('Order:', event.id, event.type, event.price);
});

// Connect and subscribe to markets
await client.connect();
client.subscribe(['0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af']);

RTDS (Real-Time Data Socket)

import { RtdsClient } from 'polymarket-websocket-client';

const client = new RtdsClient();

// Listen for crypto price updates
client.onCryptoPrice((message) => {
  console.log('Price:', message.payload.symbol, message.payload.value);
});

// Listen for comments
client.onComment((message) => {
  console.log('Comment:', message.payload.body);
});

await client.connect();

// Subscribe to crypto prices (Binance)
client.subscribeCryptoPrices(['btcusdt', 'ethusdt']);

// Subscribe to comments
client.subscribeComments('comment_created');

Unified CLOB Client

import { ClobClient } from 'polymarket-websocket-client';

const client = new ClobClient({
  auth: {
    apiKey: 'your-api-key',
    secret: 'your-secret',
    passphrase: 'your-passphrase',
  },
});

// Access both channels
client.market.onBook((event) => console.log('Book:', event));
client.user.onTrade((event) => console.log('Trade:', event));

// Connect to both channels
await client.connectAll();

// Subscribe
client.market.subscribe(['asset-id']);
client.user.subscribe(['market-id']);

// Disconnect all
client.disconnect();

Configuration Options

All clients accept configuration options:

interface ClientOptions {
  url?: string;                    // Custom WebSocket URL
  autoReconnect?: boolean;         // Enable auto-reconnection (default: true)
  maxReconnectAttempts?: number;   // Max reconnection attempts (default: Infinity)
  reconnectDelay?: number;         // Base delay between reconnects in ms (default: 1000)
  maxReconnectDelay?: number;      // Max reconnection delay in ms (default: 30000)
  heartbeatInterval?: number;      // Heartbeat interval in ms (default: 30000 for CLOB, 5000 for RTDS)
  connectionTimeout?: number;      // Connection timeout in ms (default: 10000)
}

Connection Events

All clients emit connection lifecycle events:

client.on('connected', () => {
  console.log('Connected!');
});

client.on('disconnected', ({ code, reason }) => {
  console.log('Disconnected:', code, reason);
});

client.on('reconnecting', ({ attempt, maxAttempts }) => {
  console.log(`Reconnecting... attempt ${attempt}/${maxAttempts}`);
});

client.on('error', (error) => {
  console.error('Error:', error);
});

client.on('stateChange', ({ state, previousState }) => {
  console.log(`State changed: ${previousState} -> ${state}`);
});

API Reference

ClobMarketClient

Method	Description
connect()	Connect to the WebSocket server
disconnect()	Disconnect from the server
subscribe(assetIds)	Subscribe to asset IDs (token IDs)
unsubscribe(assetIds)	Unsubscribe from asset IDs
onBook(callback)	Listen for orderbook snapshots
onPriceChange(callback)	Listen for price changes
onTickSizeChange(callback)	Listen for tick size changes
onLastTradePrice(callback)	Listen for last trade prices
onMarketMessage(callback)	Listen for all market events

ClobUserClient

Method	Description
connect()	Connect to the WebSocket server
disconnect()	Disconnect from the server
subscribe(marketIds)	Subscribe to market IDs (condition IDs)
unsubscribe(marketIds)	Unsubscribe from market IDs
onTrade(callback)	Listen for trade events
onOrder(callback)	Listen for order events
onUserMessage(callback)	Listen for all user events

RtdsClient

Method	Description
connect()	Connect to the WebSocket server
disconnect()	Disconnect from the server
subscribeCryptoPrices(symbols?)	Subscribe to Binance crypto prices
subscribeCryptoPricesChainlink(symbol?)	Subscribe to Chainlink prices
subscribeComments(type?, gammaAuth?)	Subscribe to comment events
subscribeActivity(type, clobAuth?, gammaAuth?)	Subscribe to activity events
onCryptoPrice(callback)	Listen for crypto price updates
onComment(callback)	Listen for comment events
onActivity(callback)	Listen for activity events
onRtdsMessage(callback)	Listen for all RTDS messages

Event Types

CLOB Market Events

• book: Full orderbook snapshot
• price_change: Order placement/cancellation updates
• tick_size_change: Tick size changes at price extremes
• last_trade_price: Trade execution events

CLOB User Events

• trade: Trade lifecycle (MATCHED → MINED → CONFIRMED/FAILED)
• order: Order lifecycle (PLACEMENT → UPDATE → CANCELLATION)

RTDS Events

• crypto_prices: Binance price updates
• crypto_prices_chainlink: Chainlink price updates
• comments: Comment creation/removal and reactions

Requirements

• Node.js 22+ (for native WebSocket support)

License

MIT