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,
});

await ws.connect();

Samples use top-level await (ESM). In CommonJS wrap them in an async function.

Constructor options

Option	Type	Default	Description
`url`	`string`	`wss://ws.limitless.exchange`	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; on 1.1.0 it does not re-sign on reconnect (see Connection management).
`apiKey`	`string`	—	Legacy `X-API-Key` auth; ignored when `hmacCredentials` is set
`reconnectDelay`	`number`	`1000`	Initial reconnect delay, ms (backs off to 60 s)
`maxReconnectAttempts`	`number`	`Infinity`	Give up after this many attempts
`timeout`	`number`	`10000`	Connect timeout, ms

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

await ws.connect();

await 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. To stop receiving a market, re-send subscribe_market_prices with the remaining set. The only server-side unsubscribe is unsubscribe_market_lifecycle, sent through subscribe(); ws.unsubscribe() emits a generic unsubscribe event the server does not handle, so it rejects after its 5 second ack timeout.

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.

The server re-validates the handshake signature on every authenticated subscribe call and accepts lmts-timestamp values at most 30 seconds old. Issue subscribe_positions, subscribe_order_events and subscribe_transactions immediately after connect(); to subscribe later, call await ws.disconnect(); await ws.connect(); first so the handshake is re-signed.

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

await ws.connect();

Positions

Subscribe to real-time updates when your positions change:

await ws.subscribe('subscribe_positions', {
  marketSlugs: ['btc-100k-weekly'],
  marketAddresses: ['0x1234...'],
});

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

subscribe_positions requires marketSlugs and/or marketAddresses; a call without them is ignored by the server (no ack, no error). It has replace semantics like subscribe_market_prices.

Order events

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

await 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, and EXECUTION, the terminal frame for FAK/FOK orders (status FILLED, PARTIALLY_FILLED or KILLED); on this frame price and remainingSize are strings in raw 6-decimal units.
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:

await ws.subscribe('subscribe_transactions');

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

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) => {
  const prices = Array.isArray(data.updatedPrices) ? data.updatedPrices : [data.updatedPrices];
  for (const p of prices) {
    console.log(data.marketAddress, 'YES:', p.yesPrice, 'NO:', p.noPrice);
  }
});

The first newPriceData after subscribe_market_prices is a snapshot whose updatedPrices is a single object (with collateralDecimals) rather than an array; the sample above normalises it with Array.isArray.

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.txHash);
  console.log('Status:', data.status);
});

Type definitions

interface OrderbookUpdate {
  marketSlug: string;
  version: number;                    // monotonic per market; drop frames with version <= last seen
  timestamp: string;
  orderbook: {
    bids: { price: number; size: number; side: 'BUY' }[];   // size: raw 6-decimal units, 1 share = 1,000,000
    asks: { price: number; size: number; side: 'SELL' }[];  // size: raw 6-decimal units, 1 share = 1,000,000
    tokenId: string;
    adjustedMidpoint: number;
    midpoint: number;
    maxSpread: number;
    minSize: number;                  // same raw 6-decimal units as size
  };
}

interface NewPriceData {
  marketAddress: string;
  updatedPrices: { marketId: number; marketAddress: string; yesPrice: number; noPrice: number }[];
  blockNumber: number;
  timestamp: string;
}

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

// One frame per market.
type PositionEvent =
  | {
      type: 'CLOB';
      account: string;
      marketSlug: string;
      tokenIds: string[];
      positions: Array<{
        tokenId: string;
        marketId: number | string;
        ctfBalance: string;        // shares, 6-decimal integer string
        marketValue: string;
        averageFillPrice: string;
        costBasis: string;
      }>;
      timestamp?: string;          // live frames only
    }
  | { type: 'AMM'; account: string; marketAddress: string; positions: unknown[] };

type OrderEvent = OmeOrderEvent | SettlementOrderEvent;

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

interface OmeExecutionOrderEvent {
  source: 'OME';
  type: 'EXECUTION';
  status: 'FILLED' | 'PARTIALLY_FILLED' | 'KILLED';
  eventId: string;
  orderId: string;
  userId: number;
  marketId: string;
  token: string;
  side: 'BUY' | 'SELL';
  price: string;
  remainingSize: string;
  occurredAt?: string | null;
  publishedAt?: string;
  timestamp: string;
}

type OmeOrderEvent = OmeLifecycleOrderEvent | OmeExecutionOrderEvent;

interface SettlementOrderEvent {
  source: 'SETTLEMENT';
  type: 'MATCHED' | '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;
  feeAmountCollateral?: string;
  isEstimate?: boolean;          // true on MATCHED frames: fee fields are estimates
  matchedAt?: string | null;
  occurredAt?: string | null;
  publishedAt?: string;
  txHash?: string;
  timestamp: string;
}

interface TransactionEvent {
  txHash?: string;
  status: 'CONFIRMED' | 'FAILED';
  source: string;
  timestamp: string;
  marketAddress?: string;
  marketSlug?: string;
  tokenId?: string;
  conditionId?: string;
  amountContracts?: string;
  amountCollateral?: string;
  price?: string;
  side?: 'BUY' | 'SELL';
  orderId?: string;
  clientOrderId?: string;
  tradeEventId?: string;
}

Connection management

Disconnect handling

Listen for disconnections and clean up resources:

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

When autoReconnect is enabled the client reconnects on its own. WebSocketClient exposes no reconnect event; its connection events are connect, disconnect and error. On SDK 1.1.0 an automatic reconnect does not restore any subscription, public or authenticated, and authenticated channels are rejected with Invalid HMAC authentication because the original handshake signature is replayed. To survive a drop, listen for disconnect, call await ws.disconnect(); await ws.connect(); and re-issue your subscribe() calls. The SDK main branch re-signs the handshake and re-subscribes automatically; that fix is not yet published to npm.

Graceful shutdown

Clean up the WebSocket connection on process exit:

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

Debugging

WebSocketClient has no catch-all listener in 1.1.0 (there is no onAny). Log the events you care about one by one; system carries server-side messages:

for (const event of ['orderbookUpdate', 'newPriceData', 'orderEvent', 'positions', 'tx', 'system'] as const) {
  ws.on(event, (data: unknown) => console.log(`[WS] ${event}:`, JSON.stringify(data, 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,
});

await ws.connect();

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

await ws.subscribe('subscribe_positions', { marketSlugs: ['btc-100k-weekly'] });
await ws.subscribe('subscribe_order_events');
await 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.txHash} ${data.status}`);
});

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

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)

oraclePriceData

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)

​oraclePriceData

​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)

oraclePriceData

positions

tx

Type definitions

Connection management

Disconnect handling

Graceful shutdown

Debugging

Full example