# Exits and strategies

Take-profits and stop-losses that follow your position, trailing stops, break-even, orders worked for you over time, and orders sent once a price is reached.

The API can keep orders working for you on our servers: the exits that protect a position, and strategies that place your entries over time. They keep running while your bot is offline, and every order they place is an ordinary order: you see it in your order lists, on the [account stream](/guides/streams) and in your [webhooks](/guides/webhooks).

## A position's exits

Each position can carry take-profit legs (reduce-only limits on the profit side) and stop-loss legs (reduce-only stops on the loss side), up to 5 take-profits and 3 stop-losses. The API keeps them true to the position at all times:

- **Never more than the position.** The take-profits together, and the stop-losses together, are at most the position's size. When a take-profit fills, the stop-losses shrink by its size; when the last one fills, the others are canceled.
- **They follow the position.** Reduce it, by hand or from a trading platform, and the legs shrink with it, farthest first. Add to it, and they grow with it, keeping their share (`resize_with_position`, on by default), rounded down to the size step.
- **They end with it.** When the position closes, every leg is canceled. When someone else turns it the other way, the legs are canceled. If a leg fills past flat (two legs at the same moment), the small position it opened is closed at once with a reduce-only market order, and you get a `strategy.orphan_repaired` event.
- **They rest on the trading servers** as ordinary orders, so they protect you even while your bot, or the API itself, is offline.

### Read them

`GET /v1/accounts/{account_id}/positions/{market}/exits`:

```json
{
  "data": {
    "account_id": "SANDBOX-00042-001",
    "market": "BTC-USD",
    "strategy_id": "stg_01JAB7Q8XK4M2N5P7R9S3T5V7W",
    "position": { "side": "long", "size": "0.020" },
    "take_profit": [
      { "id": "ord_01JAB7R2M4", "group": "take_profit", "type": "limit", "status": "working", "size": "0.010", "price": "64000.0", "limit_price": null, "trail": null, "break_even": null },
      { "id": "ord_01JAB7R2M5", "group": "take_profit", "type": "limit", "status": "working", "size": "0.010", "price": "65500.0", "limit_price": null, "trail": null, "break_even": null }
    ],
    "stop_loss": [
      { "id": "ord_01JAB7R2M6", "group": "stop_loss", "type": "stop_market", "status": "working", "size": "0.020", "price": "61800.0", "limit_price": null, "trail": { "distance": "350.0" }, "break_even": null }
    ],
    "resize_with_position": true
  }
}
```

A stop-loss with `status: "waiting"` is not on the market yet: it waits for its activation price or its break-even.

### Change them in one go

`PUT` the same address with what you saw and what to do. The API checks first that nothing moved since you read it: if the position or any leg differs, nothing is done and the answer is `409 exits_changed` with the exits as they are now, so you can decide again.

```json
{
  "expected_position": { "side": "long", "size": "0.020" },
  "expected_exits": [
    { "id": "ord_01JAB7R2M4", "size": "0.010", "price": "64000.0" },
    { "id": "ord_01JAB7R2M5", "size": "0.010", "price": "65500.0" },
    { "id": "ord_01JAB7R2M6", "size": "0.020", "price": "61800.0" }
  ],
  "operations": [
    { "op": "cancel", "id": "ord_01JAB7R2M5" },
    { "op": "modify", "id": "ord_01JAB7R2M6", "price": "62500.0" },
    { "op": "place", "group": "take_profit", "price": "66000.0" }
  ]
}
```

The operations run in this order: cancels, then changes, then new legs (stop-losses first). A new leg without a `size` takes what its group leaves of the position. If an order is refused on the way, the batch stops there and `422 exit_operation_failed` says what each operation did.

A leg that waits (a stop-loss with no price yet) goes in `expected_exits` with `"price": null`, as `GET` showed it. When its time comes and the engine refuses it, it is tried again a moment later (1 s, then 2 s), and dropped after 3 refusals in a row; each refusal is a `strategy.leg_rejected` event. To remove a stop-loss's trail or break-even, send it `null` or name it in `clear`: `{ "op": "modify", "id": "ord_01JAB7R2M6", "clear": ["trail"] }` (the SDKs, which cannot always send a `null`, use `clear`).

### Attach them to an order

Send `exits` with the order (see [Orders](/guides/orders#protecting-a-position)), or add them later to a working order with `PUT /v1/accounts/{account_id}/orders/{order_id}/exits` (`{}` removes them). Levels given as a `distance` or a `percent` are taken from the fill price. When the order fills, the stop-loss is placed first, then the take-profits, and from then on they are the position's exits. If the order is canceled, refused or expires, nothing is placed.

## Trailing stops

Give a stop-loss leg a `trail`, `{ "distance": "350" }` or `{ "percent": "1.5" }`, and it follows the best price since it started:

- it moves only toward the price, never back;
- at most once every 1,000 ms, and only by at least one tick and 5% of the distance, so a quiet market does not move it for nothing;
- never through the price, which would fill it at once.

With `activation_price`, it starts only once the price reaches that level. Until then the stop rests at its `price`, or, without one, nothing rests and the leg is `waiting`.

To add one to an open position without a batch, `POST /v1/accounts/{account_id}/strategies`:

```json
{ "type": "trailing_stop", "market": "BTC-USD", "distance": "350", "activation_price": "63500", "replace_stops": true }
```

`size` defaults to what the other stop-losses leave of the position; `initial_stop_price` sets where it rests before the trail first moves it; `replace_stops: true` cancels the position's other stop-losses first. The answer is the position's exits strategy.

## Break-even

Give a stop-loss leg a `break_even` and it moves to your entry once the trade has gone your way:

```json
{ "type": "break_even", "market": "BTC-USD", "trigger_distance": "300", "offset_ticks": 2 }
```

Once the price is `trigger_distance` (or `trigger_percent`) past the entry, or reaches `trigger_price`, the stop-losses move once to the entry plus `offset_ticks` on the profit side, and never back. If the price is already through that level, the move waits for the price to come back to it. A break-even leg with no price of its own is placed only at that moment.

Trailing stops and break-even move on market prices straight from the exchanges. If those prices pause, the stops stay where they are and keep protecting.

## Strategies that place orders

`POST /v1/accounts/{account_id}/strategies` also starts programs that work an entry for you. Each order a program places is checked exactly like an order you place yourself: your key's limits, the size step, the minimum size.

| `type` | What it does | Its fields |
|---|---|---|
| `oco` | Two resting orders; the first fill cancels the other | `orders`: the two orders (`limit`, `stop_market` or `stop_limit`); `exits`, placed on the fill |
| `twap` | The size in market slices at even times | `side`, `size`, `duration_minutes` (5 to 1,440), `interval_seconds` (at least 30, at most half the duration; 60 when not given), `randomize`, `max_slippage_pct` |
| `vwap` | Like `twap`, each slice sized by yesterday's volume over the same hours (UTC) | The same as `twap` |
| `scaled` | A ladder of limits between two prices | `side`, `size`, `start_price`, `end_price`, `rungs` (2 to 10), `distribution` (`flat`, `ascending`, `descending`), `post_only`, `all_or_none`, `allow_marketable`, `exits` |
| `chase` | A limit that follows the bid (buy) or the ask (sell) | `side`, `size`, `offset_ticks`, `max_minutes` (up to 60), `on_expiry` (`cancel` or `market`), `allow_cross` |
| `conditional` | An order sent once a price is reached, on this market or another one | `side`, `size`, `trigger_price`, `trigger_market` and `trigger_direction` (another market), `order_type` (`market` or `limit`, with `limit_price`), `max_slippage_pct`, `expires_at`, `exits` |

A few rules worth knowing:

- **Price bounds.** On `twap` and `vwap`, a slice waits while the price is beyond `max_price` (buy) or `min_price` (sell), and its size is carried to the next one; whatever is left at the end ends the program `price_bound`. On `chase`, the same fields are its cap.
- **Ladders** are placed nearest the price first; their `exits` are placed on the first fill and grow with the next ones.
- **A chase** moves at most every 2,000 ms and never past its cap. At `max_minutes` it is canceled, or what is left goes at the market with `on_expiry: "market"`.
- **`reduce_only: true`** makes a program only reduce your position: a `twap` then ends when the position is closed.

```json
{
  "type": "twap",
  "market": "BTC-USD",
  "side": "buy",
  "size": "0.500",
  "duration_minutes": 60,
  "interval_seconds": 120,
  "max_slippage_pct": "0.5",
  "client_strategy_id": "accumulate-btc-oct"
}
```

### Conditional orders

A `conditional` waits on our servers for a price, then sends its order. Nothing rests on the trading servers until then (its status is `waiting`), so it costs no margin while it waits.

- **On its own market**, it is an entry that waits for the price to come to you: a buy is sent once the price falls to `trigger_price`, a sell once it rises to it. You give no `trigger_direction` there: the other way is a stop order, which the trading servers keep themselves.
- **On another market**, name it in `trigger_market` and say `trigger_direction`: `above` sends the order once that market trades at or above `trigger_price`, `below` at or below it. Buy ETH when BTC breaks a level, for example.
- **The price it watches** is the market's last trade (the middle of the book until there is one), the same price trailing stops follow.
- **Its order** is a market order, or a limit with `order_type: "limit"` and `limit_price`. It is checked when it is sent, as an order you place then: if it is refused, the strategy ends `child_rejected` and nothing is tried again. A limit then rests until it fills or you cancel it; `exits` are placed on the fill.
- **A price already reached** is refused (`trigger_already_met`, with the price now): send the order yourself instead.
- **`expires_at`** (milliseconds) ends it `expired` if its price has not come by then. It may be as far ahead as a `gtd` order may last (`gtd_max_days` in `GET /v1/limits`); without it, it waits that long. Once its order is sent, the order stands on its own.
- While market prices pause, it waits; the first price after the pause sends it if the level was crossed meanwhile. When the trading servers restart, it ends with every strategy (`engine_restart`).

```json
{
  "type": "conditional",
  "market": "ETH-USD",
  "side": "buy",
  "size": "0.50",
  "trigger_market": "BTC-USD",
  "trigger_price": "120000",
  "trigger_direction": "above",
  "exits": { "stop_loss": { "percent": "2" } },
  "client_strategy_id": "eth-on-btc-breakout"
}
```

Send an `Idempotency-Key` header as you do with orders, so a retry never starts a program twice. You can also give it your own `client_strategy_id`, unique in its environment: a second program with the same one is refused with `client_strategy_id_conflict`, naming the first. A program whose orders are refused as it starts (an oco or a chase whose order is refused, a ladder whose every rung is) made nothing: the call answers the refusal, no strategy is left behind and the `client_strategy_id` is free. A ladder with some rungs refused starts with the others; each refused rung names its order.

## Follow and stop a strategy

`GET .../strategies` lists them (filter with `status`, `market` or `client_strategy_id`); `GET .../strategies/{strategy_id}` answers one with its `progress` (slices sent, size carried, the next slice's time) and every order it placed. Each step is also an event: `strategy.created`, `strategy.leg_placed`, `strategy.leg_modified`, `strategy.leg_filled`, `strategy.slice`, `strategy.triggered` (a conditional's price came), `strategy.ended` and the others in the [stream's events](/guides/streams#events).

| `status` | Meaning |
|---|---|
| `waiting` | Armed, nothing placed yet |
| `working` | Running |
| `completed` | Done as asked (`end_reason`: `filled`, `take_profit` or `stop_loss`) |
| `canceled` | You stopped it (`end_reason`: `canceled_by_user`) |
| `ended` | It stopped by itself; `end_reason` says why |

`DELETE .../strategies/{strategy_id}` stops a strategy and cancels its working orders. What already filled stays: a position it opened is still open.

### Why a strategy ends

| `end_reason` | What happened |
|---|---|
| `position_closed` | The position its exits protected was closed |
| `position_reversed` | Someone else turned the position the other way |
| `external` | Its order was canceled outside the API, from a trading platform for example |
| `child_rejected` | Its orders were refused: a twap's or vwap's slices 3 times in a row, every rung of a ladder, or a conditional's order when its price came |
| `price_bound` | The price stayed beyond its bound until the end (a slice refused at the end is `child_rejected`) |
| `expired` | Its time ran out |
| `key_revoked` | The key that started a program was revoked or expired. A position's exits keep protecting |
| `account_closed` | The account can no longer trade |
| `engine_restart` | The trading servers restarted: as with [orders](/guides/orders#when-the-engine-restarts), nothing is placed again by itself |

## Limits

An account holds 25 running strategies, of which 5 programs (oco, twap, vwap, scaled, chase, conditional: the exits attached to an order are no program), with 40 working orders between them; a customer holds 100 across accounts. Past a limit, a new strategy is refused with `strategy_limit`, its `details` naming the limit. Your code can read every one of these numbers from `GET /v1/limits`, under `strategies`.
