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

# Changelog

> Every Lean API release, newest first.

Each entry names the release version from `info.version` in the
[OpenAPI spec](https://lean.mintlify.site/api-reference/openapi.json). Breaking changes are marked, with the date they take
effect. See [Versioning](https://docs.lean.xyz/versioning.md) for what counts as breaking.

**2026-11-13**

0.1.0: Kalshi and Polymarket US

**Venues**

* Markets, quotes, books, trades, prices, orders, fills, positions, balances, PnL, risk, stop
  losses and limit chases cover Kalshi and Polymarket US as well as Polymarket and Hyperliquid.
  `venue` takes `kalshi` and `polymarket_us` wherever it names a trading venue.
* Kalshi and Polymarket US accounts belong to the user, so every trading account and key of the
  user shares their cash and shares. A live order there goes out under the user's API key for
  that venue, connected in the Lean app, and is refused with `403 FORBIDDEN` without one. See
  [Kalshi and Polymarket US](https://docs.lean.xyz/orders.md#kalshi-and-polymarket-us).
* A quote, preview or order that needs a Polymarket US book Lean has not loaded yet answers
  `503 UPSTREAM_ERROR` with `Retry-After`. Send it again after that time.
* A test key starts with 10,000 USD of simulated cash on Kalshi and on Polymarket US.
* Stop losses and limit chases run on every venue. They no longer refuse `hyperliquid`.
* `post_only` orders go to Kalshi, Polymarket US and Hyperliquid. `gtd` orders go to Kalshi,
  Polymarket and Polymarket US. A `fok` order goes whole to one venue: Polymarket, else Kalshi,
  else Polymarket US.
* Paying from the other venue, `best_price` routes, self-signed routed orders, deposits,
  withdrawals and transfers stay on Polymarket and Hyperliquid only.

**2026-11-13**

0.1.0: fee terms and fixture filters on markets, sizes on prices, batch previews, test-mode marks

**Markets**

* Every market leg has `fees`: the formula (`price_curve` or `notional_on_exit`), `taker_rate`,
  `maker_rate` and, for `price_curve`, `exponent`. They are the terms the preview charges, so a
  client can set a fee-aware limit price before previewing. `fees` is `null` when the venue's fee
  rate isn't recorded. See [Fees](https://docs.lean.xyz/markets.md#fees).
* `GET /v1/markets` takes `fixture` (a fixture key) and `group` (a group key such as
  `moneyline:game`), so one event's market group loads in one request instead of a whole league.
* Every market leg has `status`, the venue market's status (`unopened`, `open`, `closed`,
  `resolving` or `resolved`). An `unopened` or `resolving` leg has a live book on the Lean
  platform but stays `tradable: false`, because its venue refuses orders. See [Legs](https://docs.lean.xyz/markets.md#legs).

**Prices**

* `GET /v1/prices` returns `best_bid_quantity` and `best_ask_quantity`, top level and per venue:
  the shares at the best price, so a client can see how much an edge is worth before previewing.
* Prices match the Lean platform's orderbook. Best prices are snapped to the market's tick. `mid`
  is the venue's mid rounded down to the tick, and a book with only one side reads that side
  instead of `null`. One venue's crossed book reads a `spread` of `0`.
* `last_trade_price` counts a Hyperliquid trade of the opposite outcome at 1 minus its price, as
  Polymarket's already did, so it is the latest trade on either outcome.

**Candles**

* `GET /v1/markets/{id}/candles` leaves out periods the Lean chart treats as unpriced (an open of
  0 or a close below 0.001), as the chart does.

**Orders and fills**

* Orders and fills carry the market's `title` and `outcome`, as positions do.
* A canceled `ioc` order and its canceled legs have `status_reason.code`
  `IOC_REMAINDER_CANCELED`; `filled_quantity` says how much filled first.
* `POST /v1/orders/preview-batch` previews 1 to 25 orders in one request and returns each one's
  preview or error in order. It needs only the `read` scope. See
  [Preview orders (batch)](https://docs.lean.xyz/api-reference/orders/preview-orders-batch.md).
* Orders carry `remaining_quantity`: the shares still working on the venues, `0` once the order is
  final. `avg_fill_price` is documented as excluding fees.
* An order or leg the venue rejected or canceled after part of it filled reads `canceled`, and one
  whose whole size filled reads `filled`, as the Lean app reports them.
* A Polymarket `ioc` or `fok` sell may go below the market's minimum shares, down to `0.01`, so a
  position under the minimum can be closed. A sell that can rest keeps the minimum.
* Closing positions skips a Hyperliquid remainder under one whole contract instead of sending a
  sell the venue refuses.

**Test mode**

* Test positions are marked as the Lean portfolio marks live ones: Polymarket at the last trade,
  Hyperliquid at the venue's mid. `GET /v1/pnl` totals their unrealized profit and loss exactly as
  it does for a live key, so a position on a resolved market counts none. `GET /v1/pnl/history` stays realized-only for test
  keys. See [Test mode](https://docs.lean.xyz/test-mode.md).

**Errors**

* A `400 VALIDATION_ERROR` message names the first failing field and what is wrong with it,
  such as `market_ids: At most 25 market ids per request; split larger sets across requests`,
  and says how many more problems are in `details`.

**Performance**

* Responses report key authentication time in the `Server-Timing` header (`auth`), and a key's
  last-used time is written at most once a minute instead of on every request.

**2026-11-13**

0.1.0: Rust SDK 0.1.0

**Rust SDK**

* `lean-api-sdk` 0.1.0 is an async Rust client for the API. It is on crates.io once 0.1.0 is
  published; add it with Tokio.
* Every endpoint is a method on `lean_api::Client` with typed requests and responses, generated
  from the 0.1.0 OpenAPI spec. A response that isn't a success returns `Error::Api` with the
  HTTP status, the error code and the request ID.
* GET requests are retried on connection errors, 429 and 5xx responses. Order placement and
  other writes are never retried.
* `Client::stream` keeps a WebSocket open for orders, positions, balances and books, and
  reconnects after a drop.
* The API itself is unchanged.

See [Rust SDK](https://docs.lean.xyz/rust-sdk.md).

**2026-11-13**

0.1.0: TypeScript SDK 0.1.0 on npm

**TypeScript SDK**

* [`@leanxyz/api-sdk`](https://www.npmjs.com/package/@leanxyz/api-sdk) 0.1.0 is on npm. Install
  it with `npm install @leanxyz/api-sdk`. It needs Node.js 22 or later.
* Every endpoint is a method with typed requests and responses, generated from the 0.1.0
  OpenAPI spec. A response that isn't a success throws `LeanApiError` with the HTTP `status`,
  the error `code` and the `requestId`.
* `@leanxyz/api-sdk/stream` keeps a WebSocket open for orders, positions, balances and books,
  and reconnects after a drop.
* The API itself is unchanged.

See [TypeScript SDK](https://docs.lean.xyz/typescript-sdk.md).

**2026-11-13**

0.1.0: unknown query parameters refused

**Requests**

* Every endpoint that takes query parameters returns `400 VALIDATION_ERROR` for one it does not
  take, as `GET /v1/markets` already did, naming it in `details`. A misspelled filter such as
  `GET /v1/orders?stauts=open` used to be ignored and return every order. **Breaking:** takes
  effect on release; remove any parameter an endpoint does not list.

**2026-11-12**

0.1.0: client\_order\_id lookups across keys, cursors tied to their list, clearer errors

**Orders**

* `GET /v1/orders?client_order_id=` lists the orders any key of the account placed with that ID,
  not only the calling key's, so an order placed before a key rotation can still be found. It
  combines with the other filters.
* Quotes, previews and placement report a venue failure as `503 UPSTREAM_ERROR`. They never
  returned `502`; the reference listed it by mistake.

**Paging**

* A cursor is tied to the list that issued it. An orders cursor sent to `GET /v1/fills`, or any
  cursor sent to another list, returns `400 VALIDATION_ERROR`. **Breaking:** a cursor issued
  before this release is refused once with `400`; page that list again from the start.

**Errors**

* A path or method no endpoint serves returns the JSON `404 NOT_FOUND` envelope, not plain text.
* A malformed key returns `401 UNAUTHORIZED` with "Invalid, expired or revoked API key", the same
  as an unknown key, instead of "Missing API key".

**Funding**

* When a venue already has some deposit addresses, the deposit address note names only the
  network still missing one, such as Solana, and says the returned addresses are ready to use.
  Hyperliquid's `min_deposit_usd` is `null`: it has no minimum. See [Funding](https://docs.lean.xyz/funding.md).

**2026-11-12**

0.1.0: steady search results, and closed markets refused on quote and preview

**Markets**

* `GET /v1/markets` with `search` looks only at the listings of games in the start window. The
  same search now returns the same markets every time; it used to drop nickname and typo matches,
  such as `philly`, when it ran slowly. One- and two-letter searches no longer return
  `503 UPSTREAM_ERROR`.
* A search that cannot finish in time returns `503 UPSTREAM_ERROR` instead of a partial list.
* `GET /v1/markets/{id}/quote` and `POST /v1/orders/preview` on a market Polymarket has stopped
  trading return `409 CONFLICT` with `details.reason: "MARKET_NOT_TRADABLE"`, as documented. They
  used to return `500`, or `500` and `409` at random for a market with both a YES and a NO
  Polymarket listing. The [OpenAPI spec](https://lean.mintlify.site/api-reference/openapi.json)
  now lists this `409` on both routes.
* When Polymarket answers that check with a response Lean cannot read, quote and preview return
  `503 UPSTREAM_ERROR` instead of `500`.
* `POST /v1/orders/preview` returns these errors, and `503 UPSTREAM_ERROR` when a venue book
  can't be read, as the quote does. It no longer answers `200` with a `ROUTE_UNAVAILABLE` warning
  for them; that warning now means routing is off or no route can take the order.
* A leg whose venue market has closed now reads `tradable: false`. Closed markets used to show
  every leg as tradable.

**2026-11-12**

0.1.0: profit and loss, risk and the Lean MCP server

**Profit and loss**

* New `GET /v1/pnl` returns realized, unrealized and total profit and loss for the account and
  for each venue. Pass `venue` or `market_id` to narrow it.
* New `GET /v1/pnl/history` returns profit and loss over time at a `1h` or `1d` interval, for up
  to 365 days and 1000 points. See [Profit and loss](https://docs.lean.xyz/orders.md#profit-and-loss).

**Risk**

* New `GET /v1/risk` returns cost basis, mark value, cash and open order notional for the account
  and for each venue, with the largest positions and the split by market and by category. See
  [Risk](https://docs.lean.xyz/orders.md#risk).

**Account**

* `GET /v1/account/config` now returns `scopes`, what the key may do: `read`, `trade`, `route`
  and `withdraw`.

**MCP server**

* The Lean MCP server lets an AI assistant use your key to read markets, orders, fills,
  positions, profit and loss, risk, stop losses, limit chases, deposits, withdrawals and
  transfers. Every tool that takes a market id also takes a venue symbol.
* It is read only unless it starts with `--enable-trading`. Then a key with the `trade` scope can
  place, preview, amend and cancel orders, close positions, create stop losses and limit chases,
  pause trading and lower its own limits. Transfers also need the `route` scope. Withdrawals need
  only the `withdraw` scope. Only the Lean app resumes trading or raises a limit.

See [Run the Lean MCP server](https://docs.lean.xyz/build-with-ai.md#run-the-lean-mcp-server).

**2026-11-12**

0.1.0: withdrawals to more chains

**Withdrawals**

* `POST /v1/withdrawals` pays USDC out on every chain the Lean app withdraws to:
  `destination.chain` is one of `polygon`, `arbitrum`, `base`, `optimism`, `ethereum`, `bsc` or
  `solana`, from either venue. A Solana withdrawal takes a Solana address, and every other chain
  a `0x` address; an address the chain cannot take is refused with `400 VALIDATION_ERROR`.
  `GET /v1/withdrawals` and `GET /v1/withdrawals/{id}` return the chain each withdrawal paid out
  on. See [Withdrawals through the API](https://docs.lean.xyz/funding.md#withdrawals-through-the-api).

**2026-11-12**

0.1.0: market search matches the Lean app search

**Markets**

* `GET /v1/markets` with `search` now finds markets the way the search box in the Lean app does.
  Every word is matched against Polymarket and Hyperliquid listing titles, with common team
  nicknames and small typos tried when few listings match. See
  [Search by text](https://docs.lean.xyz/markets.md#search-by-text).
* Only markets with a matching listing are returned, not every market of the same game. Results
  keep their order by start time, and the other filters and `cursor` work as before.
* `search` no longer matches a market by its league. A league name such as `nba` finds only the
  markets with a listing whose title contains it, such as some Hyperliquid listings. Use `league`
  to list a league.
* A request with `search` can return `503 UPSTREAM_ERROR` while search is briefly unavailable.
  Retry it.

**2026-11-11**

0.1.0: filter positions, and find positions, orders and fills by text

**Positions**

* `GET /v1/positions` takes `venue`, `market_id` and `search`. With `venue`, Lean reads only that
  venue, so only it can be listed in `unavailable`. See [Read positions](https://docs.lean.xyz/orders.md#read-positions).

**Orders and fills**

* `GET /v1/orders` and `GET /v1/fills` take `search`. It keeps the records on a market whose
  `title` or `outcome` contains the text, in any letter case, and pages with `next_cursor` as
  usual. See [Find by text](https://docs.lean.xyz/orders.md#find-by-text).
* `search` must be 1 to 100 characters once spaces at either end are removed. Anything else
  returns `400 VALIDATION_ERROR`.

**2026-11-11**

0.1.0: venue symbols wherever a market id goes

**Markets**

* Every path and field that takes a market id also takes a venue symbol that names one market:
  a Polymarket token id, a Hyperliquid book coin (`#…`, written `%23…` in a path), or a leg
  `ticker` that pays only one outcome. Responses, orders, fills and filters always use the market
  id. See [Venue symbols](https://docs.lean.xyz/markets.md#venue-symbols).
* An order named by a venue symbol trades only that listing, and a buy Lean routes for it can
  still be paid from the other venue. Quotes, books, trades, prices and the `book` stream
  channel named by a symbol read only that listing, so they price what the order would trade.
* A `book` stream channel takes a venue symbol as well as a market id. Each `book` frame now
  carries a top level `market_id`: the id or symbol the channel was subscribed with. The book
  inside it still carries the market id. See [Book](https://docs.lean.xyz/streaming.md#book).
* A symbol that names more than one market, such as a Polymarket condition id, returns
  `400 VALIDATION_ERROR`. An unknown symbol returns `404 NOT_FOUND`, as an unknown market id
  does.

**Breaking, effective 2026-11-12:** in a REST path, query or body, a value that is neither a market id
nor a venue symbol now returns `400 VALIDATION_ERROR` instead of `404 NOT_FOUND`. A `mkt_…` id
Lean did not issue still returns `404 NOT_FOUND`.

**2026-11-11**

0.1.0: transfers between your venues

**Transfers**

* `POST /v1/transfers/quote` shows what moving USDC from one of your account's venues to the
  other costs: `fee_usd`, `receive_usd`, `minimum_usd`, `available_usd` and `expires_at`.
* `POST /v1/transfers` creates a transfer to the account's own balance on the other venue and
  returns the message to sign. Sending the same `client_transfer_id` again returns the same
  transfer. `POST /v1/transfers/{id}/execute` takes your signature, or `"delegated"` to have Lean
  sign.
* `GET /v1/transfers` and `GET /v1/transfers/{id}` show each transfer from
  `awaiting_authorization` to `completed`, `failed` or `expired`.
* Transfers count against the key's limits and stop while the key or account is paused. A
  quote still answers while paused. They need the `trade` and `route` scopes. Transfers are
  test mode only for now: a live key gets `503 FEATURE_DISABLED` with
  `details.reason: "LIVE_TRANSFERS_UNAVAILABLE"`. See [Transfers](https://docs.lean.xyz/transfers.md).

**Test mode**

* `POST /v1/test/reset` also deletes the account's test transfers and returns
  `deleted_transfers`.

**2026-11-11**

0.1.0: limit chases

**Limit chases**

* `POST /v1/limit-chases` rests a post only limit order on Polymarket a set distance behind the
  best price on its own side, given in `offset_ticks` or `offset_price`, and moves it as the book
  moves until it fills, is canceled or reaches `expires_at`. `price_limit` caps how far it
  follows. Hyperliquid does not run them, and a request for it is refused with
  `400 VALIDATION_ERROR`. `GET /v1/limit-chases`, `GET /v1/limit-chases/{id}` and
  `DELETE /v1/limit-chases/{id}` read and cancel them. Each one counts against the key's order
  and daily limits at the most it can trade for. A test key's limit chases follow the public book
  and fill in simulation. What one has filled is listed in `GET /v1/fills` with `order_id`
  `null`, as a live limit chase's fills are. `POST /v1/test/reset` also deletes them and returns
  `deleted_limit_chases`. See [Limit chases](https://docs.lean.xyz/limit-chases.md).

**2026-11-10**

0.1.0: market names on positions, older trades, fill filters and price candles

**Fills**

* Each fill in `GET /v1/fills` now carries `market_id`, the market it filled on, or `null` when
  Lean cannot tie it to one.
* `GET /v1/fills` takes `market_id`, `filled_after` and `filled_before` to narrow the list to one
  market or a time window. See [Read fills](https://docs.lean.xyz/orders.md#read-fills).

**Positions**

* Each position in `GET /v1/positions` and the `positions` stream channel now carries `title` and
  `outcome` beside `market_id`. All three are `null` whenever `market_id` is. See
  [Reconcile](https://docs.lean.xyz/orders.md#reconcile).

**Markets**

* Each market now carries `title`, the fixture, proposition and outcome in words.
* `GET /v1/markets/{id}/trades` returns `next_cursor`. Pass it as `cursor`, with the same market
  and `venue`, to read older trades. See [Recent trades](https://docs.lean.xyz/markets.md#recent-trades).
* New `GET /v1/markets/{id}/candles` returns open, high, low, close and volume per venue
  listing, from one second to two hours per candle. See [Price candles](https://docs.lean.xyz/markets.md#price-candles).

**2026-11-10**

0.1.0: order management

**Orders**

* `POST /v1/orders/cancel-batch` cancels up to 50 orders in one call, named by id,
  `client_order_id` or both, with one result for each name. See [Track and cancel](https://docs.lean.xyz/orders.md#track-and-cancel).
* `post_only` on `POST /v1/orders` and `POST /v1/orders/preview` places an order that only rests
  on the book. It runs on Hyperliquid, and an order that would trade at once is refused with
  `details.reason` `POST_ONLY_WOULD_CROSS`. See [Post only orders](https://docs.lean.xyz/orders.md#post-only-orders).
* `PATCH /v1/orders/{id}` changes the price, the size or both of a resting order. Lean cancels it
  and places a new order for the rest once the cancel is confirmed, answering `409`
  `REPLACEMENT_PENDING` until then, and the two name each other in the new `replaces_order_id`
  and `replaced_by_order_id` fields. The new order is placed as the key that sends the amend
  places one. See [Amend an order](https://docs.lean.xyz/orders.md#amend-an-order).
* `type: "market"` on `POST /v1/orders` and `POST /v1/orders/preview` trades at once with
  `limit_price` as an optional cap. Without one, a buy is capped at `0.99` and a sell at `0.01`.
  It needs `time_in_force` `ioc` or `fok`. See [Market orders](https://docs.lean.xyz/orders.md#market-orders).
* `time_in_force` `fok` fills an order in full at once or cancels all of it, and `gtd` rests an
  order until the new `expires_at`. Both run on Polymarket, and a request for Hyperliquid is
  refused with `400 VALIDATION_ERROR`. A `fok` buy is sized with `notional`. See
  [Fill or kill and expiring orders](https://docs.lean.xyz/orders.md#fill-or-kill-and-expiring-orders).
* Orders and previews show the new `type` and `expires_at` fields.

**Withdrawals**

* `POST /v1/withdrawals` withdraws cash from a venue to the address the request names,
  within the key's single and daily withdrawal limits. `GET /v1/withdrawals` and
  `GET /v1/withdrawals/{id}` read them back. It needs the new `withdraw` scope, which a live key
  takes when you turn on withdrawals for it in the Lean app. Both limits are optional. A request
  names its `source` venue and asset, its `destination` chain, asset and address, and the
  `amount`; the response adds the venue's `fee` and the `net_amount` quoted to arrive. A live
  withdrawal pays USDC on Polygon from Polymarket's pUSD and USDC on Arbitrum from Hyperliquid's
  USDC; any other pair is refused with `400`. It starts `pending`, and becomes `completed` or
  `failed` with a `failure_reason` as the venue settles it.
  The account must have trading enabled. `POST /v1/test/reset` also deletes test withdrawals and returns
  `deleted_withdrawals`. See [Withdrawals through the API](https://docs.lean.xyz/funding.md#withdrawals-through-the-api).

**Stop losses and take profits**

* `POST /v1/stop-losses` sells shares the account holds on Polymarket once the best bid falls
  to a trigger price (`stop_loss`) or rises to it (`take_profit`). Hyperliquid does not run them,
  and a request for it is refused with `400 VALIDATION_ERROR`. `GET /v1/stop-losses`,
  `GET /v1/stop-losses/{id}` and `DELETE /v1/stop-losses/{id}` read and cancel them, and a
  cancel shows in the new `cancel_requested_at` field. Each sale counts against the key's order
  and daily limits at its trigger price. A test key's stop losses are checked and listed but
  never sell.
  `POST /v1/test/reset` also deletes them and returns `deleted_stop_losses`. See
  [Stop losses and take profits](https://docs.lean.xyz/stop-losses.md).

**2026-11-10**

0.1.0: more fixes from agent testing

**Orders**

* **Breaking, effective 2026-11-12:** when no venue that lists the market is open to the trading
  account, for example because the venue is not available in your region,
  `POST /v1/orders/preview` now returns the same `403` error as `POST /v1/orders` and the quote. It used to return `200` with a
  `TRADING_UNAVAILABLE` warning. See [Preview](https://docs.lean.xyz/preview.md).
* Order docs now say where fees are: an order has no fee field, and its fees are the `fee_usd` of
  its fills. A live Hyperliquid buy fill shows `fee_usd` `0` because the buy pays its fee when the
  position closes or settles. See [Limitations](https://docs.lean.xyz/orders.md#limitations).
* **Breaking, effective 2026-11-12:** an order you canceled reads `cancel_requested` until its venue
  confirms the cancel, then `canceled`, or `filled` if a fill beat the cancel. It used to keep
  reading `open` or `partially_filled` meanwhile. `GET /v1/orders` takes `status=cancel_requested`.
  See [Statuses](https://docs.lean.xyz/statuses.md).
* Orders carry `filled_notional_usd`, what the filled shares traded for across every leg.
  `notional_usd` stays the order at its own limit. See [Orders](https://docs.lean.xyz/orders.md).
* A sell at `0.01`, as a close without `limit_price` places, now shows the lowest limit among its
  legs as its `limit_price`, the protection the venue orders carry. It used to show `0.01`.
* An `ioc` buy can send `notional`, the dollars to spend, in place of `quantity`. Lean walks the
  books within your limit and slippage bound and never spends more than `notional` before fees.
  `limit_price` is optional with it. `POST /v1/orders/preview` and `GET /v1/markets/{id}/quote`
  take it too. See [Buying a dollar amount](https://docs.lean.xyz/orders.md#buying-a-dollar-amount).
* An `ioc` buy sized with `notional` can now fill on Polymarket. One sized with `quantity` is
  still refused there, and the error now says to send `notional`.
* Reading a filled Hyperliquid or Polymarket order with `GET /v1/orders/{id}` now brings its
  fills into `GET /v1/fills`. Before, the order could read `filled` a few seconds before its
  fills were listed. A Polymarket fill whose trade Polygon has not confirmed yet, or a fill of an
  order you have not read, can still be listed a few seconds later. See
  [Limitations](https://docs.lean.xyz/orders.md#limitations).

**Closing positions**

* Each placed sell in a close is read back before the response, so a sell the venue matched at once
  reads `filled` with its filled quantity and average price. It used to read as first placed.
* A close scoped to one market no longer includes positions that can't be matched to a market the
  API trades. A close of every position still includes them.

**Test mode**

* A test buy paid from the other venue now fills at the asks that venue's public book shows. When
  those asks can't fill the whole size within the limit, the buy is refused with
  `422 VALIDATION_ERROR`, as a live one is. It used to fill at the limit. See
  [Test mode](https://docs.lean.xyz/test-mode.md).
* Test positions now carry `mark_price`, the best bid on the venue's public book, and
  `unrealized_pnl_usd`. Both used to be `null`.

**Streaming**

* The [Streaming](https://docs.lean.xyz/streaming.md) page names the WebSocket URL, `wss://api.lean.xyz/v1/ws`.

**2026-11-08**

0.1.0: fixes from agent testing

**Markets**

* `GET /v1/markets` takes `venue`, `polymarket` or `hyperliquid`, to list only markets with a leg
  on that venue. See [Query parameters](https://docs.lean.xyz/markets.md#query-parameters).
* A Polymarket leg the venue no longer trades now reads `tradable: false`, and a market with no tradable open
  leg reads `closed`.
* **Breaking, effective 2026-11-12:** `GET /v1/markets` refuses a query parameter it does not
  know with `400 VALIDATION_ERROR`. It used to ignore it and return the whole list.
* **Breaking, effective 2026-11-12:** a request that needs the book of a market Polymarket has
  stopped trading returns `409 CONFLICT` with `details.reason: "MARKET_NOT_TRADABLE"`. It used to
  return `503 UPSTREAM_ERROR`. See [Errors](https://docs.lean.xyz/errors.md#codes).

**Orders and account**

* Each item of `GET /v1/positions` carries `market_id`, the Lean market the position belongs to.
  `market_id` is `null` when no listed market currently matches the holding, for example a fixture
  that settled more than 7 days ago. It can also be `null` for a moment after an API restart or a
  failed market list load, until the market list loads. Closing still works because the close
  path resolves the market from the ticker.
* `POST /v1/orders/preview` prices `route_plan` at the order's limit. A limit at the best ask no
  longer warns, and a buy limit below the book reports `limited_by: "depth"`, not `"funds"`. The
  `LIMIT_BELOW_ROUTE_PRICE` preview warning is gone: `ROUTE_LIMITED` covers a limit the books
  cannot fill. See [Preview](https://docs.lean.xyz/preview.md).
* `GET /v1/balances` answers within about 3 seconds. A venue that has not answered by then is
  listed in `unavailable`, and the other venues are still returned.

**2026-11-02**

0.1.0: one-call orders across venues

**Orders**

* `POST /v1/orders` now buys with cash held on the other venue in the same call. Lean moves the
  cash and buys on the venue with the book. The response carries
  `route: { funding_venue, execution_venue }`, or `route: null` when nothing was moved. See
  [Paying from the other venue](https://docs.lean.xyz/orders.md#paying-from-the-other-venue).

* It needs the key's `route` scope, trading enabled in the Lean app for a live key, and routing
  available. If any is missing, the order is refused as before with `422 VALIDATION_ERROR` and
  `details.reason: "INSUFFICIENT_FUNDS"`.

* **Read and trade** keys made in the Lean app now include the `route` scope, in test and live
  mode. Keys made earlier keep their scopes: create a new key, or one with `route` through
  `POST /api-keys`, to use one-call routing. See [Authentication](https://docs.lean.xyz/authentication.md#create-a-key).

* Test keys get the same one call against the simulator. No real funds move.

* `POST /v1/routed-orders` and `POST /v1/routed-orders/{id}/execute` remain for programs that sign
  each payment themselves. See [Advanced: self-signed routed orders](https://docs.lean.xyz/routed-orders.md).

* `venues` on `POST /v1/orders` keeps an order on the venues it names. A single venue places the
  order only there, or refuses it. The list can only narrow the account's venues. See
  [Choosing venues](https://docs.lean.xyz/orders.md#choosing-venues).

* `POST /v1/orders/preview` honors `venues`, and shows the route a buy would take in `route`.

* `best_price` on `POST /v1/orders` and `POST /v1/orders/preview` pays from the other venue
  whenever that costs less in all than buying where the account's cash is. It is `false` by
  default. See [Best price across venues](https://docs.lean.xyz/orders.md#best-price-across-venues).

Nothing breaking: an order that would have been refused with `INSUFFICIENT_FUNDS` can now fill.

**0.1.0**

Preview release

The first public preview of the Lean API, served at `https://api.lean.xyz/v1`.

**Markets**

* `GET /v1/markets` lists canonical sports markets, without naming a venue. Each leg carries the
  venue's resolution terms, and each market says whether its venue listings were reviewed as the
  same proposition. See [Markets](https://docs.lean.xyz/markets.md#legs).
* `GET /v1/markets/{id}/quote` quotes a market across the venues that list it.

**Orders**

* `POST /v1/orders/preview` prices an order and shows the route Lean would take.
* `POST /v1/orders` places an order on Hyperliquid, Polymarket or both. `client_order_id` makes
  retries safe.
* `GET /v1/orders`, `GET /v1/orders/{id}` and `POST /v1/orders/{id}/cancel` reconcile and cancel
  orders. Each order has `legs`, one per venue order, each with its own `status` and
  `status_reason`, and an `avg_fill_price` for the whole order.
* Venue outcomes are order statuses: an unfilled `ioc` order is `canceled`, a venue refusal is
  `rejected`, and a submit the venue did not confirm is `unconfirmed`. See
  [Order statuses](https://docs.lean.xyz/statuses.md).

**Account**

* `GET /v1/balances` and `GET /v1/positions` read each venue, and report a venue that cannot be
  read as unavailable rather than as zero.
* `POST /v1/account/pause` lets a key stop new orders for itself or its whole trading account.
  Only the Lean dashboard resumes. See [Pause trading](https://docs.lean.xyz/orders.md#pause-trading).

**Keys**

* `POST /api-keys`, `GET /api-keys` and `DELETE /api-keys/{id}` manage keys, each with scopes and
  per order and daily limits.
* Test keys simulate fills against simulated balances. See [Test mode](https://docs.lean.xyz/test-mode.md).


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