| name | liquidation_guard |
| description | Pre-deploy checklist: order size validation + liquidation price guard for grid executors on perpetual futures |
| when_to_use | Before every grid_executor deployment on perpetual futures. Run after hourly_mtf_check produces a recommendation and before calling manage_executors(action='create'). |
| created | 2026-07-30T14:22:18Z |
| source | agent:adaptive_grid_trader |
Pre-Deploy Gate — run every step, stop on first FAIL
Step 0 — Order Size Validation
Given: budget, range (start_price → end_price), spacing, min_order_size, exchange_minimum
- Compute levels:
levels = (end_price - start_price) / (spacing × mid_price)
- Compute per-level size:
per_level = total_amount_quote / levels
- Check:
per_level ≥ max(min_order_size, exchange_minimum)
- If FAIL:
- Reduce levels (widen spacing) until per_level passes
- If no valid configuration exists → FAIL: budget too small for this range
Step 1 — Worst-Case Position Size
Assume every grid level fills (worst case for LONG = price at start_price, worst case for SHORT = price at end_price).
- For each level, compute:
level_base = per_level_quote / level_price
total_base = Σ level_base across all levelsavg_entry = total_amount_quote / total_base
Step 2 — Worst-Case Liquidation Price
Using isolated-margin formula:
- LONG:
liq_price = avg_entry × (1 - 1/leverage + maintenance_margin_rate)
- SHORT:
liq_price = avg_entry × (1 + 1/leverage - maintenance_margin_rate)
Where maintenance_margin_rate depends on the exchange's position tier for the notional total_base × limit_price. Typical values:
- Tier 1 (small positions): 0.4% (0.004)
- Tier 2 (medium): 0.5% (0.005)
- Tier 3 (large): 1-2% (0.01-0.02)
When in doubt, use the higher tier — it's conservative.
Step 3 — The Check
- LONG grid:
liq_price must be below limit_price
- PASS if
liq_price < limit_price
- FAIL if
liq_price ≥ limit_price
- SHORT grid:
liq_price must be above limit_price
- PASS if
liq_price > limit_price
- FAIL if
liq_price ≤ limit_price
Step 4 — If FAIL, try remediation (in order)
- Reduce leverage by 1 step → recompute from Step 2
- If leverage is already at minimum useful level → narrow the range (fewer levels, wider spacing) → recompute from Step 1
- If still FAIL → HOLD and report
Reporting
On PASS, include in deploy report:
liq_price: <value>liq_guard: PASSmargin_buffer: <distance between limit_price and liq_price as %>
On FAIL, report:
liq_price: <value>limit_price: <value>leverage: <value>liq_guard: FAIL — <reason>remediation_attempted: <what was tried>action: HOLD
Why this matters
limit_price only protects you if the exchange hasn't already liquidated you. At full fill with high leverage, liquidation can be closer than you think. This check guarantees your exit fires first — every time, before every deploy, no exceptions.
