Protect a position

Protect a position with a bracket: up to three take profits and up to three stop losses, placed with the entry, on an entry that’s already resting, or on a position you already hold. Use this page when your trading program places entries and has to keep them protected as the market moves. trdrs lays a bracket out as pairs along the position, nearest the entry first. Each pair is a take profit and a stop loss for one stretch of the position, and when one of them fills, the other is cancelled. By the end you have placed an entry with a bracket, protected a position you hold, moved a stop loss, set a stop loss that moves itself, and read back what’s resting.

Before you start

The examples use the variables from the programmatic quickstart and trade ESZ6, the December 2026 E-mini S&P 500 contract, on a Demo in production. A Demo prices futures only from your own futures login, as Place your first order explains, so in the sandbox you run the same calls on HYPERLIQUID:BTC, sized in bitcoin, as Test it end to end does. The TypeScript SDK isn’t published, so call the routes over HTTP, as the curl examples do. The TypeScript examples show the same calls through the SDK’s client, with provider and account set. Check that the account can hold a bracket first. The capabilities of the account snapshot carry exitHolding, which is none where the provider holds no take profits or stop losses, and exitSupport, the parts of a bracket the account can run. A Demo supports all of them.

Place an entry with its bracket

Send exits with the order. This one buys 2 contracts and takes profit on them in two steps, one contract at a time, with one stop loss under both.

curl -X POST "$TRDRS_API_BASE_URL/api/trading/order?provider=$PROVIDER&account=$ACCOUNT" \
  -H "Authorization: Bearer $TRDRS_TRADING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instrument": "ESZ6",
    "side": "buy",
    "qty": 2,
    "orderType": "limit",
    "limitPrice": 6480.5,
    "tif": "day",
    "clientOrderId": "entry-esz6-1",
    "exits": {
      "takeProfits": [{ "quantity": 1, "price": 6488.5 }, { "quantity": 1, "price": 6495 }],
      "stopLosses": [{ "quantity": 2, "price": 6472.5 }]
    }
  }'

const entry = await client.trading.placeAnOrder({
  provider,
  account,
  instrument: 'ESZ6',
  side: 'buy',
  qty: 2,
  orderType: 'limit',
  limitPrice: 6480.5,
  tif: 'day',
  clientOrderId: 'entry-esz6-1',
  exits: {
    takeProfits: [{ quantity: 1, price: 6488.5 }, { quantity: 1, price: 6495 }],
    stopLosses: [{ quantity: 2, price: 6472.5 }],
  },
})

The two take profits and the stop loss make two pairs: the first contract’s take profit at 6488.50 with its share of the stop loss, and the second contract’s at 6495 with the rest of it. Size each leg by quantity, in the instrument’s own unit, or by share of the order in percent. Place it at a price, or at a distance from the entry in the bracket’s unit: ticks, price, percent, pips where the instrument has a pip, or currency, what the leg makes or loses in the instrument’s settlement currency.The response carries bracket, with its id. Keep it as BRACKET_ID: every change names it. trdrs records the bracket before it sends the entry. While the limit rests, the bracket is pending_entry, and each pair starts protecting the moment the part of the position it covers fills. attached is true where the provider holds the pairs with the entry itself.

Protect a position you already hold

Send a bracket to Protect a position. Distances are measured from the position’s average entry, and every price must clear the market on the side it protects, since a stop loss already past the market would close the position at once. This example sets a take profit 58 ticks above the average entry and a stop loss 32 ticks below, each for the whole position.

curl -X POST "$TRDRS_API_BASE_URL/api/trading/exits?provider=$PROVIDER&account=$ACCOUNT" \
  -H "Authorization: Bearer $TRDRS_TRADING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instrument": "ESZ6",
    "clientOrderId": "protect-esz6-1",
    "exits": {
      "unit": "ticks",
      "takeProfits": [{ "share": 100, "distance": 58 }],
      "stopLosses": [{ "share": 100, "distance": 32 }]
    }
  }'

const protection = await client.trading.protectAPosition({
  provider,
  account,
  instrument: 'ESZ6',
  clientOrderId: 'protect-esz6-1',
  exits: {
    unit: 'ticks',
    takeProfits: [{ share: 100, distance: 58 }],
    stopLosses: [{ share: 100, distance: 32 }],
  },
})

The response names the bracket, with its id and state, and carries refused, the provider’s reason where it refused a pair, whose stretch the bracket then shows as unprotected. clientOrderId makes a retry of the same request safe.The bracket covers qty of the position when you send one, and otherwise all of the position that no other bracket protects. A position the account’s brackets already protect is refused with 409 position_protected and the bracketId to change instead.On an account that holds each entry as its own ticket, send the ticket’s positionId from the account frame to protect that ticket alone.

Move a stop loss

Send the bracket’s ladders as they should be to Change a bracket. A leg that keeps its place in its ladder keeps its id and moves. Here the stop loss moves up to 6478.50 and both take profits stay.

curl -X PUT "$TRDRS_API_BASE_URL/api/trading/exits/$BRACKET_ID?provider=$PROVIDER&account=$ACCOUNT" \
  -H "Authorization: Bearer $TRDRS_TRADING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exits": {
      "takeProfits": [{ "quantity": 1, "price": 6488.5 }, { "quantity": 1, "price": 6495 }],
      "stopLosses": [{ "quantity": 2, "price": 6478.5 }]
    }
  }'

await client.trading.changeABracket({
  provider,
  account,
  id: entry.bracket!.id,
  exits: {
    takeProfits: [{ quantity: 1, price: 6488.5 }, { quantity: 1, price: 6495 }],
    stopLosses: [{ quantity: 2, price: 6478.5 }],
  },
})

A change is all or nothing. The new layout rests before the old one is cancelled, so the position is never without its stop loss, and if the provider refuses any pair, the bracket stays exactly as it was and refused says why. A take profit or a stop loss of a bracket changes only this way: moving its order with Replace an order is refused with 409 bracket_order.To take the bracket down and keep the position, withdraw it:

curl -X DELETE "$TRDRS_API_BASE_URL/api/trading/exits/$BRACKET_ID?provider=$PROVIDER&account=$ACCOUNT" \
  -H "Authorization: Bearer $TRDRS_TRADING_API_KEY"

Every order the bracket rests is cancelled, the bracket ends as cancelled, and the position stays open.

Let a stop loss move itself

A stop loss can move to breakeven once, and trail the price in up to three tiers. trdrs moves it on every provider that holds a bracket, so your program doesn’t have to. Write the rules on the stop loss, with the unit they’re in:

"exits": {
  "unit": "ticks",
  "takeProfits": [{ "quantity": 1, "price": 6488.5 }, { "quantity": 1, "price": 6495 }],
  "stopLosses": [{
    "quantity": 2,
    "price": 6472.5,
    "breakeven": { "trigger": 8, "plus": 1 },
    "trail": [{ "trigger": 16, "distance": 8, "frequencyTicks": 2 }]
  }]
}

Once the position is 8 ticks in profit, the stop loss moves to 1 tick past the entry. From 16 ticks in profit it follows the best price 8 ticks behind, moving each time the price has gained 2 more ticks. A stop loss that moves itself only ever tightens. The same rules work in an entry’s exits, a protection and a change.

Read what's actually resting

List brackets returns the protection around each position: its ladders, the orders resting for them, and how each stop loss that moves itself is running.

curl "$TRDRS_API_BASE_URL/api/account/brackets?provider=$PROVIDER&account=$ACCOUNT" \
  -H "Authorization: Bearer $TRDRS_TRADING_API_KEY"

const { items } = await client.account.listBrackets({ provider, account })

If you already hold an account snapshot or an account stream frame, you don’t need this call: the same brackets array is in both, at the same moment as the positions and orders.

Protect a resting order

Put a bracket on an entry you’ve already placed, before it fills, by naming the order in entryOrderId in place of a position. Use this when your program places an entry first and decides its protection afterwards, or when a trader drags a take profit or a stop loss off a resting order on a chart. Here ORDER_ID, and orderId in TypeScript, hold the entry’s providerOrderId, as the order’s response or the account’s working orders give it.

curl -X POST "$TRDRS_API_BASE_URL/api/trading/exits?provider=$PROVIDER&account=$ACCOUNT" \
  -H "Authorization: Bearer $TRDRS_TRADING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instrument": "ESZ6",
    "clientOrderId": "protect-entry-esz6-1",
    "entryOrderId": "'"$ORDER_ID"'",
    "exits": {
      "takeProfits": [{ "quantity": 2, "price": 6488.5 }],
      "stopLosses": [{ "quantity": 2, "price": 6472.5 }]
    }
  }'

const protection = await client.trading.protectAPosition({
  provider,
  account,
  instrument: 'ESZ6',
  clientOrderId: 'protect-entry-esz6-1',
  entryOrderId: orderId,
  exits: {
    takeProfits: [{ quantity: 2, price: 6488.5 }],
    stopLosses: [{ quantity: 2, price: 6472.5 }],
  },
})

The bracket covers the whole entry and waits on it, pending_entry, as a bracket placed with its entry does: each pair rests once the fill that opens its part of the position arrives. Its prices are measured from the entry’s own price, the limit of a limit order and the trigger of a stop or a stop-limit, and each must lie on its side of that price. None is held to the market, because no position is open. The response is the bracket and entryOrderId, the order the entry rests as afterwards. On the paper book the entry is replaced with itself, at the same price and size, to carry the bracket, so from then on it rests under your clientOrderId. Every other provider keeps the entry’s id. While the entry rests, change the bracket with Change a bracket or withdraw it as you would after the fill. On the paper book each change answers the entry’s new entryOrderId too, and withdrawing the bracket leaves the entry resting with no protection.

Read a bracket

Each entry in brackets is the protection around one position. takeProfits and stopLosses are its ladders, nearest the entry first, and orders are what rests for them, each naming its pairId. runner is how much of the position has a stop loss and no take profit, and unprotected is how much has no stop loss at all. A bracket that ended stays listed for a day, so your interface can show how it ended.

Bracket `state`	What it means
`pending_entry`	The bracket waits on an entry that hasn’t filled.
`active`	The bracket is protecting a position.
`completed`	The position it protected is closed, by its legs or otherwise.
`cancelled`	The bracket was withdrawn, or its entry was cancelled before it filled.
`failed`	The provider refused the entry, or a position is open and the provider refused its protection. `endReason` says which. Show this to the trader at once.

Leg or order `state`	What it means
`pre_armed`	Priced and recorded. It rests once the part of the position it protects fills.
`working`	Resting at the provider.
`filled`, `cancelled`, `rejected`	Ended. On a rejected order, `rejectReason` carries the provider’s reason.

A stop loss that moves itself carries automation. Its phase says which stop loss rests now: the one placed (protecting), the breakeven one (breakeven), or a trailing one (trailing). When state is paused, pauseReason says why nothing is moving the stop loss: provider_disconnected, no_price_feed, no_instrument_facts or account_locked. The stop loss resting at the provider still protects the position while it’s paused. Two details catch clients out:

The other order of a pair disappears on its own. When one order of a pair fills, the other is cancelled. Don’t cancel it yourself, and don’t treat its disappearance as a fault.
An order can rest before it has a provider id. Where the provider holds the pairs with the entry, an order carries holding provider_managed until the provider names it. Match the account’s working orders to a bracket by providerOrderId once it’s there.

When a change is refused

Status	Code	What it means	What to do
`400`	none	The bracket is malformed, the account can’t run it (`missing` lists what it lacks), or it doesn’t resolve on the instrument (`problems` says why, such as a stop loss on the wrong side of the price or a price off the tick).	Fix the request.
`400`	`position_exits_unsupported`	You sent a `positionId` to an account whose provider doesn’t name positions.	Protect by instrument.
`400`	none	`entryOrderId` names no resting order of yours on the instrument, or one that only reduces a position, or came with `positionId` or `qty`.	Name a resting entry, and send it on its own.
`404`	none	The account has no bracket with this id.	Check `BRACKET_ID` and the account you named.
`409`	`position_protected`	The position’s brackets already protect it.	Change the bracket the body names.
`409`	`entry_protected`	The resting entry already carries a bracket.	Change the bracket the body names.
`409`	`entry_partially_filled`	Part of the resting entry has filled.	Protect the position it opened.
`409`	`bracket_order`	The order you named is a take profit or stop loss of a bracket.	Change that bracket instead.
`409`	none	This `clientOrderId` was already used. The first request stands.	Read the account, then send a new request with a new id.
`409`	none	The bracket you’re changing has ended.	List the brackets, and protect the position again if it’s still open.
`409`	`bracket_attached`	The provider holds the bracket attached to its unfilled entry.	Cancel the entry, and place it again with the bracket you want.
`409`	`bracket_still_resting`	An order of the bracket wouldn’t cancel, so the bracket stays live.	Try the withdrawal again.
`409`	`version_conflict`	On the paper book, the account changed while the resting entry was being replaced.	Send the request again.
`422`	`market_data_unavailable`	On the paper book, you’ve connected no login that carries futures prices (`login_missing`), so a futures bracket can’t rest.	Connect such a login in production.
`422`	the provider’s	The provider refused every order of the protection, so nothing rests.	Show the refusal, and fix its cause before you retry.
`423`	`risk_locked` or `reconciliation_hold`	On the paper book, a hold refuses the replacement of the resting entry that carries the bracket.	Cancel the entry to withdraw its bracket with it, or wait for the hold to lift.
`503`	none	trdrs couldn’t record the bracket, so nothing was placed.	Retry with the same `clientOrderId`.

No hold on the account refuses a bracket on a position: it only closes the position it protects, so it can’t add exposure. On the paper book a bracket on a resting entry is carried by replacing the entry, so a hold that refuses new entries refuses that too.

Test it end to end

On your Demo in the sandbox, with HYPERLIQUID:BTC sized in bitcoin:

Buy 0.02 with a limit above the market, so it fills at once, with two take profits of 0.01 each above the limit and one stop loss for 0.02 below the market.
List the brackets and confirm the bracket is active with four working orders, two pairs.
Move the stop loss, then list again: the stop loss’s price changed and the take profits’ didn’t.
Flatten the instrument, and confirm the bracket has ended and nothing of it rests.

Start here

Trading

Before you start

Protect a resting order

Read a bracket

When a change is refused

Test it end to end

Next steps

Manage working orders

Close a position

​Before you start

​Protect a resting order

​Read a bracket

​When a change is refused

​Test it end to end

​Next steps

Manage working orders

Close a position

Before you start

Protect a resting order

Read a bracket

When a change is refused

Test it end to end

Next steps