Skip to main content
One WebSocket carries every channel you subscribe to, for one key, its trading account and its mode. For reconnecting and rebuilding state, see the Streaming guide.

Connect

Frames you send must not carry fields other than the ones shown on this page. Channels always follow the ticket’s account and mode; no frame can name another.

Get a ticket

Your API key never travels over the socket. Exchange it for a ticket with Create a stream ticket:
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.

Authenticate

Within 10 seconds of opening the socket, send the ticket as the first frame:
Any other frame before auth closes the socket. A second auth frame on the same connection is answered with a VALIDATION_ERROR error frame.

Subscribe and unsubscribe

Name one or more channels:
The reply lists the channels you named:
To stop channels, send the same shape with unsubscribe. The reply is an unsubscribed frame listing the channels you named:
Subscribing to a channel you already hold does not add it twice. These are answered with a VALIDATION_ERROR error frame and the connection stays open:

Channels

orders

Sends each state of the account’s orders that happens after subscribed. Each order’s states only move forward. Call GET /v1/orders once after subscribed to cover anything earlier.

positions

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

balances

Sent and refreshed the same way as positions.

book

Takes a market_id: a market ID or a venue symbol. With a market ID, each frame holds the market’s book across every venue that lists it; with a venue symbol, only that symbol’s listing. combined merges the venues’ levels by price, at a depth of 20 levels per side. The book updates about once a second, and each frame replaces the one before it. A market_id that names no market sends nothing. The frame’s top-level market_id is the one you subscribed with, so a session following one market under two names can tell their frames apart. book.market_id is always the market ID.
A session that reads positions, balances or books too slowly skips ahead to the newest state.

Keep the connection alive

Send {"op":"ping"} every 10 seconds; the reply is {"type":"pong"}. If no frame of any kind, pong included, arrives for 25 seconds, close the socket and reconnect with a new ticket.

Errors

After authentication, a bad frame is answered with an error frame and the connection stays open:

Close codes

Before authentication, or when the connection must end, Lean sends an error frame and then closes the socket: After a 1012 or 1013 close, reconnect with a new ticket, subscribe again and call GET /v1/orders. After a 1008 close, the ticket or key was refused: try once more with a new ticket and stop after three 1008 closes in a row. The Streaming guide covers the full reconnect plan.