WebSocket Protocol

Ondo’s native WebSocket endpoint and how the SDK discovers it

Ondo exposes a native WebSocket endpoint at wss://api.ondoperps.xyz/ws. The SDK discovers this URL from the wsUrl field in the GET /providers response. If you’re using the SDK, subscribe through Streaming rather than connecting to the endpoint directly.

​

Per-subscription dex field

When subscribing across providers, the per-subscription field that selects the venue is named dex (not provider). For Ondo the value is ondo.

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

declare const ws: PerpsWsClient;

await ws.subscribe(
  { channel: 'orderbook', dex: 'ondo', marketId: 'BTC-USD.P' },
  (event) => {
    // event.data: orderbook snapshot / updates
  }
);

See SDK / Streaming for the full list of normalized channels and the subscription lifecycle.

​

Channel mapping

The SDK maps each normalized channel to Ondo’s wire channel name:

Normalized channel	Wire channel	Scope
orderbook	depthBooksPerps	Per market
trades	tradesPerps	Per market
candle	kLinePerps	Per market
marketsContext	markPricesPerps, fundingRatesPerps and topOfBooksPerps	All markets — subscribed with no markets filter; all three wire channels feed the aggregated context emit
marketContext	markPricesPerps, fundingRatesPerps and topOfBooksPerps	Per market — all three wire channels feed the aggregated context emit
orderUpdates	ordersPerps	Account-wide, authenticated
fills	fillsPerps	Account-wide, authenticated
positions	positionsPerps	Account-wide, authenticated
accountSummary	(none)	Not a wire channel of its own. The SDK reads REST GET /v1/perps/balance and emits the summary from the venue balance. A positionsPerps frame or a fillsPerps frame starts a new read. It reserves the connection’s authenticated-address binding like the channels above
spotBalances	(none)	Ondo publishes no balance channel — the SDK always emits one empty [] snapshot and never subscribes on the wire

In the aggregated market context, midPrice is the midpoint of the best bid and the best ask from topOfBooksPerps. The mark price stays in midPrice before the first two-sided book frame. It also stays there when one side of the book is empty.

​

Frames

Login — sent once per connection, before the first authenticated subscribe:

{ "op": "login", "args": { "token": "<session JWT>" } }

The venue rejects a second login on the same connection. The SDK reads the JWT from the client-held SIWE session; an absent or expired session throws SetupRequired before a login frame is ever sent, so callers re-run the SIWE login. A dropped socket forgets the login and re-authenticates on reconnect. See Account access.

Subscribe — sent per channel, and re-sent verbatim on every reconnect:

{ "op": "subscribe", "channel": "depthBooksPerps", "markets": ["BTC-USD.P"] }

A kLinePerps frame carries markets together with resolution. The wire resolutions are 1, 5, 15, 30, 1H, 4H, 1D, 1W, and 1M.

Ping — the literal keep-alive payload the SDK sends on its heartbeat interval:

{"op":"ping"}

​

One authenticated address per connection

Ondo’s WebSocket authenticates the whole connection, not per-subscription. Once an authenticated channel (orderUpdates, fills, positions, or accountSummary) is subscribed for one address, subscribing an authenticated channel for a different address on the same connection throws while the bound address still has a live authenticated channel. Open a new connection per address instead. When all the authenticated channels of the bound address are idle, the SDK releases the binding and reconnects the socket. The subscribe for the new address then continues.