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

# Stop losses and take profits

> Sell shares you hold once the market moves to a price you choose.

A stop loss watches the best bid for shares your trading account holds and sells them when the bid
reaches your trigger price. Lean watches the market for you, so your program does not need to stay
connected. There are two types:

* `stop_loss` sells once the best bid falls to `trigger_price` or below.
* `take_profit` sells once the best bid rises to `trigger_price` or above.

Both 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/stop-losses" \
  -H "Authorization: Bearer $LEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "market_id": "'"$MARKET_ID"'",
    "venue": "polymarket",
    "type": "stop_loss",
    "trigger_price": "0.4",
    "quantity": "25",
    "slippage_limit": "0.05"
  }'
```

| Field | Meaning |
| - | - |
| `market_id` | A `mkt_…` ID from `GET /v1/markets`. |
| `venue` | `kalshi`, `polymarket`, `polymarket_us` or `hyperliquid`: the venue that holds the shares to sell. Shares stay on the venue that bought them, so a stop loss sells on that venue only. |
| `type` | `stop_loss` or `take_profit`. |
| `trigger_price` | The best bid, in dollars per share, that starts the sale. It must fit the market's price ticks and be one the bid has not reached yet: below the current best bid for a `stop_loss`, above it for a `take_profit`. See [Triggers the bid already meets](#triggers-the-bid-already-meets). |
| `quantity` | Shares to sell, as a decimal string. |
| `slippage_limit` | Optional. How far below `trigger_price` the sale may fill, in dollars above `0` and at most `0.2`, on the market's price tick and below `trigger_price`. The default is `0.05`. |
| `expires_at` | Optional. When the stop loss lapses, as an ISO 8601 time. A sale still resting then is canceled. Leave it out to keep the stop loss until you cancel it. |

The key needs the `trade` scope. The answer is `200` with the stop loss, which reads `active` while
it watches the market.

## Triggers the bid already meets

A trigger the best bid has already reached would start the sale on the next price check, so Lean
refuses it with `400 VALIDATION_ERROR` on test and live keys alike. The message names the current
best bid.

* A `stop_loss` with `trigger_price` at or above the best bid is refused. To sell once the bid
  rises, send a `take_profit`.
* A `stop_loss` on a market with no bid is refused too, since an empty bid side starts its sale.
* A `take_profit` with `trigger_price` at or below the best bid is refused. A `take_profit` on a
  market with no bid is accepted and waits for one.

The bid is read from the venue's book when the request arrives. If the book cannot be read, the
request is refused with `503 UPSTREAM_ERROR` and nothing is created; send it again.

## How the sale works

When the best bid reaches the trigger, Lean sells the shares on the venue at once, no lower than
`trigger_price` minus `slippage_limit`. Whatever does not sell straight away rests on the book at
that lowest price until it fills, you cancel it, or `expires_at` passes. Once the trigger is reached
the sale keeps going even if the bid moves back. `triggered_at` and `triggered_price` record when
it was reached and the best bid at that moment, and `filled_quantity` and `avg_fill_price` show what
sold so far.

| `status` | Final | Meaning |
| - | - | - |
| `active` | No | Watching the market. |
| `triggered` | No | The bid reached the trigger and the sale is starting. |
| `executing` | No | Selling right now. |
| `partial` | No | Part of the quantity sold. The rest is resting on the book. |
| `filled` | Yes | Every share sold. |
| `canceled` | Yes | Canceled by you. |
| `expired` | Yes | `expires_at` passed, or the shares were no longer held when the sale started. |
| `failed` | Yes | Lean could not sell, for example because the venue kept refusing the sale. |

## Limits on what can be sold

* The stop losses on the same shares together sell at most what the account holds. Shares already
  offered by a resting sell order count as taken. A stop loss above what is left is refused with
  `400 VALIDATION_ERROR`, and the message says how many shares are available.
* A sale 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"`.
* The sale counts toward the key's and account's rolling day as an order of `quantity` shares at
  `trigger_price` would, from when the stop loss is created. A sale only takes risk off, so neither
  the per order limit nor the daily limit refuses it. A test key's stop losses count toward its own
  day.
* Creating a stop loss is refused with `503 FEATURE_DISABLED` while trading is paused, or while
  Lean has paused stop losses on the venue. See [Pause trading](https://docs.lean.xyz/orders.md#pause-trading).

## Track and cancel

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

Cancel one with `DELETE /v1/stop-losses/{id}`:

```bash theme={"dark"}
curl -sS -X DELETE "$LEAN_API_URL/v1/stop-losses/$STOP_LOSS_ID" \
  -H "Authorization: Bearer $LEAN_API_KEY"
```

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

Pausing trading does not stop a stop loss that is already watching the market. Cancel it if you
want it gone.

## Test keys

A test key's stop loss is checked like a live one, against the market and the test account's
simulated shares, and it can be listed and canceled. It never sells. See
[Test mode and live mode](https://docs.lean.xyz/test-mode.md).


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