A TypeScript library for real-time Polymarket market price alerts over Websocket with automatic reconnections and easy subscription management.

Powering Nevua Markets

npm install @nevuamarkets/poly-websockets

• 📊 Real-time Market Updates: Get book , price_change, tick_size_change and last_trade_price real-time market events from Polymarket WSS
• 🎯 Derived Future Price Event: Implements Polymarket's price calculation logic (midpoint vs last trade price based on spread)
• 🔗 Group Management: Efficiently manages multiple asset subscriptions across connection groups without losing events when subscribing / unsubscribing assets.
• 🔄 Automatic Connection Management: Handles WebSocket connections, reconnections, and cleanup for grouped assetId (i.e. clobTokenId) subscriptions
• 🚦 Rate Limiting: Built-in rate limiting to respect Polymarket API limits
• 💪 TypeScript Support: Full TypeScript definitions for all events and handlers

import {
  WSSubscriptionManager,
  WebSocketHandlers
  } from '@nevuamarkets/poly-websockets';

// Create the subscription manager with your own handlers
const manager = new WSSubscriptionManager({
  onBook: async (events: BookEvent[]) => {
    for (const event of events) {
      console.log('book event', JSON.stringify(event, null, 2))
    }
  },
  onPriceChange: async (events: PriceChangeEvent[]) => {
    for (const event of events) {
      console.log('price change event', JSON.stringify(event, null, 2))
    }
  }
});

// Subscribe to assets
await manager.addSubscriptions(['asset-id-1', 'asset-id-2']);

// Remove subscriptions
await manager.removeSubscriptions(['asset-id-1']);

// Clear all subscriptions and connections
await manager.clearState();

The main class that manages WebSocket connections and subscriptions.

new WSSubscriptionManager(handlers: WebSocketHandlers, options?: SubscriptionManagerOptions)

Parameters:

• handlers - Event handlers for different WebSocket events
• options - Optional configuration object:
  • maxMarketsPerWS?: number - Maximum assets per WebSocket connection (default: 100)
  • reconnectAndCleanupIntervalMs?: number - Interval for reconnection attempts (default: 10s)
  • burstLimiter?: Bottleneck - Custom rate limiter instance. If none is provided, one will be created and used internally in the component.

Adds new asset subscriptions. The manager will:

• Filter out already subscribed assets
• Find available connection groups or create new ones
• Establish WebSocket connections as needed

Removes asset subscriptions. Connections are kept alive to avoid missing events, and unused groups are cleaned up during the next reconnection cycle.

Clears all subscriptions and state:

• Removes all asset subscriptions
• Closes all WebSocket connections
• Clears the internal order book cache

Returns statistics about the current state of the subscription manager:

• openWebSockets: The number of websockets that are currently in OPEN state
• subscribedAssetIds: The number of unique asset IDs that are currently subscribed

Interface defining event handlers for different WebSocket events.

interface WebSocketHandlers {
  // Core Polymarket WebSocket events
  onBook?: (events: BookEvent[]) => Promise<void>;
  onLastTradePrice?: (events: LastTradePriceEvent[]) => Promise<void>;
  onPriceChange?: (events: PriceChangeEvent[]) => Promise<void>;
  onTickSizeChange?: (events: TickSizeChangeEvent[]) => Promise<void>;
  
  // Derived polymarket price update event
  onPolymarketPriceUpdate?: (events: PolymarketPriceUpdateEvent[]) => Promise<void>;
  
  // Connection lifecycle events
  onWSOpen?: (groupId: string, assetIds: string[]) => Promise<void>;
  onWSClose?: (groupId: string, code: number, reason: string) => Promise<void>;
  onError?: (error: Error) => Promise<void>;
}

BookEvent

• See // https://docs.polymarket.com/developers/CLOB/websocket/market-channel#book-message

PriceChangeEvent

• See https://docs.polymarket.com/developers/CLOB/websocket/market-channel#price-change-message

onTickSizeChange

• See https://docs.polymarket.com/developers/CLOB/websocket/market-channel#tick-size-change-message

LastTradePriceEvent

• Currently undocumented, but is emitted when a trade occurs

PolymarketPriceUpdateEvent

• Derived price update following Polymarket's display logic
• Uses midpoint when spread <= $0.10, otherwise uses last trade price
• Includes full order book context

import Bottleneck from 'bottleneck';

const customLimiter = new Bottleneck({
  reservoir: 10,
  reservoirRefreshAmount: 10,
  reservoirRefreshInterval: 1000,
  maxConcurrent: 10
});

const manager = new WSSubscriptionManager(handlers, {
  burstLimiter: customLimiter
});

Check the examples folder for complete working examples

The library includes error handling:

• Automatic reconnection on connection drops
• User-defined error callbacks for custom handling

Respects Polymarket's API rate limits:

• Default: 5 requests per second burst limit
• Configurable through custom Bottleneck instances

AGPL-3

npm test

Full TypeScript definitions included.

This software is provided "as is", without warranty of any kind, express or implied. The author(s) are not responsible for:

• Any financial losses incurred from using this software
• Trading decisions made based on the data provided
• Bugs, errors, or inaccuracies in the data
• System failures or downtime
• Any other damages arising from the use of this software

Use at your own risk. Always verify data independently and never rely solely on automated systems for trading decisions.