Streaming

Subscribe to live market context, orderbook updates, fills, and order status via WebSocket

The PerpsWsClient provides streaming data over WebSocket. Connections are made directly to the DEX for lowest latency — the SDK discovers the WebSocket URL from GET /providers automatically.

All incoming data is normalized to the same types used by REST responses, so your application logic works identically whether data comes from a REST call or a WebSocket event.

WebSocket support is provider-specific. Not all channels may be supported by every provider — check the provider’s documentation for available channels.

Setup

import { createPerpsClient, PerpsWsClient } from '@lifi/perps-sdk';
import { hyperliquidWsProvider } from '@lifi/perps-sdk-provider-hyperliquid';

const client = createPerpsClient({ integrator: 'my-app', apiKey: 'your-api-key' });
const ws = new PerpsWsClient(client, {
  wsProviders: { hyperliquid: hyperliquidWsProvider() },
});

The PerpsWsClient lazily initializes connections — no WebSocket is opened until you call subscribe().

Subscribe

subscribe() is async and returns a Promise<() => void> — awaiting it yields the unsubscribe function. The descriptor’s dex field selects the venue (use the key from getProviders(), e.g., 'hyperliquid' or 'lighter').

const unsub = await ws.subscribe(
  { channel: 'orderbook', dex: 'hyperliquid', marketId: 'ETH' },
  (event) => {
    console.log('Best bid:', event.data.bids[0]?.price);
    console.log('Best ask:', event.data.asks[0]?.price);
  }
);

// Later: stop receiving updates
unsub();

subscribe() accepts an optional third argument, onStatus, a listener for the underlying connection’s health. It fires 'reconnecting' on a transient drop and the terminal 'disconnected' once auto-reconnect is abandoned, so consumers can surface a reconnecting/disconnected state instead of silently showing stale data.

const unsub = await ws.subscribe(
  { channel: 'orderbook', dex: 'hyperliquid', marketId: 'ETH' },
  (event) => updateBook(event.data),
  (status) => {
    // status: 'connected' | 'reconnecting' | 'disconnected'
    setConnectionState(status);
  }
);

getQuote

One-shot fill quote for size USD notional of symbol on a single venue: VWAP expected fill, price impact (bps), base-tier taker fee, and funding (perps only). This is a plain request/response service (not a WS subscription) — the streaming counterpart is subscribeQuote, and both share the GetQuoteParams shape. Cross-venue comparison is a consumer-side loop over client.providers.

import { getQuote } from '@lifi/perps-sdk';

const quote = await getQuote(client, {
  provider: 'hyperliquid',
  symbol: 'BTC',
  side: 'buy',
  size: 10_000,
  type: 'perps',
});
console.log(quote.expectedFillPrice, quote.priceImpactBps);

GetQuoteParams:

Field	Type	Description
provider	string	Provider identifier
symbol	string	Display symbol, e.g. "BTC"
side	QuoteSide	'buy' | 'sell'
size	number	USD notional to fill
type	TradeType	'perps' | 'spot'

Throws a PerpsError when the provider plugin is not registered, no market matches the symbol and type, or on network / parsing errors.

subscribeQuote

Stream live fill quotes for a market. The provider’s WS plugin layers the quote on its orderbook channel, so a concurrent orderbook subscription on the same market shares a single wire subscription. Async; returns a Promise<() => void> unsubscribe function.

const unsub = await ws.subscribeQuote(
  { provider: 'hyperliquid', symbol: 'BTC', side: 'buy', size: 10_000, type: 'perps' },
  (quote) => {
    console.log('Expected fill price:', quote.expectedFillPrice);
    console.log('Price impact (bps):', quote.priceImpactBps);
  }
);

Parameter	Type	Description
params	GetQuoteParams	{ provider, symbol, side, size, type } — symbol is the display symbol (e.g. "BTC"), side is 'buy' | 'sell', size is the USD notional as a number, type is 'perps' | 'spot'
onQuote	QuoteListener	Called with each Quote update

Throws a PerpsError when no WS provider factory is registered for params.provider, or no market matches the symbol and type.

Available Channels

marketsContext

Full context for every market on the DEX, keyed by marketId. Use this when a UI needs mark price, oracle price, 24h volume, open interest, or funding for the whole market list.

await ws.subscribe(
  { channel: 'marketsContext', dex: 'hyperliquid' },
  (event) => {
    // event.data: Record<string, MarketContext> — marketId -> context
    const btc = event.data['BTC'];
    console.log('BTC mark:', btc?.markPrice);
    console.log('BTC funding:', btc?.funding?.rate);
  }
);

marketContext

Full context for a specific market. The event data is a MarketContext snapshot, so consumers should replace their cached context for that market when a new event arrives.

await ws.subscribe(
  { channel: 'marketContext', dex: 'hyperliquid', marketId: 'BTC' },
  (event) => {
    // event.data: MarketContext
    console.log('Mark:', event.data.markPrice);
    console.log('Oracle:', event.data.oraclePrice);
    console.log('24h volume:', event.data.volume24h);
  }
);

orderbook

L2 orderbook for a specific market. Fires on every book update. Pass an optional depth to limit price levels (provider default if omitted), and an optional priceStep to request a price granularity — the desired bucket width in quote currency (e.g. 10 buckets a BTC book into $10-wide levels). Providers that aggregate the book server-side honour priceStep best-effort; providers that stream the full book ignore it, and undefined requests full precision.

await ws.subscribe(
  { channel: 'orderbook', dex: 'hyperliquid', marketId: 'BTC', depth: 5, priceStep: 10 },
  (event) => {
    // event.data: OrderbookResponse — { bids, asks, timestamp, ... }
    const spread = Number(event.data.asks[0].price) - Number(event.data.bids[0].price);
    console.log('Spread:', spread);
  }
);

candle

OHLCV candle updates for a specific market and interval.

await ws.subscribe(
  { channel: 'candle', dex: 'hyperliquid', marketId: 'BTC', interval: '1h' },
  (event) => {
    // event.data: Candle — { t, o, h, l, c, v }
    console.log('Close:', event.data.c);
  }
);

trades

Public trade prints for a specific market. Fires as trades execute on the venue.

await ws.subscribe(
  { channel: 'trades', dex: 'hyperliquid', marketId: 'BTC' },
  (event) => {
    // event.data: Trade[] — { provider, marketId, price, size, side, timestamp, id? }
    // `side` is the taker (aggressor) side: 'buy' or 'sell'.
    for (const trade of event.data) {
      console.log(trade.side, trade.size, '@', trade.price);
    }
  }
);

orderUpdates

Live order status changes for a user’s orders. Requires the user’s wallet address.

await ws.subscribe(
  { channel: 'orderUpdates', dex: 'hyperliquid', address: '0x...' },
  (event) => {
    // event.data: { openOrders: OpenOrder[]; triggerOrders: TriggerOrder[]; terminated: string[] }
    // openOrders / triggerOrders are upserts; terminated lists orderIds that
    // just reached a terminal status — evict them from both buckets.
    for (const order of event.data.openOrders) {
      console.log(order.orderId, order.filledSize);
    }
    for (const orderId of event.data.terminated) {
      console.log('terminated:', orderId);
    }
  }
);

fills

Live fill notifications for a user’s trades.

await ws.subscribe(
  { channel: 'fills', dex: 'hyperliquid', address: '0x...' },
  (event) => {
    // event.data: Fill[]
    for (const fill of event.data) {
      console.log(fill.market.baseAsset.displaySymbol, fill.side, fill.size, '@', fill.price);
    }
  }
);

positions

Live position updates for a user.

await ws.subscribe(
  { channel: 'positions', dex: 'hyperliquid', address: '0x...' },
  (event) => {
    // event.data: Position[]
    for (const pos of event.data) {
      console.log(pos.market.baseAsset.displaySymbol, pos.side, pos.size, 'PnL:', pos.unrealizedPnl);
    }
  }
);

spotBalances

Live spot balance updates for a user (e.g., USDC collateral held on the DEX).

await ws.subscribe(
  { channel: 'spotBalances', dex: 'hyperliquid', address: '0x...' },
  (event) => {
    // event.data: (Balance & { locked: string })[] — { categoryId, asset, units, valueUsd, locked }
    for (const bal of event.data) {
      console.log(bal.asset.displaySymbol, 'units:', bal.units, 'locked:', bal.locked);
    }
  }
);

accountSummary

Live account roll-up for a user — portfolio value, available margin, margin used, and unrealized PnL. Requires the user’s wallet address. Field coverage matches the venue’s own stream (e.g. Hyperliquid’s portfolioValue covers perps equity only; spot balances have their own spotBalances channel).

await ws.subscribe(
  { channel: 'accountSummary', dex: 'hyperliquid', address: '0x...' },
  (event) => {
    // event.data: AccountSummary
    //   { portfolioValue, availableMargin, marginUsed, unrealizedPnl } — decimal strings
    console.log('Portfolio value:', event.data.portfolioValue);
    console.log('Available margin:', event.data.availableMargin);
  }
);

Multiple Subscriptions

You can subscribe to multiple channels simultaneously. Each returns an independent unsubscribe function.

const unsubMarketContext = await ws.subscribe(
  { channel: 'marketsContext', dex: 'hyperliquid' },
  (event) => updateMarketContextDisplay(event.data)
);

const unsubBook = await ws.subscribe(
  { channel: 'orderbook', dex: 'hyperliquid', marketId: 'BTC' },
  (event) => updateOrderbookDisplay(event.data)
);

const unsubOrders = await ws.subscribe(
  { channel: 'orderUpdates', dex: 'hyperliquid', address: userAddress },
  (event) => updateOrdersDisplay(event.data)
);

// Unsubscribe individually
unsubBook();

// Or close everything at once
ws.close();

Connection Lifecycle

• Lazy connection — The WebSocket connects on the first subscribe() call for each DEX
• Automatic reconnection — Jittered exponential backoff on disconnect. The first-retry delay is drawn once per socket from [500, 1500)ms (to de-synchronize reconnect storms) and grows exponentially, capped at 10s. After 10 attempts the socket is declared disconnected.
• Resubscription — All active subscriptions are automatically re-sent after reconnection
• Keepalive — 30-second ping/pong heartbeat to detect stale connections
• Refcounted — Duplicate subscriptions to the same channel are deduplicated; the upstream subscription is removed only when the last listener unsubscribes
• Manual reconnect — ws.reconnect(provider) forces an already-created provider whose socket reached terminal disconnected to reconnect with a fresh retry budget. It is a safe no-op when the provider is unknown or not terminal.

Cleanup

Always close the client when you’re done to release WebSocket connections:

// Close all connections and subscriptions
ws.close();

Individual subscriptions can be cleaned up by calling the returned unsubscribe function. The underlying WebSocket connection stays open as long as at least one subscription is active on that DEX.

Type Safety

The subscribe method is fully typed — the callback receives the correct event type based on the subscription channel:

// TypeScript knows event.data is Record<string, MarketContext>
await ws.subscribe({ channel: 'marketsContext', dex: 'hyperliquid' }, (event) => {
  event.data; // Record<string, MarketContext> — no cast needed
});

// TypeScript knows event.data is OrderbookResponse
await ws.subscribe({ channel: 'orderbook', dex: 'hyperliquid', marketId: 'BTC' }, (event) => {
  event.data.bids; // OrderbookLevel[] — no cast needed
});