Skip to main content
A market is one outcome of one proposition of one fixture. For example: “DEN” in “DEN -3.5” in “Denver Broncos at Los Angeles Chargers”.

Query parameters

Season futures start later than 30 days ahead; pass starts_before to list them. Their market IDs resolve at any time. A parameter the endpoint does not take is refused with 400 VALIDATION_ERROR, so a misspelled filter never returns the whole list. List markets lists every parameter.

One proposition of one fixture

Pass fixture and group together to list the outcomes of one proposition, such as every driver in one race’s winner market, without paging through the whole league:
Take both keys from a market you already have. Both filters combine with the others, and the start window still applies: a fixture that starts outside it lists nothing, so pass starts_after or starts_before to reach it.

Search by text

search finds markets the way the search box in the Lean app does.
  • Every word must appear, in any letter case, in the title of a Kalshi, Polymarket, Polymarket US or Hyperliquid listing of the market or of its game. The last word can be the start of a word, so celt finds Celtics.
  • When few listings match, Lean also tries common team nicknames and city short forms, such as philly for Philadelphia, and words one or two letters off, such as celtcs.
  • Only markets with a matching listing are returned, not every market of the same game.
  • Results keep the usual order by start time. league, sport, status, the start window, limit and cursor work the same as without search. Pass next_cursor back as cursor with the same search to read the next page.
  • A search looks only at the listings of games in the start window, and at no more than 10,000 matching ones, open listings first, then by start. Narrow broad words with league, sport or the start window.
  • The same search over the same listings returns the same markets every time.
  • League names are in only some listing titles, so search=nba finds only the markets with such a listing, not every NBA market. To list a league, use league rather than search.
  • Spaces at either end are ignored. The text must then be 1 to 100 characters, or the request returns 400 VALIDATION_ERROR.
  • If search is briefly unavailable or cannot finish in time, the request returns 503 UPSTREAM_ERROR rather than a partial list. Retry it, or narrow a long start window.

A market

title names the fixture, the proposition and the outcome in words, ready to show a person.

Fixture

Proposition (group)

group.kind is moneyline, spread, total, team_total or prop.
  • group.period is game for every v0.1 sports market. v0.1 lists markets on the full game only.
  • In a spread, group.subject is the team that holds the negative line, and group.line is that negative line. In spread:game:DEN:-3.5, DEN is the subject.

Signed line per outcome

line on each market is the line from that outcome’s point of view:

Legs

legs lists the venue listings behind the market. side is the venue side that pays when this outcome happens. status is the venue market’s status: unopened, open, closed, resolving or resolved, or null until Lean has recorded the venue market. The Lean platform shows a live book for every status but closed and resolved. tradable: true marks a leg the venue takes orders on now: a venue POST /v1/orders can place on, whose venue market is open and not marked untradable by the venue. An unopened or resolving leg has a live book but reads tradable: false, because its venue refuses orders. A market with no tradable leg is closed. Other legs are there for price discovery.
  • legs[].resolution is how that venue settles its market, and any field can be null:
    • source: how the venue resolved the market. It stays null until the market resolves.
    • rules: the venue’s rules text, verbatim, with any secondary rules after a blank line.
    • end_date: the venue’s end date, in ISO 8601.
    • url: the venue’s page for the market, or null when Lean does not know it.
  • legs[].fees is what that venue charges a fill, with the same terms POST /v1/orders/preview prices its fees with. It is null on Kalshi and Polymarket US, and when Lean has not recorded the venue’s fee for the market. See Fees.
  • equivalence says how far the legs are known to match: single_venue (one venue lists it), verified (a reviewer confirmed each venue’s market is the same proposition, which does not mean the rules text is identical, so read each leg’s rules) or unreviewed (not yet checked). A venue listing a reviewer judged to be a different proposition is never listed as a leg.
GET /v1/markets/{id} returns one market in the same shape, or 404 NOT_FOUND.

Fees

Each leg’s fees lets you price a fill’s fee before you preview it: rate is taker_rate for a fill that takes liquidity and maker_rate for a resting order that fills. A Polymarket market with maker_rate: "0" charges only takers. Hyperliquid’s maker_rate is its lowest-volume tier. For example, a Polymarket leg with { "formula": "price_curve", "taker_rate": "0.05", "maker_rate": "0", "exponent": 1 }:
  • Buying 100 shares at 0.24 pays 100 × 0.05 × (0.24 × 0.76) = $0.912, so each share costs 0.24912 with its fee. If the outcome is worth 0.255 to you, the edge is 0.255 − 0.24912 = 0.00588 a share, not 0.015.
  • Selling 100 shares at 0.76 pays the same $0.912, because price × (1 − price) is the same.
And a Hyperliquid leg with { "formula": "notional_on_exit", "taker_rate": "0.0007", "maker_rate": "0.0004", "exponent": null }:
  • Buying 100 shares at 0.60 pays nothing.
  • Selling those 100 shares at 0.60 pays 100 × 0.60 × 0.0007 = $0.042.
  • Holding them to a win instead pays 100 × $1 × 0.0007 = $0.07 at settlement.
POST /v1/orders/preview and the quote price every fill at taker_rate from these same terms, and their expected_fee_usd and fee_usd are authoritative. When a Polymarket leg’s fees is null, they show a fee of 0 for it, which may be less than Polymarket charges. When a Hyperliquid leg’s fees is null, they price its sells at the base rate, 7 bps. A venue can change its fees, so preview an order before you place it.

Market IDs

A market ID (mkt_…) is stable and opaque. Store it and send it back unchanged. Do not build or edit IDs yourself. A mkt_… ID Lean did not issue, or one that names a team outside its fixture, returns 404 NOT_FOUND.

Venue symbols

Every field and path that takes a market ID, including a book channel on the stream, also takes a venue symbol that names exactly one market: Kalshi and Polymarket US markets have no venue symbol here: name them by market ID. To find the market ID from a Kalshi or pmus: ticker, use GET /v1/markets?symbol=. Lean answers with the market under its market ID, so a market never appears under two IDs. Orders, fills and filters store and compare the market ID: listing orders by a token ID returns the same orders as listing them by the market ID. An order named by a venue symbol trades only that listing. If venues leaves out the symbol’s venue, the order is refused with 422 and details.reason: "NO_EXECUTABLE_VENUE". A buy Lean routes for you still buys that listing, paid from the other venue, which happens only between Polymarket and Hyperliquid. Reads that price a market price what an order naming the same ID would trade. With a venue symbol, the quote, book, trades, prices and book stream channel read only the symbol’s listing, under the market ID. With a market ID they read every listing. GET /v1/markets/{id} describes the whole market either way. A symbol that names more than one market returns 400 VALIDATION_ERROR. The ticker or Polymarket condition ID of a listing that pays both outcomes names both of its markets; send the token ID, the book coin or the market ID instead. A symbol Lean does not list returns 404 NOT_FOUND, and a value that is neither a market ID nor a venue symbol returns 400 VALIDATION_ERROR.

Prices

GET /v1/prices reads the top of the book for up to 25 markets, separated by commas. More than 25 returns 400 VALIDATION_ERROR with market_ids: At most 25 market ids per request; split larger sets across requests. Ids that name no market are listed in not_found. A best price backed by a few shares fills only those shares there. Size an order against the quantity, or read the book for the depth behind it. Polymarket quantities include what the opposite outcome’s book implies; Hyperliquid quantities are the venue’s book as it stands.

Quotes and liquidity

A quote shows how a buy of quantity shares would fill across venues. Send action=sell to quote a sell of shares the trading account holds. For a buy, send notional instead of quantity to quote the shares a dollar amount buys, as a buy sized with notional would be placed. A quote prices a market order, within the account’s slippage bound when it sets one (max_slippage_bps in GET /v1/account/config), on the venues orders can use. limited_by is one of: When nothing could be placed, legs is empty and quantity is 0. New limited_by values can appear without a new version; treat one you do not recognize as covering only part of the quantity. If routing is not available, the quote returns 503 FEATURE_DISABLED. Markets, previews and orders still work.

Recent trades

GET /v1/markets/{id}/trades lists the trades on each venue listing of the market, newest first. To read further back, pass the page’s next_cursor as cursor. Each page holds trades strictly older than the last trade of the page before. next_cursor is null when no older trade is recorded. A cursor works only for the market and venue it was issued for. A cursor Lean did not issue, or one passed with another market or venue, returns 400 VALIDATION_ERROR.

Price candles

GET /v1/markets/{id}/candles returns open, high, low, close and volume for each venue listing of the market, oldest first. Pass venue to read one listing. One call returns at most 1000 candles per listing. A range longer than that, a start that is not before end, or an unknown interval returns 400 VALIDATION_ERROR. An unknown market returns 404 NOT_FOUND. Prices are dollars per share of the side the market buys. A period with no trade has no candle, and the period still open may be missing or hold only the trades so far. A period the Lean chart treats as unpriced has no candle either: a recorded open of 0 or close below 0.001, read before a Polymarket NO market’s prices are turned over.