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

# Lean API v0.1

> List canonical sports markets, quote them, place orders and reconcile, without naming a venue.

**v0.1**Sports markets in preview
Trade sports markets from code.

One API for canonical sports markets, quotes and orders. Name the outcome you want; Lean finds
the venue across Kalshi, Polymarket, Polymarket US and Hyperliquid, prices the route and places
the order.

[Start the quickstart](https://docs.lean.xyz/quickstart.md)
[Browse the API reference](https://docs.lean.xyz/api-reference/markets/list-markets.md)

**REST and WebSocket**One JSON envelope**Idempotent orders**Retry without doubling**OpenAPI 3**Generate any client

## One call to buy

With a test key, nothing real moves:

```bash theme={"dark"}
curl -sS -X POST "https://api.lean.xyz/v1/orders" \
  -H "Authorization: Bearer $LEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_order_id": "bot-2026-11-02-0001",
    "market_id": "mkt_...",
    "action": "buy",
    "quantity": "5",
    "limit_price": "0.42",
    "time_in_force": "ioc"
  }'
```

Polymarket takes `ioc` buys by dollar amount only. On a market only Polymarket lists, send
`"notional": "25"` in place of `quantity`; see [Limitations](https://docs.lean.xyz/orders.md#limitations).

The response is the order. If the book was on Polymarket and the account's cash on Hyperliquid, or
the other way round, Lean moved the cash and bought on the venue with the book, and `route` says
so; otherwise `route` is `null`:

```json theme={"dark"}
{
  "success": true,
  "data": {
    "id": "3f6c2a8e-91d4-4b7a-8c25-0e4d7b19a6f3",
    "client_order_id": "bot-2026-11-02-0001",
    "status": "filled",
    "filled_quantity": "5",
    "avg_fill_price": "0.42",
    "route": { "funding_venue": "hyperliquid", "execution_venue": "polymarket" },
    "livemode": false
  },
  "meta": { "requestId": "<request id>" }
}
```

Read it back by `id`:

```bash theme={"dark"}
curl -sS "https://api.lean.xyz/v1/orders/3f6c2a8e-91d4-4b7a-8c25-0e4d7b19a6f3" \
  -H "Authorization: Bearer $LEAN_API_KEY"
```

See [Orders and idempotency](https://docs.lean.xyz/orders.md) for every field.

## From a new key to a reconciled trade in five calls

Every step is a plain HTTPS request with a bearer key. The [TypeScript SDK](https://docs.lean.xyz/typescript-sdk.md) and
the [Rust SDK](https://docs.lean.xyz/rust-sdk.md) make each one a typed method.

<ol>
  <li>
    01
    Create a key
    Start with a test key that simulates fills. Each key has its own per order and daily limit.
    [Authentication](https://docs.lean.xyz/authentication.md)
  </li>

  <li>
    02
    Find a market
    List canonical sports markets. You name the outcome; Lean knows the venues.
    [GET`/v1/markets`](https://docs.lean.xyz/markets)
  </li>

  <li>
    03
    Place the order
    One limit order with your own ID, on any venue and safe to retry on a dropped connection.
    [POST`/v1/orders`](https://docs.lean.xyz/orders)
  </li>

  <li>
    04
    Read it back
    Read the order by its ID to see its status and fills.
    [GET`/v1/orders/{id}`](https://docs.lean.xyz/orders#track-and-cancel)
  </li>

  <li>
    05
    Reconcile
    Read positions and balances back until the books agree.
    [GET`/v1/positions`](https://docs.lean.xyz/orders#reconcile)
  </li>
</ol>

## Designed for programs that move money

> [card] [Preview before you trade](https://docs.lean.xyz/preview.md)
>
> `POST /v1/orders/preview` takes the exact order body and returns the venue, route plan and
> refusals, with a read only key.

> [card] [Retries are safe](https://docs.lean.xyz/orders.md#idempotency)
>
> Every order carries your `client_order_id`. Sending it again returns the original order, never
> a second order.

> [card] [Limits live on the key](https://docs.lean.xyz/authentication.md)
>
> Each key has its own per order and rolling daily notional limit, checked before anything
> reaches a venue.

> [card] [One shape everywhere](https://docs.lean.xyz/errors.md)
>
> `{ success, data, meta }` on success and a stable error `code` on failure, with a request ID to
> quote when you report a problem.

## Conventions

* Every response uses one envelope: `{ "success": true, "data": …, "meta": … }` or
  `{ "success": false, "error": { "code", "message", "details" }, "meta": … }`.
* `meta.requestId` (also sent as the `X-Request-ID` header) identifies the request. Include it when
  you report a problem.
* Prices are decimal strings in dollars per share, strictly between `0` and `1`.
* Quantities are shares, as decimal strings. Amounts are USD, as decimal strings.
* Field names are `snake_case`.
* `data.livemode` in every successful response is `false` for a test key and `true` for a live key. See
  [Test mode and live mode](https://docs.lean.xyz/test-mode.md).

## What the API covers

| Capability | Endpoint |
| - | - |
| Discover markets | `GET /v1/markets`, `GET /v1/markets/{id}` |
| Prices, depth, trades and candles | `GET /v1/prices`, `GET /v1/markets/{id}/book`, `GET /v1/markets/{id}/trades`, `GET /v1/markets/{id}/candles` |
| Quote across venues | `GET /v1/markets/{id}/quote` |
| Preview orders without placing them | `POST /v1/orders/preview`, `POST /v1/orders/preview-batch` |
| Place an order on any venue | `POST /v1/orders` |
| Read, amend and cancel orders | `GET /v1/orders`, `GET /v1/orders/{id}`, `PATCH /v1/orders/{id}`, `POST /v1/orders/{id}/cancel`, `POST /v1/orders/cancel-batch`, `POST /v1/orders/cancel-all`, `POST /v1/orders/cancel-after` |
| Stop losses and limit chases | `/v1/stop-losses`, `/v1/limit-chases` |
| Fills | `GET /v1/fills` |
| Balances, positions, PnL and risk | `GET /v1/balances`, `GET /v1/positions`, `POST /v1/positions/close`, `GET /v1/pnl`, `GET /v1/pnl/history`, `GET /v1/risk` |
| Deposits, on Polymarket and Hyperliquid | `GET /v1/deposits/assets`, `GET /v1/deposits/addresses`, `POST /v1/deposits/addresses` |
| Withdrawals, from Polymarket and Hyperliquid | `POST /v1/withdrawals`, `GET /v1/withdrawals`, `GET /v1/withdrawals/{id}` |
| Transfers between Polymarket and Hyperliquid | `POST /v1/transfers/quote`, `POST /v1/transfers`, `POST /v1/transfers/{id}/execute`, `GET /v1/transfers` |
| Live updates | `POST /v1/ws/token`, then the `/v1/ws` WebSocket |
| Account controls | `GET /v1/account/config`, `POST /v1/account/limits`, `POST /v1/account/pause` |
| Test mode | `POST /v1/test/reset` |
| Self-signed routed orders, on Polymarket and Hyperliquid ([advanced](https://docs.lean.xyz/routed-orders.md)) | `POST /v1/routed-orders`, `POST /v1/routed-orders/{id}/execute` |
| Manage API keys, signed in | `POST /api-keys`, `GET /api-keys`, `DELETE /api-keys/{id}` |

### How it works

* Markets cover the full game of a sports match only. Halves, quarters and periods are not listed.
* Lean chooses the venues. A buy is split across eligible venues by best price; a sell takes the
  best bids across the venues that hold the shares.
* Between Polymarket and Hyperliquid, a buy can pay with cash on the other venue: Lean moves it and
  buys on the venue with the book, in the same call. Kalshi and Polymarket US orders pay with the
  cash already on that venue. Shares can't move between venues.
* Live orders route to Kalshi, Polymarket, Polymarket US and Hyperliquid. Test orders are simulated
  and never reach a venue.
* Kalshi and Polymarket US are user wide accounts: every trading account of a user shares the same
  Kalshi and Polymarket US balances and positions, and live orders there use the venue API key the
  user connected in the Lean app.
* Deposits, transfers, withdrawals and routed orders cover Polymarket and Hyperliquid only.
* Quotes price buys, and sells of shares the account holds.
* Hyperliquid does not cancel resting orders at kickoff. See [Orders](https://docs.lean.xyz/orders.md#kickoff).


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