Trading
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.
On this page
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 and in your 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_repairedevent. - 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:
{
"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.
{
"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), 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:
{ "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:
{ "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
twapandvwap, a slice waits while the price is beyondmax_price(buy) ormin_price(sell), and its size is carried to the next one; whatever is left at the end ends the programprice_bound. Onchase, the same fields are its cap. - Ladders are placed nearest the price first; their
exitsare 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_minutesit is canceled, or what is left goes at the market withon_expiry: "market". - **
reduce_only: true** makes a program only reduce your position: atwapthen ends when the position is closed.
{
"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 notrigger_directionthere: the other way is a stop order, which the trading servers keep themselves. - On another market, name it in
trigger_marketand saytrigger_direction:abovesends the order once that market trades at or abovetrigger_price,belowat 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"andlimit_price. It is checked when it is sent, as an order you place then: if it is refused, the strategy endschild_rejectedand nothing is tried again. A limit then rests until it fills or you cancel it;exitsare 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 itexpiredif its price has not come by then. It may be as far ahead as agtdorder may last (gtd_max_daysinGET /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).
{
"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.
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, 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.