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
Passfixture 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:
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
celtfindsCeltics. - When few listings match, Lean also tries common team nicknames and city short forms, such as
phillyfor Philadelphia, and words one or two letters off, such asceltcs. - 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,limitandcursorwork the same as withoutsearch. Passnext_cursorback ascursorwith the samesearchto 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,sportor 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=nbafinds only the markets with such a listing, not every NBA market. To list a league, useleaguerather thansearch. - 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_ERRORrather 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.periodisgamefor every v0.1 sports market. v0.1 lists markets on the full game only.- In a spread,
group.subjectis the team that holds the negative line, andgroup.lineis that negative line. Inspread: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[].resolutionis how that venue settles its market, and any field can benull:source: how the venue resolved the market. It staysnulluntil 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, ornullwhen Lean does not know it.
legs[].feesis what that venue charges a fill, with the same termsPOST /v1/orders/previewprices its fees with. It isnullon Kalshi and Polymarket US, and when Lean has not recorded the venue’s fee for the market. See Fees.equivalencesays 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’srules) orunreviewed(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’sfees 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.
{ "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.07at 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 abook 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
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.