WebSocket Protocol

Lighter-native WebSocket protocol, channel mapping, and authenticated subscriptions

Each Lighter deployment advertises its native WebSocket endpoint through Provider.wsUrl: lighter uses the mainnet stream and lighter-rh uses the Robinhood stream. The same lighterWsProvider() factory binds to that provider-specific stream URL. For lighter-rh, also pass LIGHTER_RH_REST_URL so address-to-account-index lookups use the matching deployment. If you’re using normalized SDK channels, see Streaming.

​

SDK Channel Mapping

The SDK’s LighterWsProvider maps between normalized channel names and Lighter-native channels:

SDK channel	Lighter channel	Auth required	SDK event type
marketsContext	market_stats/all, spot_market_stats/all	No	Record<string, MarketContext>
marketContext	market_stats/<market_id>, spot_market_stats/<market_id>	No	MarketContext
orderbook	order_book/<market_id>	No	OrderbookResponse
trades	trade/<market_id>	No	Trade[]
orderUpdates	account_all_orders/<account_index>	Yes	{ orders: Order[]; terminated: string[] }
fills	account_all_trades/<account_index>	No	Fill[]
positions	account_all_positions/<account_index>	Yes	Position[]
accountSummary	user_stats/<account_index>, plus account_all_assets/<account_index> (needs a token) when a token resolves, else the public account_all/<account_index>	No	AccountSummary

Lighter has no candle, spotBalances, or availableToTrade channel. Subscribing to any of them rejects with Lighter WS does not support channel. Check ws.streamsCandles('lighter') and ws.streamsAvailableToTrade('lighter') (both false) before subscribing, and render charts from REST history plus marketContext ticks.

For orderUpdates, orders holds upserts of any status (terminal rows included) and terminated lists the order ids to evict.

​

Authenticated channels

orderUpdates and positions require a Lighter auth token on every subscribe and reconnect. fills and accountSummary are publicly readable. When the matching REST plugin is registered on the same SDK client, the WebSocket provider automatically calls that plugin’s resolveAuthToken; no token callback or separate key store is needed.

import { createPerpsClient, PerpsWsClient } from '@lifi/perps-sdk';
import {
  lighterProvider,
  lighterRhProvider,
  LIGHTER_RH_REST_URL,
  lighterWsProvider,
} from '@lifi/perps-sdk-provider-lighter';

const sdkClient = createPerpsClient({
  apiKey: 'your-api-key',
  providers: [lighterProvider(), lighterRhProvider()],
});

const ws = new PerpsWsClient(sdkClient, {
  wsProviders: {
    lighter: lighterWsProvider(),
    'lighter-rh': lighterWsProvider({ restUrl: LIGHTER_RH_REST_URL }),
  },
});

await ws.subscribe(
  { channel: 'orderUpdates', dex: 'lighter-rh', address: userAddress },
  (event) => console.log(event.data),
);

Pass resolveAuthToken to lighterWsProvider({ resolveAuthToken }) only when constructing a standalone WebSocket client without the corresponding lighterProvider() or lighterRhProvider() on the same PerpsSDKClient. When the resolver yields no token, subscribe on orderUpdates or positions throws SetupRequired, the same code the REST reads throw. When neither source is wired, it throws SDKError — a wiring defect, not an account state. See Account access.

orderUpdates, fills, positions and accountSummary each resolve the Lighter account index before the channel opens, so every one throws AccountNotFound at subscribe time for a wallet with no Lighter account — including fills and accountSummary, which need no token. See Account access.

​

Keepalive

The SDK sends a ping frame every 30 seconds to keep the connection alive.

​

Per-subscription dex field

When subscribing across providers, the per-subscription field that selects the venue is named dex (not provider). Use lighter for mainnet or lighter-rh for the Robinhood deployment.