Position Management
Position management covers what happens to a trade after it opens. Four independently toggleable features let you compose post-entry protection exactly how you want it.
All features disabled means the agent never modifies an open position. All features are safe by default — settings are off until you opt in.
The Four Features
| Feature | Driven By | What It Does |
|---|---|---|
| Break-Even Protection | ROE | Moves stop-loss to entry (plus optional offset) once the trade reaches a configured profit threshold. One-time event per trade. |
| Trailing Stop | Price peak | Ratchets the stop-loss up as the price reaches new highs (long) or lows (short). ATR-based or fixed percent. |
| Time-Decay Stop | Elapsed time | Progressively tightens the stop-loss when ROE stagnates below a threshold. Interval-driven. |
| Take-Profit Ladder | ROE milestones | Partially closes the position at configured ROE levels. Up to 10 ladder rungs. |
Why Four Separate Features?
Previous versions used a 3-mode enum that forced you to understand three full systems before configuring any of them. Composable features let you opt into one protection layer at a time:
- Start with Break-Even to protect a winning trade from becoming a loser.
- Layer on TP Ladder to lock partial profits.
- Add Trailing Stop to capture extended runs.
- Use Time-Decay to cut stale trades that aren't going anywhere.
Break-Even Protection
- Agent calculates ROE every 10 seconds on every open position.
- When ROE meets or exceeds your Break-Even Trigger ROE percent:
- Stop-loss moves to entry price, plus or minus your configured offset.
- The move is flagged as "break-even applied" so it only fires once per trade.
- A ratchet guard ensures the stop-loss only ever improves — if your current SL is already better than the break-even target, nothing changes.
Typical config: trigger at +3% ROE, offset +0.1% (guarantees a tiny profit locked in).
Trailing Stop
Tracks the trade's peak price and moves the stop-loss up behind it.
Start condition determines when the trail begins:
| Condition | Meaning |
|---|---|
| IMMEDIATELY | Trail runs from the first monitor cycle onward. |
| BREAKEVEN_REACHED | Trail starts only after Break-Even Protection has fired. |
| FIRST_TP_HIT | Trail starts only after the first Take-Profit ladder level closes. |
Trail type:
- FIXED — stop-loss stays a fixed percent behind the peak.
- ATR — stop-loss stays a configured ATR multiple behind current price. Adapts to live volatility. If ATR data is temporarily unavailable, that cycle is skipped safely (trail will resume next cycle).
As with break-even, the ratchet guard means trails only improve, never worsen. A spike-and-crash doesn't pull your stop back down.
Time-Decay Stop
The "we've been here too long" protection. Runs only when:
- Grace period has elapsed since the trade filled on the exchange.
- Current ROE is below your configured stale threshold (the position isn't performing).
- The configured interval has passed since the last decay tightening.
When all three gates pass, the stop-loss tightens by a configurable percent of the gap between the current SL and current price. A max tighten cap limits total movement so time-decay can never drag the SL past a reasonable bound.
| Knob | Typical Default | Purpose |
|---|---|---|
| Grace period | 60 min | Time before time-decay is even considered. |
| Interval | 15 min | Time between successive tightenings. |
| Tighten percent | 5% | Per-step gap reduction. |
| Max tighten percent | 50% | Hard cap on total movement from the original SL. |
| Stale threshold ROE | 1.0% | Below this, the position is considered stagnant. |
Time-decay complements the trailing stop (which is price-driven). Both share the same ratchet guard, so stops still only ever improve.
Grace period must be greater than or equal to interval. This is enforced at save time.
Take-Profit Ladder
Defines up to 10 partial-close levels. Each level has:
- Level order — 1 through 10. Triggers must be strictly increasing.
- Trigger ROE — when this ROE is hit, the level fires.
- Close percent — percent of the original position size to close.
When the monitor cycle sees ROE crossing an un-triggered level, it submits a reduceOnly market order for the configured close percent. The ladder then waits for the next higher level.
Constraints:
- Ladder levels are strictly increasing in trigger ROE.
- Total close percent across all levels must stay under 100 (you always keep at least a scrap of the position running).
- Partial closes go through the same rate-limited submit path as new entries, preserving balance-cache correctness.
A common ladder: 30% close at +5% ROE, 30% at +10% ROE, 30% at +20% ROE, leaving 10% as a runner.
Execution Order
Inside each 10-second monitor cycle, the agent runs these features in a fixed sequence:
- Break-Even → so the trailing stop's
BREAKEVEN_REACHEDgate can see the update in the same cycle. - Trailing Stop → so time-decay's ratchet guard sees any trailing improvement.
- Time-Decay Stop → so the stop tightens only if trailing hasn't already improved past the decay target.
- Take-Profit Ladder → partial close last, so any SL improvements from earlier steps are persisted before the ladder fires.
Stop-loss changes always follow: (1) amend on exchange → (2) persist runtime state → (3) write audit record. If any step fails, the cycle retries next iteration without leaving inconsistent state.
Safety Guarantees
- Ratchet guard — all SL changes must improve the floor. Stops never move backwards.
- Grace periods and gates — every feature has opt-in gates that prevent surprise behavior.
- Atomic amendments — SL changes amend the existing protection order on HyperLiquid through the same shared service used by manual TP/SL edits.
- Composable and independent — disabling any feature has no effect on the others. You can turn Trailing off tomorrow and your TP Ladder keeps working.
When Not To Use Position Management
- Very short-duration trades — if your agent only holds positions for a few minutes, post-entry management often fires too late to matter.
- Manual review flows — if you're actively managing TP/SL by hand, turn position management off to avoid conflicts with the monitor.
- Testing new strategies — disable position management during initial strategy evaluation so you can see the raw strategy performance without protection effects.
A safe starting point: enable Break-Even Protection with a +3% trigger and +0.1% offset. Once you're comfortable, layer on a Take-Profit Ladder. Add trailing and time-decay only after you've seen how the first two behave with your strategy.