guard-trailing-stop

Guard Trailing Stop

Two-phase ROE-based trailing stop that protects profits on Hyperliquid perp positions.

How It Works

Phase 1: "Let It Breathe"

• Wide retrace (3% default) from high-water mark
• Patient: requires 3 consecutive breach checks before close
• Absolute price floor caps max loss
• Goal: don't get shaken out before the trade develops

Phase 2: "Lock the Bag"

• Tight retrace (1.5% default, per-tier overrides)
• Quick exit: 1-2 breaches to close
• ROE-based tier ratcheting — profit floors never go backward
• Per-tier retrace tightens as profit grows

ROE-Based Tiers

All triggers use ROE (Return on Equity): PnL / margin * 100. At 10x leverage, 1% price move = 10% ROE.

Usage

Standalone — Guard an existing position

hl guard start ETH-PERP \
  --entry 2500.0 \
  --size 1.0 \
  --direction long \
  --leverage 10 \
  --preset tight \
  --tick 5

Composable — Attach to any strategy

# config.yaml
strategy: avellaneda_mm
instrument: ETH-PERP
tick_interval: 10.0
guard:
  enabled: true
  preset: tight
  leverage: 10.0

hl run avellaneda_mm --config config.yaml

Presets

Module API

from modules.trailing_stop import TrailingStopEngine, GuardAction
from modules.guard_config import GuardConfig, PRESETS
from modules.guard_state import GuardState

config = PRESETS["tight"]
config.leverage = 10.0
config.direction = "long"

engine = TrailingStopEngine(config)
state = GuardState.new("ETH-PERP", entry_price=2500.0, position_size=1.0, direction="long")

result = engine.evaluate(price=2520.0, state=state)
# result.action: GuardAction.HOLD | .CLOSE | .TIER_CHANGED
# result.state: updated state (persist this)
# result.roe_pct, result.effective_floor, result.reason

Configuration Reference

Tier Format

tiers:
  - trigger_pct: 10.0    # Activate at 10% ROE
    lock_pct: 5.0         # Lock 5% ROE as floor
  - trigger_pct: 20.0
    lock_pct: 14.0
    retrace: 0.012        # Per-tier retrace override (1.2%)
    max_breaches: 1       # Per-tier breach count override

Direction Reference

Agent Mandate

You are the Guard trailing stop guardian. Your job is to protect profits and limit losses on open positions. You never make entry decisions — you only manage exits via a two-phase trailing stop system.

RULES:

• ALWAYS attach Guard to every open position — unprotected positions are unacceptable
• NEVER override a CLOSE signal — if Guard says close, close immediately
• ALWAYS use the correct direction (long/short) — wrong direction inverts all logic
• Let Phase 1 breathe — do not panic on early retrace within 3% threshold
• In Phase 2, trust the tier system — floors only ratchet up, never down
• ALWAYS verify entry price and leverage are correct before starting

Decision Rules

Anti-Patterns

• Using tight preset on trending assets: Tight stops exit too early on strong trends. Use moderate for trend-following strategies.
• Wrong direction parameter: Setting direction=long on a short position means Guard will hold losses and exit winners. Always double-check.
• Overriding CLOSE signals: "It'll come back" — it won't. Guard computed the exit. Trust it.
• Starting Guard after the move: Guard needs accurate entry price. Starting Guard at current price when entry was 2% ago means the trailing is wrong.
• Running without leverage parameter: Default leverage (10x) may not match your actual leverage — incorrect ROE calculation — wrong tier triggers.

Error Recovery

Composition

Guard is a sub-component of APEX (runs every tick per active slot). Can also be used standalone to guard any position. When used with APEX, Guard states are managed automatically. When used standalone, you must provide entry price, size, direction, and leverage.

Cron Template

# Guard is typically long-running (attached to a position), not cron-scheduled.
# Start manually when opening a position:
hl guard start ETH-PERP --entry 2500 --direction long --leverage 10 --preset moderate --tick 5