v2.0.0 to v3.0.0
116 added, 33 removed. Audit A to A.
---
name: broker-account-margin-call-handling
description: Use when monitoring margin account health to calculate real-time maintenance
- margin ratios, enforce multi-tiered margin warning thresholds, evaluate predictive
- order impacts, and trigger automated liquidity-aware de-leveraging before broker
- forced liquidation.
+ margin ratios, cross-check them against the broker's own excess-liquidity cushion,
+ enforce multi-tiered margin warning thresholds, gate new orders on initial margin, and
+ trigger liquidity-aware de-leveraging before broker forced liquidation.
domain: algorithmic-trading
subdomain: broker-integration
tags:
- broker-integration
- margin-call
- risk-management
- forced-liquidation-prevention
- margin-utilization
- liquidity-aware
brokers_frameworks:
- Interactive Brokers Reg T / Portfolio Margin
- Zerodha RMS
- Alpaca Margin API
- CME SPAN
- version: "2.0.0"
- author: quantitative-systems-engineer
+ version: "3.0.0"
+ author: algo-trading-skills-contributors
license: Apache-2.0
---
## When to Use
- Invoke this whenever an algorithmic trading bot operates on a margin account (Reg T, Portfolio Margin, or Futures margin). If adverse market movements push maintenance margin requirements above Net Liquidation Value (NLV), brokers issue margin calls and automatically liquidate positions at market prices, incurring severe slippage and realization losses.
+ Invoke this whenever an algorithmic trading bot operates on a margin account (Reg T,
+ Portfolio Margin, or futures margin). When adverse market moves push maintenance margin
+ requirements toward or past account equity, brokers liquidate positions at market prices,
+ and they choose which ones. Acting first — cancelling resting orders, blocking new
+ leverage, and unwinding on your own schedule with liquidity limits — is the difference
+ between a controlled reduction and a forced one.
- Implementing real-time margin ratio monitoring, multi-tiered risk gates (`WARNING` at 85%, `CANCEL_ORDERS` at 95%, `DE_LEVERAGE` at 100%), predictive pre-trade margin impact checks, and systematic, liquidity-aware order vetoing prevents broker-forced liquidation.
+ Use it to run three gates: a **tiered house ratio** as early warning, a **broker-cushion
+ check** that catches deficiency the house ratio can miss, and a **pre-trade veto** on
+ orders that would consume margin you do not have.
+ ## When NOT to Use
+
+ - **As a substitute for the broker's own numbers.** The engine grades a snapshot you
+ supply. If your feed is stale, the grade is stale. Poll `excess_liquidity` and
+ `available_funds` from the broker; do not derive them from NLV.
+ - **As a guaranteed way to beat the broker to liquidation.** IBKR does not make margin
+ calls — it liquidates in real time, without prior notice, and may do so without the
+ account ever displaying a margin warning. If you are already at BREACH you may have no
+ window at all. The pre-breach tiers are where this skill earns its keep.
+ - **To size liquidations under Portfolio Margin or SPAN without re-pricing.** The planner
+ assumes margin is separable per position. Under portfolio-level regimes, closing one leg
+ of a hedge can *raise* total margin — see Workflow step 5.
+ - **On a cash account**, or for exchange margin-shortfall *penalty* accounting, which is a
+ separate settlement-side concern.
+
## Prerequisites
- - Access to broker real-time account data: `net_liquidation_value`, `maintenance_margin`, `initial_margin`, `excess_liquidity`.
- - Open order cancellation interface.
- - Position de-leveraging prioritization logic (highest-margin, short options tail-risk, or liquidity-capped slicing).
+ - Broker real-time account data: `net_liquidation_value`, `initial_margin`,
+ `maintenance_margin`, and critically `excess_liquidity` and `available_funds`.
+ - A pre-trade margin impact source. Estimating it is the weak link — get it from the
+ broker. At IBKR that is an `Order.whatIf = true` submission, whose `OrderState` returns
+ `initMarginChange` and `maintMarginChange`.
+ - An open-order cancellation interface.
+ - Per-position `average_daily_volume`. It is a required field, not an optional one: it
+ caps how much of a position the plan will sell, and a guessed value defeats the cap.
+ - An execution path for liquidation slices (TWAP/VWAP or equivalent).
## Workflow
- 1. **Calculate Margin Utilization Metrics**:
- - Compute Maintenance Margin Utilization Ratio: $M_{\text{ratio}} = \frac{\text{Maintenance Margin}}{\text{Net Liquidation Value}}$.
- - Compute Predictive Initial Margin Impact before order placement.
+ 1. **Evaluate account health** with `evaluate_margin_health(snapshot)`. It escalates on
+ the *worse* of two signals:
+ - the house ratio $M = \text{maintenance margin} / \text{NLV}$, against your configured
+ tiers, and
+ - **`excess_liquidity < 0`**, the broker's own cushion, which is authoritative.
+ Unusable input (NaN, infinity, negative margin) raises `MarginDataError` rather than
+ grading the account. A margin engine that reports NORMAL because its feed broke is
+ worse than one that stops.
- 2. **Evaluate Multi-Tiered Margin Thresholds**:
- - **NORMAL** ($M_{\text{ratio}} < 0.85$): Normal trading operations.
- - **WARNING** ($0.85 \le M_{\text{ratio}} < 0.95$): Block new leverage-increasing orders; issue alert to risk operators.
- - **CRITICAL** ($0.95 \le M_{\text{ratio}} < 1.0$): Cancel all open pending orders immediately to release reserved margin buffers.
- - **BREACH** ($M_{\text{ratio}} \ge 1.0$): Execute automated de-leveraging to restore $M_{\text{ratio}} \le 0.75$ (target buffer) before broker forced liquidation.
+ 2. **Act on the tier.** Defaults are house policy, not regulation — set them for your book:
+ - **NORMAL** ($M < 0.85$): trade normally.
+ - **WARNING** ($0.85 \le M < 0.95$): block new leverage-increasing orders; alert.
+ - **CRITICAL** ($0.95 \le M < 1.0$): cancel all resting orders to release reserved margin.
+ - **BREACH** ($M \ge 1.0$, or negative excess liquidity): de-leverage now.
+ For calibration, IBKR's own warning fires at roughly a 90.9% maintenance/ELV ratio,
+ between the 85% and 95% defaults.
- 3. **Execute De-Leveraging Order Slicing**:
- - Score and sort existing positions prioritizing unhedged short options (tail risk), high margin density, and highly liquid assets.
- - Apply a volume participation cap (e.g., max 10% of ADV) to prevent the de-leveraging algorithm from causing flash crashes in illiquid names.
- - Liquidate position slices systematically until the target margin buffer is restored.
+ 3. **Handle non-positive equity as a different problem.** If NLV $\le 0$ the ratio is
+ undefined — the engine returns `math.inf` and the action `HALT_AND_ESCALATE` rather than
+ `DE_LEVERAGE_IMMEDIATELY`. There is no target margin to de-leverage toward against
+ non-positive equity; stop trading and involve a human.
- 4. **Predictive New Order Veto Guard**:
- - Intercept outbound order requests via `guard_new_order(margin_impact)`. Veto any order that *would* increase the projected margin ratio $\ge 0.85$.
+ 4. **Gate every new order** through `guard_new_order(snapshot, margin_impact,
+ initial_margin_impact=...)`. Pass `initial_margin_impact` whenever you have it: new
+ positions are opened against **initial** margin (Reg T requires 50% on a long margin
+ equity purchase) not maintenance margin (FINRA 4210's 25% minimum), so a
+ maintenance-only projection is the weaker constraint and can pass an order the broker
+ refuses. The guard returns `True` or raises — it never returns `False`, so treat any
+ exception as a hard veto.
+ 5. **Plan de-leveraging** with `plan_deleveraging(snapshot, positions)`, which orders by
+ short-option tail risk, then margin density, then liquidity, and caps each slice at
+ `max_participation_rate` of ADV. **Then re-price the plan before acting on it if you
+ are on Portfolio Margin or SPAN** — the planner's linear "units × margin per unit" model
+ does not hold when margin is computed on portfolio-level stressed loss, and unwinding a
+ hedge leg can increase the requirement. Send each slice through the broker's own
+ pre-trade check first.
+
+ 6. **Expect the plan to be incomplete under illiquidity.** The ADV cap can leave the plan
+ short of the required reduction. That is the intended trade-off — dumping the position
+ would crush its price, lower NLV and trigger a second deficiency — but it means you must
+ check whether the plan actually clears the deficit and escalate when it does not.
+
> Full step-by-step procedure with broker-specific detail: see `references/workflows.md`.
- > Broker/framework coverage table for this skill: see `references/standards.md`.
+ > Broker triggers, cushion definitions and regulatory reference points: see `references/standards.md`.
> Printable pre-flight checklist: see `assets/checklist.md`.
## Common Pitfalls
- - **Passive Waiting for Broker Liquidation**: Waiting for the broker's automated RMS engine to liquidate positions, leading to market-order slippage and bad fills.
- - **Ignoring Predictive Margin Impact**: Approving an order when current margin is 80%, but the order itself pushes margin to 110%.
- - **Illiquidity Spirals**: Dumping an illiquid asset all at once, crushing the bid price, lowering the NLV further, and triggering a secondary margin call.
- - **Ignoring Tail Risk**: De-leveraging long equity positions first while leaving naked short options open during a volatility spike.
+ - **Trusting the house ratio alone.** `maintenance_margin / NLV` uses NLV; the broker's
+ cushion uses Equity with Loan Value, which excludes non-margin-eligible value and can be
+ much lower. An account can read 70% and healthy while `excess_liquidity` is already
+ negative and liquidation is underway.
+ - **Letting NaN through a threshold chain.** Every comparison against NaN is False, so a
+ NaN ratio falls past `>= breach`, `>= critical` and `>= warning` into the healthy branch.
+ A broken feed must fail closed.
+ - **Checking new orders against maintenance margin.** Positions are opened against initial
+ margin, which is roughly double under Reg T.
+ - **Flooring NLV to avoid dividing by zero.** It manufactures a finite ratio from an
+ undefined one and, if the deficit is computed from the floored value, understates the
+ deficit by exactly the amount of negative equity.
+ - **Exempting "de-leveraging" orders without checking they de-leverage.** A bypass flag
+ that is trusted unconditionally lets a margin-increasing order through every gate.
+ - **Unordered thresholds.** Setting warning above critical makes the WARNING tier
+ unreachable — the account jumps straight to CRITICAL and the early gate never fires.
+ - **Passive waiting for broker liquidation**, taking market-order slippage on positions
+ someone else chose.
+ - **Illiquidity spirals**: dumping an illiquid asset at once, crushing the bid, lowering
+ NLV, and triggering a secondary call.
+ - **Ignoring tail risk**: unwinding long equity first while naked short options stay open
+ through a volatility spike.
+ - **Ignoring the clock.** Where the broker force-closes intraday products on a schedule
+ (Zerodha squares off MIS positions around 15:20 IST), being margin-healthy is not enough.
## Verification
- - Ensure `evaluate_margin_health` correctly applies logic across initial and maintenance margins.
- - Submit account metrics with $M_{\text{ratio}} = 0.88$ and confirm state transitions to `WARNING`.
- - Simulate a high-impact order using `guard_new_order` and verify predictive rejection.
- - Run unit test suite `python scripts/test_margin_call_engine.py` and confirm 100% pass rate.
+ - Run the unit suite and confirm every test passes:
+ `python -m unittest discover -s skills/broker-account-margin-call-handling/scripts`
+ - Feed a snapshot with a healthy ratio but negative `excess_liquidity` and confirm the
+ state is `MARGIN_CALL_BREACH` with `broker_deficiency` set — this is the failure mode
+ most likely to be missed in production.
+ - Feed NaN in each snapshot field in turn and confirm `MarginDataError` every time; a
+ `NORMAL` result from any of them is a fail-open bug.
+ - Check each tier at its exact boundary (85.0%, 95.0%, 100.0%), not just mid-band.
+ - Submit a snapshot with $M = 0.88$ and confirm `WARNING`.
+ - Submit an order whose `initial_margin_impact` exceeds `available_funds` and confirm the
+ veto, even when the maintenance projection alone would have passed.
+ - Replay a historical drawdown that actually breached, and confirm the tiers would have
+ fired early enough to matter given your broker's liquidation behaviour.
## Related Skills
- `kill-switch-and-drawdown-circuit-breakers`
- `options-margin-span-calculation-global`
- `correlation-aware-exposure-limits`
+ - `margin-utilization-circuit-breaker`