WebSocket Streaming

Real-time market data and position updates with the TypeScript SDK

WebSocketClient setup

The WebSocketClient connects to the Limitless Exchange WebSocket server for real-time market data, position updates, order lifecycle events, and transaction notifications.

import { WebSocketClient } from '@limitless-exchange/sdk';

const ws = new WebSocketClient({
  url: 'wss://ws.limitless.exchange',
  autoReconnect: true,
});

ws.connect();

Constructor options

Option	Type	Default	Description
url	string	—	WebSocket server URL
autoReconnect	boolean	true	Automatically reconnect on disconnection
hmacCredentials	{ tokenId, secret }	—	Required for authenticated subscriptions (positions, order events, transactions). The SDK signs the handshake automatically.

Public subscriptions (market prices) do not require authentication. Authenticated subscriptions (positions, order events, transactions) require hmacCredentials — see Authentication to generate a token.

Public subscriptions

Market prices

Subscribe to real-time price updates for one or more markets. No authentication required.

const ws = new WebSocketClient({
  url: 'wss://ws.limitless.exchange',
});

ws.connect();

ws.subscribe('subscribe_market_prices', {
  marketSlugs: ['btc-100k-weekly', 'eth-5k-daily'],
  marketAddresses: ['0x1234...'], // For AMM markets
});

Subscriptions replace previous ones. To listen to both CLOB (by slug) and AMM (by address) markets, include both marketSlugs and marketAddresses in a single subscribe_market_prices call.

The server answers every subscribe_market_prices call, first or repeat, with one orderbookUpdate per CLOB slug carrying the full current book, including books with empty bids and asks. You do not need a REST call to seed local state. See Initial snapshot.

Authenticated subscriptions

These subscriptions require hmacCredentials passed to the constructor. The SDK signs the WebSocket handshake automatically.

const ws = new WebSocketClient({
  url: 'wss://ws.limitless.exchange',
  hmacCredentials: {
    tokenId: process.env.LMTS_TOKEN_ID,
    secret: process.env.LMTS_TOKEN_SECRET,
  },
});

ws.connect();

Positions

Subscribe to real-time updates when your positions change:

ws.subscribe('subscribe_positions');

ws.on('positions', (data) => {
  console.log('Position update:', data);
});

Order events

Subscribe to CLOB order lifecycle and settlement events for your account:

ws.subscribe('subscribe_order_events');

ws.on('orderEvent', (event: OrderEvent) => {
  if (event.source === 'OME') {
    console.log('Order state:', event.type, event.orderId, event.clientOrderId);
  } else {
    console.log('Settlement:', event.type, event.orderId, event.clientOrderId, event.txHash);
  }
});

orderEvent uses source as a discriminator:

• source: 'OME' — off-chain order state changes: placement, update, cancellation.
• source: 'SETTLEMENT' — on-chain settlement results for the taker order and each matched maker order.

For settlement events, clientOrderId is the id of the recipient’s own orderId. If only one side of a trade supplied a clientOrderId, only that side’s event includes it. Counterparty order ids inside takerOrderId or makerMatches[] are not resolved to client ids.

Transactions

Subscribe to transaction confirmations:

ws.subscribe('subscribe_transactions');

ws.on('tx', (data) => {
  console.log('Transaction:', data.hash, data.status);
});

Events

orderbookUpdate (CLOB markets)

Fired once per slug right after you subscribe, then whenever a CLOB market orderbook changes. Contains the full current orderbook.

ws.on('orderbookUpdate', (data: OrderbookUpdate) => {
  console.log('Market:', data.marketSlug);
  console.log('Bids:', data.orderbook.bids.length);
  console.log('Asks:', data.orderbook.asks.length);

  if (data.orderbook.bids.length > 0 && data.orderbook.asks.length > 0) {
    const spread = data.orderbook.asks[0].price - data.orderbook.bids[0].price;
    console.log('Spread:', spread.toFixed(4));
  }
});

newPriceData (AMM markets)

Fired when AMM market prices update.

ws.on('newPriceData', (data: NewPriceData) => {
  console.log('Market:', data.marketAddress);
  console.log('YES:', data.updatedPrices.yes);
  console.log('NO:', data.updatedPrices.no);
});

oraclePriceData

Fired when the oracle backing a subscribed market publishes a new price (e.g. Chainlink, Pyth). Delivered on the same subscribe_market_prices channel as orderbookUpdate and newPriceData, so no separate subscription is required.

ws.on('oraclePriceData', (data: OraclePriceData) => {
  console.log('Market:', data.marketSlug);
  console.log('Oracle value:', data.value);
  console.log('At (ms):', data.timestamp);
});

OraclePriceData fields: marketAddress (nullable), marketSlug, timestamp (unix ms), value (number).

positions

Fired when any of your positions change (fill, cancel, resolution).

ws.on('positions', (data: PositionEvent) => {
  console.log('Updated positions:', data);
});

tx

Fired on transaction events related to your account.

ws.on('tx', (data: TransactionEvent) => {
  console.log('Tx hash:', data.hash);
  console.log('Status:', data.status);
});

Type definitions

interface OrderbookUpdate {
  marketSlug: string;
  orderbook: {
    bids: { price: number; size: number }[];
    asks: { price: number; size: number }[];
  };
}

interface NewPriceData {
  marketAddress: string;
  updatedPrices: {
    yes: string;
    no: string;
  };
}

interface OraclePriceData {
  marketAddress: string | null;
  marketSlug: string;
  timestamp: number;
  value: number;
}

interface PositionEvent {
  clob: Array<{
    market: { slug: string };
    positions: {
      yes: { size: number; collateral: number };
      no: { size: number; collateral: number };
    };
  }>;
}

type OrderEvent = OmeOrderEvent | SettlementOrderEvent;

interface OmeOrderEvent {
  source: 'OME';
  type: 'PLACEMENT' | 'UPDATE' | 'CANCELLATION';
  eventId: number;
  orderId: string;
  clientOrderId?: string;
  userId: number;
  marketId: string;
  token: string;
  side: 'BUY' | 'SELL';
  price: string;
  remainingSize: string;
  timestamp: string;
}

interface SettlementOrderEvent {
  source: 'SETTLEMENT';
  type: 'MINED' | 'FAILED';
  eventId: string;
  tradeEventId: string;
  orderId?: string;
  clientOrderId?: string;
  takerOrderId?: string;
  takerAccount?: string;
  makerMatches?: Array<{
    account: string;
    orderId: string;
    matchedSize: string;
    price: string;
  }>;
  marketSlug?: string;
  tokenId?: string;
  side?: 'BUY' | 'SELL';
  price?: string;
  amountContracts?: string;
  amountCollateral?: string;
  configuredFeeRateBps?: number;
  effectiveFeeBps?: number;
  feeAmountContracts?: string;
  txHash?: string;
  timestamp: string;
}

interface TransactionEvent {
  hash: string;
  status: 'pending' | 'confirmed' | 'failed';
  type: string;
}

Connection management

Disconnect handling

Listen for disconnections and clean up resources:

ws.on('disconnect', (reason: string) => {
  console.log('Disconnected:', reason);
});

ws.on('reconnect', () => {
  console.log('Reconnected — resubscribing...');

  ws.subscribe('subscribe_market_prices', {
    marketSlugs: ['btc-100k-weekly'],
  });
});

When autoReconnect is enabled, the client automatically attempts to reconnect. However, you must re-send your subscriptions after reconnection. Listen for the reconnect event to resubscribe.

Graceful shutdown

Clean up the WebSocket connection on process exit:

process.on('SIGINT', () => {
  console.log('Shutting down...');
  ws.disconnect();
  process.exit(0);
});

Debugging

Log all raw events to inspect the data the server sends:

ws.onAny((eventName: string, ...args: unknown[]) => {
  console.log(`[WS] ${eventName}:`, JSON.stringify(args, null, 2));
});

Use raw event logging during development to discover event shapes and debug subscription issues. Remove it before deploying to production.

Full example

A complete script that subscribes to market prices and positions:

import { WebSocketClient } from '@limitless-exchange/sdk';

const ws = new WebSocketClient({
  url: 'wss://ws.limitless.exchange',
  hmacCredentials: {
    tokenId: process.env.LMTS_TOKEN_ID,
    secret: process.env.LMTS_TOKEN_SECRET,
  },
  autoReconnect: true,
});

ws.connect();

ws.subscribe('subscribe_market_prices', {
  marketSlugs: ['btc-100k-weekly'],
});

ws.subscribe('subscribe_positions');
ws.subscribe('subscribe_order_events');
ws.subscribe('subscribe_transactions');

ws.on('orderbookUpdate', (data) => {
  const best_bid = data.orderbook.bids[0];
  const best_ask = data.orderbook.asks[0];
  console.log(`[${data.marketSlug}] Bid: ${best_bid?.price ?? '-'} | Ask: ${best_ask?.price ?? '-'}`);
});

ws.on('positions', (data) => {
  console.log('[Positions]', JSON.stringify(data));
});

ws.on('orderEvent', (event) => {
  console.log('[OrderEvent]', event.source, event.type, event.orderId, event.clientOrderId ?? '(no client id)');
});

ws.on('tx', (data) => {
  console.log(`[Tx] ${data.hash} — ${data.status}`);
});

ws.on('disconnect', (reason) => {
  console.log('[Disconnected]', reason);
});

ws.on('reconnect', () => {
  ws.subscribe('subscribe_market_prices', {
    marketSlugs: ['btc-100k-weekly'],
  });
  ws.subscribe('subscribe_positions');
  ws.subscribe('subscribe_order_events');
  ws.subscribe('subscribe_transactions');
});

process.on('SIGINT', () => {
  ws.disconnect();
  process.exit(0);
});

console.log('Listening for events... (Ctrl+C to stop)');