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

# Best price execution across venues

> One order, filled at the best combined price across Polymarket and Hyperliquid.

**Who it's for:** prop desks, funds and market makers who trade sports outcomes on more than one venue.

**What you build:** an execution layer that gets one fill at the best combined price across
Polymarket and Hyperliquid, without integrating either venue yourself.

## Call sequence

**1. Find the market**

[List markets](https://docs.lean.xyz/api-reference/markets/list-markets.md) (filter by `league`, `sport` or
`starts_after`), then [Get a market](https://docs.lean.xyz/api-reference/markets/retrieve-market.md).

**2. See the depth**

[Quote a market](https://docs.lean.xyz/api-reference/markets/quote-market.md) prices a size across venues.
[Get a market orderbook](https://docs.lean.xyz/api-reference/markets/retrieve-market-book.md) shows each venue's book.

**3. Preview**

[Preview an order](https://docs.lean.xyz/api-reference/orders/preview-order.md) returns the plan: the legs per venue,
the executable quantity and the slippage check. Nothing is sent.

**4. Place it**

[Place an order](https://docs.lean.xyz/api-reference/orders/create-order.md) with the same body. Lean places the legs
on the venues the plan chose. Set `client_order_id` so a retry returns the same order.

If the cash is on one venue and the book on the other, the same call moves the cash and
buys, and `route` in the response names both venues. See
[Paying from the other venue](https://docs.lean.xyz/orders.md#paying-from-the-other-venue).

Set `best_price: true` to take that route whenever it costs less than buying where the cash
is, even when the cash would cover the buy. See
[Best price across venues](https://docs.lean.xyz/orders.md#best-price-across-venues).

**5. Follow and reconcile**

[Create a stream ticket](https://docs.lean.xyz/api-reference/streaming/create-stream-ticket.md) to follow order,
position and balance updates over the WebSocket, then confirm with
[Get an order](https://docs.lean.xyz/api-reference/orders/retrieve-order.md) and
[List fills](https://docs.lean.xyz/api-reference/orders/list-fills.md).

## Starter

```bash theme={"dark"}
# 1. Price 5 shares across venues
curl -sS "$LEAN_API_URL/v1/markets/$MARKET_ID/quote?quantity=5" \
  -H "Authorization: Bearer $LEAN_API_KEY"

# 2. See the plan; nothing is sent
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":"exec-0001","market_id":"'"$MARKET_ID"'","action":"buy",
       "quantity":"5","limit_price":"0.42","time_in_force":"ioc","max_slippage_bps":50}'

# 3. Place it: send the same body to /v1/orders
```

## Guardrails

* **Price protection.** `limit_price` is the worst price per share you accept, and
  `max_slippage_bps` bounds how far each venue order may trade from that venue's own best price,
  so venues quoting different prices can each fill. `limit_price` caps every venue alike.
* **Fill or nothing.** `all_or_none` with `time_in_force: ioc` places the order only if the books
  can fill the whole quantity. It is best effort: a book can move before the fill, so a partial
  fill is still possible. See [All or none](https://docs.lean.xyz/orders.md#all-or-none). Polymarket takes `ioc` buys by
  dollar amount only, so a buy sized with `quantity` fills on Hyperliquid.
* **Safe retries.** The same `client_order_id` always returns the same order.
* **Spending caps.** Every order is checked against the key's per order and rolling 24 hour
  limits before it reaches a venue.
* **Precise sizing.** Quantities are in steps of 0.01 shares.


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