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

# Quickstart

> From a new key to a filled test order in one call.

These examples use two environment variables:

```bash theme={"dark"}
export LEAN_API_URL="https://api.lean.xyz"
export LEAN_API_KEY="lean_sk_test_..."
```

`LEAN_API_URL` is the Lean API. Test and live keys use the same URL; the key decides the mode.
Start with a test key: orders and fills are simulated and no money moves. To create a key, sign in to Lean, open
Settings (the gear) and choose **API**. [Authentication](https://docs.lean.xyz/authentication.md#create-a-key) explains its
limits, and [Test mode and live mode](https://docs.lean.xyz/test-mode.md) shows how to switch to a live key when you're ready.

**1. Find a market**

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

Pick a market whose `legs` include one with `tradable: true`, and keep its `id`:

```bash theme={"dark"}
export MARKET_ID="mkt_..."
```

[Markets and IDs](https://docs.lean.xyz/markets.md) explains each field.

**2. Place the order**

One call places the order. Lean picks the venues among Kalshi, Polymarket, Polymarket US and
Hyperliquid. If the book is on Polymarket and the account's cash on Hyperliquid, or the other
way round, it moves the cash and buys on the venue with the book:

```bash theme={"dark"}
curl -sS -X POST "$LEAN_API_URL/v1/orders" \
  -H "Authorization: Bearer $LEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_order_id": "bot-2026-10-29-0001",
    "market_id": "'"$MARKET_ID"'",
    "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. A test order fills at once at the best price on the book, up to
the size shown there and within your limit:

```json theme={"dark"}
{
  "success": true,
  "data": {
    "id": "3f6c2a8e-91d4-4b7a-8c25-0e4d7b19a6f3",
    "client_order_id": "bot-2026-10-29-0001",
    "action": "buy",
    "quantity": "5",
    "filled_quantity": "5",
    "limit_price": "0.42",
    "avg_fill_price": "0.41",
    "status": "filled",
    "legs": [ … ],
    "route": null,
    "livemode": false
  },
  "meta": { "requestId": "<request id>" }
}
```

`route` is `null` when the order was paid for on the venue it bought on, which is always the
case on Kalshi and Polymarket US. When Lean paid with cash from the other venue, its
`funding_venue` names the venue the cash came from and its `execution_venue` the venue it
bought on, with the route's `notional_usd` and `costs`.
See [Paying from the other venue](https://docs.lean.xyz/orders.md#paying-from-the-other-venue).

> [!WARNING]
>
> An accepted response is not a fill. Read `status` and `filled_quantity`, and confirm them
> with the steps below.

**3. Read it back**

```bash theme={"dark"}
export ORDER_ID="3f6c2a8e-91d4-4b7a-8c25-0e4d7b19a6f3"
curl -sS "$LEAN_API_URL/v1/orders/$ORDER_ID" \
  -H "Authorization: Bearer $LEAN_API_KEY"
```

Use the `id` from your own response. If the response never arrived, look the order up by
`client_order_id` instead: `GET /v1/orders?client_order_id=bot-2026-10-29-0001`.

**4. Reconcile**

```bash theme={"dark"}
curl -sS "$LEAN_API_URL/v1/positions" -H "Authorization: Bearer $LEAN_API_KEY"
curl -sS "$LEAN_API_URL/v1/balances" -H "Authorization: Bearer $LEAN_API_KEY"
```

See [Orders and idempotency](https://docs.lean.xyz/orders.md#reconcile).

## Quote and preview first

Before you trade live, check what an order would do. Neither call places or reserves anything.

```bash theme={"dark"}
# How a buy of 5 shares would fill: price per venue, expected_total_usd, max_total_usd and fees
curl -sS "$LEAN_API_URL/v1/markets/$MARKET_ID/quote?quantity=5" \
  -H "Authorization: Bearer $LEAN_API_KEY"

# The exact order body: check would_submit and warnings
curl -sS -X POST "$LEAN_API_URL/v1/orders/preview" \
  -H "Authorization: Bearer $LEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_order_id": "bot-2026-10-29-0001",
    "market_id": "'"$MARKET_ID"'",
    "action": "buy",
    "quantity": "5",
    "limit_price": "0.42",
    "time_in_force": "ioc"
  }'
```

Quote again after `expires_at`. See [Preview](https://docs.lean.xyz/preview.md).

A preview checks the order against the cash on the venues that could place it. When Lean would
[pay from the other venue](https://docs.lean.xyz/orders.md#paying-from-the-other-venue), `route` names both venues and
`would_submit` is `true`. A blocking warning means the order would be refused.

## Try it in the API reference

Every page under [API reference](https://docs.lean.xyz/api-reference/markets/list-markets.md) has a **Try it** button
that sends a real request with your key and shows the response.

1. In Lean, open Settings (the gear), choose **API**, and
   [create a test key](https://docs.lean.xyz/authentication.md#create-a-key) with **Create API key**. Keep the **Test** mode
   and **Read and trade** access.
2. Open [List markets](https://docs.lean.xyz/api-reference/markets/list-markets.md) and click **Try it**.
3. Under **Server**, set `baseUrl` to your `LEAN_API_URL`, without `/v1`.
4. Under **Authorization**, paste your test key. The playground adds `Bearer` for you.
5. Click **Send**, then copy a market `id` from the response.
6. Open [Create an order](https://docs.lean.xyz/api-reference/orders/create-order.md) and send it. The body fields start
   filled with an example; replace `market_id` and set your own `client_order_id`.
7. Copy the order `id` from the response, and read it back with
   [Get an order](https://docs.lean.xyz/api-reference/orders/retrieve-order.md).

> [!WARNING]
>
> The key decides the mode. With a test key, **Send** on Create an order simulates the order. With
> a live key, it places a real order against the key's trading account. Use a test key while you
> experiment.

Each page also shows the request as cURL, Python and JavaScript, with example responses for
success and for each error status.

## Using TypeScript

The [TypeScript SDK](https://docs.lean.xyz/typescript-sdk.md) runs these same steps with typed methods:
`npm install @leanxyz/api-sdk`, then `listMarkets`, `previewOrder`, `createOrder` and `getOrder`
with the same `LEAN_API_URL` and `LEAN_API_KEY`.

## Using Rust

The [Rust SDK](https://docs.lean.xyz/rust-sdk.md) runs the same steps as async methods: add `lean-api-sdk` from crates.io with
Tokio, then `list_markets`, `preview_order`, `create_order` and `get_order` with the same
`LEAN_API_URL` and `LEAN_API_KEY`.

## Python

```python theme={"dark"}
import os
import uuid

import requests

BASE = os.environ["LEAN_API_URL"]
HEADERS = {"Authorization": f"Bearer {os.environ['LEAN_API_KEY']}"}


def call(method, path, **kwargs):
    response = requests.request(method, f"{BASE}{path}", headers=HEADERS, timeout=30, **kwargs)
    body = response.json()
    if not body["success"]:
        error = body["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']}")
    return body["data"]


market = call("GET", "/v1/markets", params={"league": "nfl", "limit": 1})["markets"][0]
print(market["fixture"]["title"], market["group"]["label"], market["outcome"])

# Save client_order_id before sending, and reuse it on every retry of this order.
order = call("POST", "/v1/orders", json={
    "client_order_id": f"bot-{uuid.uuid4().hex[:16]}",
    "market_id": market["id"],
    "action": "buy",
    "quantity": "5",
    "limit_price": "0.42",
    "time_in_force": "ioc",
})
print(order["id"], order["status"], order["filled_quantity"], order["route"])
print(call("GET", f"/v1/orders/{order['id']}")["status"])
```


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