Skip to main content
The stream pushes the same objects the REST API returns, as they change. One WebSocket carries every channel you subscribe to, for one key, its trading account and its mode.

Get a ticket

Your API key never travels over the socket. Exchange it for a ticket first:
A ticket opens one connection and is good for 60 seconds, or until the key expires if that is sooner. Request a new one for each connection, including every reconnect. A 503 with FEATURE_DISABLED means streaming is not available right now.

Connect and authenticate

Open the WebSocket at wss://api.lean.xyz/v1/ws, the /v1/ws path on the same host as the REST API. Test and live keys use the same URL; the ticket sets the mode. Within 10 seconds, send the ticket as the first frame:
Every frame in both directions is one JSON text object. Frames you send must not carry fields other than the ones shown here.

Subscribe

The reply lists the channels you named:
Send {"op":"unsubscribe","channels":[...]} to stop a channel; the reply is an unsubscribed frame. A connection holds at most 32 channels. Send {"op":"ping"} at any time; the reply is {"type":"pong"}. Channels always follow the ticket’s account and mode; no frame can name another.

Channels

Orders

Each order’s states only move forward. The channel sends states that happen after you subscribe, so call GET /v1/orders once after subscribed to cover anything earlier. The channel never skips an order state while the connection stays open. If Lean cannot be sure every state reached you, it closes the connection with 1013 and UPSTREAM_ERROR, so reconnect and call GET /v1/orders again.

Positions and balances

Each frame is a whole state that replaces the one before it. The newest state arrives first, then each change. They are sent after every order change on the account and refreshed about every ten seconds otherwise.

Book

A book frame holds one market’s book across every venue that lists it, at a depth of 20 levels per side. market_id takes a market ID or a venue symbol; a symbol’s channel holds only the listing it names, under the market’s ID. Each frame’s top level market_id is the ID or symbol you subscribed with, so you can follow one market under several names and still tell their frames apart:
  • Bids are what a sell fills against and asks are what a buy fills against, for the market’s outcome. Prices and quantities are decimal strings.
  • combined merges every venue’s levels by price and shows each venue’s share.
  • Quantity and notional totals cover every level read, not only the 20 listed.
  • A venue whose book could not be read appears in unavailable instead of as an empty book.
  • The book updates about once a second, from live venue data where Lean has it and from a venue poll otherwise. as_of is when the frame was built.
  • Each frame replaces the one before it. A book channel for a market that does not exist, or for a symbol that names more than one market, sends nothing.
A session that reads positions, balances or books too slowly skips ahead to the newest state.

Errors and closing

After authentication, a bad frame is answered with an error frame and the connection stays open:
Before authentication, or when the connection must end, Lean sends the error frame and then closes the socket: Revoking a key closes its open streams with 1008 and UNAUTHORIZED. Pausing trading on an account does not close streams, since they only read.

Reconnecting

Connections end: Lean restarts and moves streams between servers, networks drop, and tickets expire. Plan for it. Frames that would have been sent while you were disconnected are not sent later, so a reconnect always rebuilds state from fresh data.

Notice a lost connection

A connection can stop delivering frames without closing. Send {"op":"ping"} every 10 seconds. If no frame of any kind, pong included, arrives for 25 seconds, close the socket and reconnect. Treat a socket that has not answered auth with authenticated within 15 seconds the same way.

Wait before retrying

Wait a random delay between zero and min(30 seconds, 0.5 seconds × 2^attempt) before each attempt, where attempt counts from zero. The random spread keeps many clients that lost their connections together from retrying together. Reset attempt to zero once a connection has stayed authenticated for 15 seconds.

Reconnect

  1. Get a new ticket from POST /v1/ws/token. A ticket works once, so never reuse one.
  2. Open /v1/ws and send the auth frame.
  3. After authenticated, send one subscribe frame naming every channel you want. Lean keeps nothing from the old connection.
  4. Rebuild state from what arrives:
    • Books: mark each book stale when the connection drops. The first book frame for that market replaces it.
    • Positions and balances: the newest state arrives first after subscribed and replaces yours.
    • Orders: after subscribed, call GET /v1/orders and merge it with the order frames you receive. For each order keep the copy with the latest updated_at.

Which closes to retry

What to expect

  • While you reconnect, no frames arrive. Most reconnects take a few seconds, longer during an outage. Show data as stale until its first frame after the reconnect.
  • Lean never replays missed frames. Books, positions and balances recover with their next frame; orders recover through GET /v1/orders.
  • Your client cannot tell which server it reached, and does not need to: tickets, channels and frames behave the same on every connection.