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

# Markets and IDs

> Fixtures, propositions, outcomes, signed lines and market IDs.

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

```bash theme={"dark"}
curl -sS "$LEAN_API_URL/v1/markets?league=nfl&limit=50" \
  -H "Authorization: Bearer $LEAN_API_KEY"
```

## Query parameters

| Parameter | Meaning |
| - | - |
| `league` | Exactly as it appears in `fixture.league`, for example `nfl`. |
| `sport` | As it appears in `fixture.sport`, in any case, for example `football` or `Football`. |
| `fixture` | Exactly as it appears in `fixture.key`. Lists only that fixture's markets. |
| `group` | Exactly as it appears in `group.key`, for example `moneyline:game`. Lists only markets of that proposition, in every fixture the other filters keep. |
| `category` | `sports`. Every listed market is a sports market today. |
| `status` | `open`: at least one venue leg is open for trading. `closed`: no leg is. |
| `venue` | `kalshi`, `polymarket`, `polymarket_us` or `hyperliquid`. Lists only markets with a leg on that venue. |
| `search` | Words to find, the way the search box in the Lean app finds them. See [Search by text](#search-by-text). |
| `symbol` | A venue symbol: a leg `ticker` (`pm:…`, `pmus:…`, `hl:…` or a Kalshi market ticker), a Polymarket condition ID or token ID, or a Hyperliquid book coin (`#…`, sent as `%23…` in the query string). Lists the markets that symbol trades. Only `venue` applies with it; the start window, `cursor` and the other filters do not. |
| `starts_after`, `starts_before` | ISO 8601 times. By default the list starts 12 hours ago and ends 30 days ahead. |
| `limit` | From 1 to 200. The default is 50. |
| `cursor` | The `next_cursor` of the previous page. `next_cursor` is `null` on the last page. |

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](https://docs.lean.xyz/api-reference/markets/list-markets.md) 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:

```bash theme={"dark"}
curl -sS -G "$LEAN_API_URL/v1/markets" \
  --data-urlencode "fixture=nfl:2026-10-11:DEN-LAC" \
  --data-urlencode "group=moneyline:game" \
  -H "Authorization: Bearer $LEAN_API_KEY"
```

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

```bash theme={"dark"}
curl -sS "$LEAN_API_URL/v1/markets?search=celtics&limit=50" \
  -H "Authorization: Bearer $LEAN_API_KEY"
```

`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

```json theme={"dark"}
{
  "id": "mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4",
  "title": "Denver Broncos at Los Angeles Chargers: DEN -3.5, Denver Broncos -3.5",
  "outcome": "DEN",
  "line": "-3.5",
  "fixture": {
    "key": "nfl:2026-10-11:DEN-LAC",
    "sport": "football",
    "league": "nfl",
    "title": "Denver Broncos at Los Angeles Chargers",
    "starts_at": "2026-10-11T20:25:00.000Z",
    "scheduled_date": "2026-10-11",
    "participants": ["Denver Broncos", "Los Angeles Chargers"],
    "teams": [
      { "key": "DEN", "name": "Denver Broncos", "role": "away" },
      { "key": "LAC", "name": "Los Angeles Chargers", "role": "home" }
    ]
  },
  "group": {
    "key": "spread:game:DEN:-3.5",
    "kind": "spread",
    "label": "DEN -3.5",
    "period": "game",
    "subject": "DEN",
    "stat": null,
    "line": "-3.5"
  },
  "legs": [
    { "venue": "hyperliquid", "ticker": "<venue ticker>", "side": "yes", "status": "open", "tradable": true }
  ]
}
```

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

### Fixture

| Field | Meaning |
| - | - |
| `fixture.key` | The canonical fixture key: `{league}:{scheduled date}:{participants}`. |
| `fixture.scheduled_date` | The date part of the key, `YYYY-MM-DD`. |
| `fixture.teams` | Each participant's `key`, `name` and `role` (`home`, `away` or `competitor`). |
| `fixture.starts_at` | The scheduled start time. |

### Proposition (`group`)

`group.kind` is `moneyline`, `spread`, `total`, `team_total` or `prop`.

| `group.key` | Proposition |
| - | - |
| `moneyline:game` | Who wins the game. |
| `spread:game:DEN:-3.5` | DEN wins by more than 3.5 points, or LAC covers +3.5. |
| `total:game:44.5` | Combined points over or under 44.5. |

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

| Market | `outcome` | `line` |
| - | - | - |
| `spread:game:DEN:-3.5` | `DEN` | `-3.5` |
| `spread:game:DEN:-3.5` | `LAC` | `3.5` |
| `total:game:44.5` | `over` | `44.5` |
| `total:game:44.5` | `under` | `44.5` |
| `moneyline:game` | `DEN` or `LAC` | `null` |

### 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](#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:

| Field | Meaning |
| - | - |
| `formula` | How the fee is charged: `price_curve` or `notional_on_exit`. |
| `taker_rate` | The rate, as a fraction of 1, for a fill that takes liquidity. |
| `maker_rate` | The rate, as a fraction of 1, for a resting order that fills. |
| `exponent` | The exponent in `price_curve`. `null` for `notional_on_exit`. |

| `formula` | Venue | Fee for `quantity` shares filled at `price` |
| - | - | - |
| `price_curve` | Polymarket | Buys and sells both pay `quantity × rate × (price × (1 − price))^exponent`. The fee is highest at 0.50 and falls toward 0 and 1. Each fill's fee is rounded to \$0.00001. |
| `notional_on_exit` | Hyperliquid | A buy pays nothing. A sell pays `quantity × price × rate`. A winning share held to settlement pays `rate × $1`. Each fill's fee is rounded up to \$0.000001. |

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

> [!NOTE]
>
> `POST /v1/orders/preview` and the [quote](#quotes-and-liquidity) 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](https://docs.lean.xyz/streaming.md), also takes a venue symbol that names exactly one market:

| Symbol | Example | Names |
| - | - | - |
| Polymarket token ID | `7132…` | The market whose outcome that token pays. |
| Hyperliquid book coin | `#120` | The market whose outcome that coin pays. In a URL path, write `#` as `%23`. |
| Leg `ticker` | `pm:0x…`, `pmus:…`, `hl:12`, `KXNBAGAME-…` | The market, when that listing pays only one outcome. |

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](https://docs.lean.xyz/routed-orders.md) 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

```bash theme={"dark"}
curl -sS "$LEAN_API_URL/v1/prices?market_ids=$MARKET_ID,$OTHER_MARKET_ID" \
  -H "Authorization: Bearer $LEAN_API_KEY"
```

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

| Field | Meaning |
| - | - |
| `best_bid`, `best_ask` | The best price across the venues read, snapped to the market's tick as the Lean platform shows it, or `null` when no venue has a level on that side. Hyperliquid prices are not snapped. |
| `best_bid_quantity`, `best_ask_quantity` | The shares resting at `best_bid` and `best_ask`, summed over every venue at that price. `null` when the price is `null`. |
| `mid` | The Lean platform's mid. When one venue holds both best prices, its mid rounded down to the market's tick (Hyperliquid's is not rounded); otherwise halfway between the best bid and best ask. A book with only one side reads that side's price. |
| `spread` | `best_ask` minus `best_bid`, or `null` when either is `null`. One venue's crossed book reads `0`; `spread` is negative only when one venue bids above another's ask. |
| `last_trade_price`, `last_trade_at` | The latest trade on any venue, in this market's outcome. A trade of the opposite outcome counts at 1 minus its price. |
| `venues[]` | Per venue: `best_bid`, `best_bid_quantity`, `best_ask` and `best_ask_quantity` on that venue alone. |
| `unavailable` | Venues whose book could not be read; never reported as empty. |

A best price backed by a few shares fills only those shares there. Size an order against the
quantity, or read the [book](https://docs.lean.xyz/api-reference/markets/retrieve-market-book.md) 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

```bash theme={"dark"}
curl -sS "$LEAN_API_URL/v1/markets/$MARKET_ID/quote?quantity=5" \
  -H "Authorization: Bearer $LEAN_API_KEY"
```

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.

| Field | Meaning |
| - | - |
| `legs[]` | Per venue: `quantity`, `average_price`, `limit_price` (the limit that leg would be placed at), `fee_usd` and `executable`. |
| `legs[].fee_usd` | The venue fee at the expected fills. A Hyperliquid buy pays its fee when the position closes or settles, so it shows `0` here; a Hyperliquid sell pays the market's taker rate, 7 bps times its fee scale. |
| `expected_total_usd` | The expected cost of the whole quantity. |
| `max_total_usd` | The cost in the worst case: every leg filled at its `limit_price`, with the fees at that price. |
| `network_cost_usd` | The cost of moving cash between venues. A quote prices each venue with its own cash, so it is `0` here; a [preview](https://docs.lean.xyz/preview.md) of an order that would take a route shows the route's costs. |
| `limited_by` | Why the quote covers less than the whole quantity, or `null` when it covers all of it. See below. |
| `expires_at` | Quote again after this time. A quote reserves nothing. |

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:

| `limited_by` | Meaning |
| - | - |
| `depth` | The books fill less than the quantity within the slippage bound, or no venue can place the market. |
| `holdings` | A sell (`action=sell`) for more shares than the trading account holds. The quote covers the shares held. |
| `funds` | The trading account can't pay for the buy on any venue that could place it. |
| `venue_minimum` | The quantity is below the minimum of every venue that could place it. |
| `increment` | No venue that could place the order takes the quantity in its size steps. |

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

```bash theme={"dark"}
curl -sS "$LEAN_API_URL/v1/markets/$MARKET_ID/trades?limit=100" \
  -H "Authorization: Bearer $LEAN_API_KEY"
```

`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

```bash theme={"dark"}
curl -sS "$LEAN_API_URL/v1/markets/$MARKET_ID/candles?interval=1m&start=2026-11-10T12:00:00Z&end=2026-11-10T13:00:00Z" \
  -H "Authorization: Bearer $LEAN_API_KEY"
```

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

| Parameter | Meaning |
| - | - |
| `interval` | `1s`, `1m`, `5m`, `15m`, `1h` or `2h`. Defaults to `1m`. |
| `start` | The first candle opens at or after this time. Defaults to 100 intervals before `end`. |
| `end` | Candles that open before this time. Defaults to now. |

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.

| Venue | Prices | `volume` |
| - | - | - |
| Kalshi, Polymarket, Polymarket US | A NO market reads the YES prices turned over: each price is 1 minus the YES price, so the YES high becomes the NO low. | Shares traded in the venue market in the period, so a YES and a NO market show the same volume. |
| Hyperliquid | Each side has its own trades and its own candles. | Shares of that side traded in the period. |


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