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 provider for lowest latency — the SDK discovers the WebSocket URL from GET /providers automatically.

All incoming data is normalized to the same types used by the account and market reads, so your application logic works identically whether data comes from a read or a WebSocket event.

WebSocket support is provider-specific. Not every provider serves every channel — see Channel support and check ws.streamsCandles() / ws.streamsAvailableToTrade() before subscribing.

​

Setup

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

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

Register only the providers you use. See Lighter WebSocket for lighter-rh and Ondo WebSocket for the authenticated channels.

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

If you trade with a PerpsClient, build the PerpsWsClient from its low-level client: new PerpsWsClient(perps.client, { wsProviders }). Lighter and Ondo resolve their auth tokens from the providers registered on that client.

ws.close() is terminal. Afterwards subscribe() and subscribeQuote() reject with an SDKError (“PerpsWsClient is closed”). Create the client once, close it only when the app shuts down, and create a new instance to subscribe again.

​

Subscribe

subscribe() is async and returns a Promise<() => void> — awaiting it yields the unsubscribe function. The descriptor’s dex field holds the provider key — the key from getProviders(), e.g., 'hyperliquid' or 'lighter'. dex is the literal field name; the value is always a provider key.

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) => console.log('Bids:', event.data.bids.length),
  (status) => {
    // status: 'connected' | 'reconnecting' | 'disconnected'
    console.log('Connection:', status);
  }
);

The exported types WsConnectionStatus ('connected' | 'reconnecting' | 'disconnected'), WsStatusListener (the onStatus callback) and EventForSubscription<S> (the event type for a subscription descriptor S) come from @lifi/perps-sdk.

subscribe() resolves only after the channel is open. If a component unmounts before the promise resolves, call the unsubscribe function as soon as it arrives:

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

function watchOrderbook(ws: PerpsWsClient, marketId: string, onBook: (bids: number) => void) {
  let cancelled = false;
  let unsub: (() => void) | undefined;

  ws.subscribe({ channel: 'orderbook', dex: 'hyperliquid', marketId }, (event) =>
    onBook(event.data.bids.length)
  ).then((fn) => {
    if (cancelled) fn();
    else unsub = fn;
  });

  return () => {
    cancelled = true;
    unsub?.();
  };
}

Unsupported channels and providers without a WebSocket URL reject with a plain Error (no PerpsErrorCode). A provider key with no registered factory rejects with a PerpsError.

​

Channel support

Channel	Hyperliquid	Lighter	Ondo
marketsContext	Yes	Yes	Yes
marketContext	Yes	Yes	Yes
orderbook	Yes	Yes	Yes
trades	Yes	Yes	Yes
candle	Yes	No (rejects)	Yes
orderUpdates	Yes	Yes	Yes
fills	Yes	Yes	Yes
positions	Yes	Yes	Yes
accountSummary	Yes	Yes	Yes
spotBalances	Yes	No (rejects)	Accepted; emits one empty snapshot
availableToTrade	Yes	No (rejects)	No (rejects)

A rejected subscription fails with "<Provider> WS does not support channel: <channel>.". The synchronous probes read the registered factory, make no network call, and return false when no factory is registered for the provider:

if (ws.streamsCandles('lighter')) {
  // subscribe to the candle channel
}
const canStreamAvailable = ws.streamsAvailableToTrade('hyperliquid'); // boolean

​

Available Channels

​

marketsContext

Full context for every market on the provider, 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 updates for a user’s orders. Requires the user’s wallet address.

await ws.subscribe(
  { channel: 'orderUpdates', dex: 'hyperliquid', address: userAddress },
  (event) => {
    // event.data: { orders: Order[]; terminated: string[] }
    // orders are upserts of any kind (regular, trigger, TWAP — discriminate on
    // order.type) and may include terminal statuses; terminated lists the
    // orderIds that just reached a terminal status — evict them from your cache.
    for (const order of event.data.orders) {
      console.log(order.orderId, order.status, order.filledSize);
    }
    for (const orderId of event.data.terminated) {
      console.log('terminated:', orderId);
    }
  }
);

​

fills

Live fill notifications for a user’s trades. The first frame can be empty (the subscribe snapshot).

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

​

positions

Live positions for a user. Each frame is the complete set of open positions: replace your state, never merge. A closed position is the market’s absence from the next frame.

await ws.subscribe(
  { channel: 'positions', dex: 'hyperliquid', address: userAddress },
  (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 venue).

await ws.subscribe(
  { channel: 'spotBalances', dex: 'hyperliquid', address: userAddress },
  (event) => {
    // event.data: (Balance & { locked: string; transferable: string })[] — { categoryId, asset, units, valueUsd, price?, transferable, 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: userAddress },
  (event) => {
    // event.data: AccountSummary
    //   { portfolioValue, availableMargin, marginUsed, unrealizedPnl } — decimal strings
    console.log('Portfolio value:', event.data.portfolioValue);
    console.log('Available margin:', event.data.availableMargin);
  }
);

​

availableToTrade

Live per-market available-to-trade updates for a user — the amount the account can still buy and sell on one market. The venue recomputes both sides whenever the account’s margin or position changes. Hyperliquid is the only provider that streams this channel; on Lighter and Ondo the subscription rejects.

await ws.subscribe(
  { channel: 'availableToTrade', dex: 'hyperliquid', address: '0x...', marketId: 'BTC' },
  (event) => {
    // event.data: AvailableToTrade — { providerId, marketId, asset, buy, sell }
    console.log('Buy:', event.data.buy, 'Sell:', event.data.sell);
  }
);

​

Quotes

​

getQuote

One-shot fill quote for size USD notional of symbol on a single provider: VWAP expected fill, price impact (bps), base-tier taker fee, and funding (perps only). getQuote 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 the providers from getProviders().

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

const quote = await getQuote(client, {
  provider: 'hyperliquid',
  symbol: 'BTC',
  side: 'buy',
  size: '10000',
  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	string	USD notional to fill, as a DecimalString
type	TradeType	'perps' | 'spot'

Throws a PerpsError when the provider plugin is not registered or on network / parsing errors. It throws MarketNotFound (see Error Codes) both when no market matches the symbol and type and when the market is known but the provider returned no live price for it.

Quote fields:

Field	Type	Description
provider	string	Provider identifier
symbol	string	Display symbol the quote resolved against
marketId	string	Resolved Market.id
type	TradeType	'perps' | 'spot'
side	QuoteSide	'buy' | 'sell'
sizeUsd	string	Input notional in USD
baseSize	string	Base amount the book filled for sizeUsd
markPrice	string	Mark price
expectedFillPrice	string	Volume-weighted average fill price from the book walk
priceImpactBps	string	Deviation of the fill from markPrice in basis points; non-negative
feeTier	FeeTier	Base maker/taker fee fractions (not bps)
isDefaultFeeTier	boolean	Always true: quotes use the public base tier
feeUsd	string	Taker fee on the filled notional in USD
funding	FundingInfo | null	Current funding for perps; null for spot
insufficientLiquidity	boolean	true when the book could not fill the full sizeUsd
timestamp	number	Unix milliseconds

​

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: '10000', 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 DecimalString, type is 'perps' | 'spot'
onQuote	QuoteListener	Called with each Quote update

onQuote is a QuoteListener: (quote: Quote) => void. subscribeQuote throws a PerpsError when no WS provider factory is registered for params.provider, and MarketNotFound when no market matches the symbol and type.

​

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) => console.log('Markets:', Object.keys(event.data).length)
);

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

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

// Unsubscribe individually
unsubBook();

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

​

Connection Lifecycle

• Lazy connection — The WebSocket connects on the first subscribe() call for each provider
• 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 — A ping every 30 seconds, for providers that define a ping payload (all three shipped providers do). If no inbound frame arrives within three ping intervals (90 seconds), the stale-stream watchdog forces a reconnect.
• Connect timeout and send buffer — A connection attempt times out after 4 seconds. Messages sent while the socket is not open are buffered, up to 1000, and replayed on open.
• 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. subscribe() also re-arms a terminal socket, so a new subscribe() call revives it.

​

Reads lag writes

A venue’s account, order and fill reads can return pre-write data for a couple of seconds after a write (order placement, updateLeverage, sendAsset, margin updates). A refetch started before a stream frame arrives can also overwrite that newer frame. Apply the write optimistically, let stream frames replace state, and re-read once after a short delay rather than immediately.

​

Cleanup

Close the client when the app shuts down to release WebSocket connections. close() is terminal — see Setup.

// 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 provider.

​

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

​

Exported types

@lifi/perps-types exports Subscription and SubscriptionEvent, the unions of every channel. It also exports one subscription type and one event type for each channel: MarketsContextSubscription and MarketsContextEvent, then MarketContext*, Orderbook*, Candle*, Trades*, OrderUpdates*, Fills*, Positions*, SpotBalances*, AccountSummary*, and AvailableToTrade* in the same pattern. ProviderId is a plain string. MetaProvider is the type of the constant META_PROVIDER ('meta').