WebSocket Streaming

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.

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 when a CLOB market orderbook changes. Contains the full updated 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);
});

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 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)');

Getting Started

Quick Start

TypeScript SDK

Python SDK

Go SDK

Rust SDK

WebSocket

WebSocketClient Setup

Constructor Options

Public Subscriptions

Market Prices

Authenticated Subscriptions

Positions

Order Events

Transactions

Events

orderbookUpdate (CLOB markets)

newPriceData (AMM markets)

positions

tx

Type Definitions

Connection Management

Disconnect handling

Graceful shutdown

Debugging

Full Example

​WebSocketClient Setup

​Constructor Options

​Public Subscriptions

​Market Prices

​Authenticated Subscriptions

​Positions

​Order Events

​Transactions

​Events

​orderbookUpdate (CLOB markets)

​newPriceData (AMM markets)

​positions

​tx

​Type Definitions

​Connection Management

​Disconnect handling

​Graceful shutdown

​Debugging

​Full Example

WebSocketClient Setup

Constructor Options

Public Subscriptions

Market Prices

Authenticated Subscriptions

Positions

Order Events

Transactions

Events

orderbookUpdate (CLOB markets)

newPriceData (AMM markets)

positions

tx

Type Definitions

Connection Management

Disconnect handling

Graceful shutdown

Debugging

Full Example