Get a ticket
Your API key never travels over the socket. Exchange it for a ticket first:503 with FEATURE_DISABLED means streaming is not available right
now.
Connect and authenticate
Open the WebSocket atwss://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:
Subscribe
{"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 callGET /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.
combinedmerges 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
unavailableinstead 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_ofis 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.
Errors and closing
After authentication, a bad frame is answered with an error frame and the connection stays open:
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 andmin(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
- Get a new ticket from
POST /v1/ws/token. A ticket works once, so never reuse one. - Open
/v1/wsand send theauthframe. - After
authenticated, send onesubscribeframe naming every channel you want. Lean keeps nothing from the old connection. - Rebuild state from what arrives:
- Books: mark each book stale when the connection drops. The first
bookframe for that market replaces it. - Positions and balances: the newest state arrives first after
subscribedand replaces yours. - Orders: after
subscribed, callGET /v1/ordersand merge it with the order frames you receive. For each order keep the copy with the latestupdated_at.
- Books: mark each book stale when the connection drops. The first
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.