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

# Limit chases

> Rest a limit order near the best price and let Lean move it as the book moves.

A limit chase rests a post only limit order a set distance behind the best price on its own side of
the book, and moves it whenever that price moves, until the order fills, you cancel it, or it
expires. A buy follows the best bid and a sell follows the best ask. Lean moves the order for you,
so your program does not need to stay connected.

Limit chases run on every venue: Kalshi, Polymarket, Polymarket US and Hyperliquid. This example
uses a test key, so nothing real moves:

```bash theme={"dark"}
curl -sS -X POST "$LEAN_API_URL/v1/limit-chases" \
  -H "Authorization: Bearer $LEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "market_id": "'"$MARKET_ID"'",
    "venue": "polymarket",
    "action": "buy",
    "quantity": "25",
    "offset_ticks": 1,
    "price_limit": "0.45"
  }'
```

| Field | Meaning |
| - | - |
| `market_id` | A `mkt_…` ID from `GET /v1/markets`. |
| `venue` | `kalshi`, `polymarket`, `polymarket_us` or `hyperliquid`: the venue the order rests on. |
| `action` | `buy` or `sell`. |
| `quantity` | Shares to buy or sell, as a decimal string. |
| `offset_ticks` | Optional. How many price ticks behind the best price the order rests, from `0` to `10`. The default is `0`, resting at the best price. |
| `offset_price` | Optional. The same distance in dollars, from `0` to `0.1`. Give `offset_ticks` or `offset_price`, not both. |
| `price_limit` | Optional. The worst price the order rests at, in dollars: a buy never rests above it and a sell never below it. It must fit the market's price ticks. Leave it out to follow the book wherever it goes. |
| `expires_at` | Optional. When the limit chase lapses if it has not filled, as an ISO 8601 time. Leave it out to keep it until you cancel it. |

The key needs the `trade` scope. The answer is `200` with the limit chase, which reads `active`
while it follows the book. `current_price` is the price the order rests at now, and is `null` while
the chase waits for a book to follow.

## How the order moves

Lean places the order at the best price on its own side less the offset for a buy, or plus the
offset for a sell. It never rests at a price that would trade at once against the other side of the
book, and never beyond `price_limit`. When the best price moves by a cent or more, Lean cancels the
order and places it again at the new price. Each fill adds to `filled_quantity` and
`avg_fill_price`, and the rest keeps following the book.

| `status` | Final | Meaning |
| - | - | - |
| `active` | No | Resting on the book and following the best price. |
| `filled` | Yes | Every share bought or sold. |
| `canceled` | Yes | Canceled by you. Shares already bought or sold stay with the account. |
| `expired` | Yes | `expires_at` passed before the order filled. |
| `failed` | Yes | Lean could not keep the order on the book, for example because the venue kept refusing it. |

## Limits on what can be traded

* A sell takes shares the account holds, and shares already offered by a resting sell order or
  covered by a stop loss count as taken. A sell above what is left is refused with
  `400 VALIDATION_ERROR`.
* A test key's buy needs enough simulated cash on the venue for `quantity` shares at
  `price_limit`, or at \$1 a share without one, and is refused with `400 VALIDATION_ERROR`
  otherwise. A live key's buy is not checked against the account's cash when you create it, so
  check `GET /v1/balances` first: the venue refuses an order the account can't pay for.
* An order must be at least the market's minimum number of shares.
* The market must be open and must trade on the venue you name. A market that cannot be traded on
  that venue is refused with `422 VALIDATION_ERROR` and `details.reason: "NO_EXECUTABLE_VENUE"`,
  and a venue the trading account does not allow with `details.reason: "VENUE_NOT_ALLOWED"`.
* A limit chase counts against the key's limits as an order of the most it can trade for, from when
  it is created: a buy as `quantity` shares at `price_limit`, or at the top price of \$1 a share
  without one, and a sell at that same top price. A buy above the key's per order limit is refused
  with `details.reason: "ORDER_NOTIONAL_LIMIT"`, and one past the key's or account's daily limit
  with `details.reason: "DAILY_NOTIONAL_LIMIT"`. A sell counts toward the day too, but only takes
  risk off, so neither limit refuses it. A test key's limit chases count against its own limits.
* Creating a limit chase is refused with `503 FEATURE_DISABLED` while trading is paused, or while
  Lean has paused limit chases on the venue. See [Pause trading](https://docs.lean.xyz/orders.md#pause-trading).

## Track and cancel

`GET /v1/limit-chases` lists the limit chases of the key's trading account, newest first: every one
still active, and those that ended in the last hour. A live key also sees the limit chases made in
the Lean app on that account. `GET /v1/limit-chases/{id}` reads one.

Cancel one with `DELETE /v1/limit-chases/{id}`:

```bash theme={"dark"}
curl -sS -X DELETE "$LEAN_API_URL/v1/limit-chases/$LIMIT_CHASE_ID" \
  -H "Authorization: Bearer $LEAN_API_KEY"
```

The answer is `200` with the limit chase and `cancel_requested_at` set. A live limit chase keeps its
status for a moment while Lean cancels its resting order, then reads `canceled`. A test limit chase
reads `canceled` at once. Canceling works while trading is paused, and a limit chase that has
already ended is refused with `400 VALIDATION_ERROR`.

Pausing trading does not stop a limit chase that is already on the book. Cancel it if you want it
gone.

## Test keys

A test key's limit chase is checked like a live one, against the market and the test account's
simulated cash and shares. It follows the venue's public book and fills in simulation once the best
price on the other side reaches its price. It is brought up to date with the book each time you
list or read it, so its price and fills change between reads. It never reaches the venue, and its
fills show in the test account's positions and balances. See [Test mode and live mode](https://docs.lean.xyz/test-mode.md).

## Fills

A limit chase is not an order you placed, so its fills are listed in `GET /v1/fills` with `order_id`
set to `null`, and `GET /v1/fills?order_id=` never returns them. A live key sees each fill the venue
reports for the chase's resting order. A test key sees one fill per limit chase for what it has
filled so far, at `avg_fill_price`, with `liquidity` `maker` and `filled_at` the time the chase was
created. It is listed once something fills and grows as more fills, keeping the same `id`.


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