> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lean.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Streaming

> Follow orders, positions, balances and market books over one WebSocket.

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:

```bash theme={"dark"}
curl -sS -X POST "$LEAN_API_URL/v1/ws/token" \
  -H "Authorization: Bearer $LEAN_API_KEY"
```

```json theme={"dark"}
{
  "success": true,
  "data": { "token": "<ticket>", "expires_at": "2026-11-01T20:25:00.000Z", "livemode": false },
  "meta": { "requestId": "<request id>" }
}
```

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:

```json theme={"dark"}
{ "op": "auth", "ticket": "<ticket>" }
```

```json theme={"dark"}
{ "type": "authenticated", "livemode": false, "key_id": "<key id>" }
```

Every frame in both directions is one JSON text object. Frames you send must not carry fields
other than the ones shown here.

## Subscribe

```json theme={"dark"}
{
  "op": "subscribe",
  "channels": [
    { "channel": "orders" },
    { "channel": "positions" },
    { "channel": "balances" },
    { "channel": "book", "market_id": "mkt_..." }
  ]
}
```

The reply lists the channels you named:

```json theme={"dark"}
{ "type": "subscribed", "channels": [{ "channel": "orders" }, { "channel": "positions" }] }
```

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

| Channel | Frame | Holds |
| - | - | - |
| `orders` | `{"type":"order","order":{...}}` | Each new state of an order, as `GET /v1/orders/{id}` returns it. |
| `positions` | `{"type":"positions","positions":{...}}` | The whole `GET /v1/positions` result. |
| `balances` | `{"type":"balances","balances":{...}}` | The whole `GET /v1/balances` result. |
| `book` | `{"type":"book","market_id":"...","book":{...}}` | The combined order book of one market. |

### 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](https://docs.lean.xyz/markets.md#venue-symbols); 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:

```json theme={"dark"}
{
  "type": "book",
  "market_id": "<market ID or venue symbol you subscribed with>",
  "book": {
    "market_id": "mkt_...",
    "venues": [
      {
        "venue": "polymarket",
        "ticker": "<venue ticker>",
        "side": "yes",
        "bids": [{ "price": "0.52", "quantity": "100" }],
        "asks": [{ "price": "0.55", "quantity": "40" }],
        "bid_quantity": "100",
        "ask_quantity": "40",
        "bid_notional_usd": "52",
        "ask_notional_usd": "22"
      }
    ],
    "combined": {
      "bids": [
        { "price": "0.52", "quantity": "100", "venues": [{ "venue": "polymarket", "quantity": "100" }] }
      ],
      "asks": [
        { "price": "0.55", "quantity": "40", "venues": [{ "venue": "polymarket", "quantity": "40" }] }
      ]
    },
    "total_bid_quantity": "100",
    "total_ask_quantity": "40",
    "total_bid_notional_usd": "52",
    "total_ask_notional_usd": "22",
    "unavailable": [],
    "as_of": "2026-11-01T20:25:00.000Z",
    "livemode": false
  }
}
```

* 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:

```json theme={"dark"}
{ "type": "error", "code": "VALIDATION_ERROR", "message": "Unrecognized frame" }
```

Before authentication, or when the connection must end, Lean sends the error frame and then
closes the socket:

| Close code | `code` | When |
| - | - | - |
| `1008` | `UNAUTHORIZED` | The ticket is invalid, expired or already used; no `auth` frame arrived within 10 seconds; a frame came before `auth`; or the key was revoked or expired. |
| `1008` | `VALIDATION_ERROR` | The first frame was not an `auth` frame. |
| `1003` | `VALIDATION_ERROR` | A binary frame was sent. |
| `1013` | `RATE_LIMITED` | The session read order states too slowly to keep up. |
| `1013` | `UPSTREAM_ERROR` | Lean could not check whether the ticket was already used. |
| `1013` | `UPSTREAM_ERROR` | Order updates were interrupted inside Lean, so some may not have reached the session. Only sessions subscribed to `orders`, or sending a `subscribe` that names it, close this way; that `subscribe` gets no `subscribed` reply. |
| `1012` | none | Lean is restarting. |

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 happened | What to do |
| - | - |
| Close `1012` | Lean is restarting. Reconnect with a new ticket after the delay. |
| Close `1013` with `RATE_LIMITED` | Reconnect with a new ticket after the delay, and read frames faster. |
| Close `1013` with `UPSTREAM_ERROR` | Lean could not check the ticket, or order updates were interrupted. Reconnect with a new ticket after the delay, subscribe again and call `GET /v1/orders`. |
| Any other close, or no close at all | Reconnect with a new ticket after the delay. |
| The upgrade answered HTTP `502`, `503` or `504`, or no connection could be made | Retry with a new ticket after the delay. |
| `POST /v1/ws/token` answered `5xx` or did not answer | Retry it after the delay. No new connection can start until it succeeds. |
| Close `1008` | The ticket or the key was refused. Try once more with a new ticket. Stop after three `1008` closes in a row. |
| `POST /v1/ws/token` answered `401` or `403` | The key is revoked, expired or lacks access. Stop and fix the key. |

### 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.