Skip to main content
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:
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.

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.

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}:
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.