Margin & Liquidation
GoDark uses isolated margin: each open position carries its own collateral silo. The sequencer continuously evaluates margin health and applies a six-tier ladder — from early warnings through partial liquidations — before escalating to auto-deleveraging (ADL) or insurance-fund backstop.
This page describes how margin requirements, health tiers, and liquidation work. For fee tiers (Core → Apex), see VIP Tiers — those are unrelated to margin health.
Isolated Margin Model
| Concept | Description |
|---|---|
| Initial margin (IM) | Collateral locked when a position opens: ⌈size × price / leverage⌉ |
| Extra margin | Optional additional collateral added to a position |
| Equity | IM + extra margin + unrealized PnL |
| Maintenance margin | Minimum equity required to keep the position open: size × mark × maintenance_rate |
| Margin ratio | equity / maintenance_margin — values below 100% trigger liquidation |
Positions do not share collateral across markets. Higher leverage requires less initial margin but leaves a tighter buffer before liquidation.
Default platform rates (overridable per instrument via GET /instruments):
| Rate | Default | Meaning |
|---|---|---|
| Maintenance margin | 500 bps (5%) | Minimum equity as a fraction of notional at mark |
| Warning margin | 1,000 bps (10%) | Early warning band (internal classification) |
Per-instrument fields initial_margin_ratio and maintenance_margin_ratio on GET /instruments are authoritative for each market.
Pre-Trade Risk Checks
Every order is risk-checked before it enters the book. A successful POST /orders response means all checks passed — not that the order has filled.
Checks include margin, position limits, liquidation lockout, and max leverage. Resting orders also reserve margin so free_collateral reflects working liquidity. Rejects use the trade ACK catalog — see Error Codes and Place Order — Pre-Trade Risk Validation.
Pre-trade checks fail closed on stale or missing oracle prices — orders are rejected rather than accepted without a valid mark.
Margin Health Tiers
The liquidation monitor evaluates every open position approximately every 250 ms. Each position is classified into one of six tiers based on margin ratio (equity ÷ maintenance margin, expressed in basis points where 10,000 = 100%).
| Tier | Margin ratio | User-visible action |
|---|---|---|
| Healthy | > 150% | No alert |
| Warning150 | 120% – 150% | Margin alert (web UI banner / health bar) |
| Critical120 | 110% – 120% | Margin alert; same-side resting orders may be cancelled |
| T1 | 100% – 110% | First liquidation tranche — 10% of original position size; all user orders cancelled |
| T2 | 80% – 100% | Second tranche — 30% of original size (requires T1 complete) |
| T3 | ≤ 80% | Third tranche — 60% of original size (requires T2 complete) |
The web trading UI mirrors these bands in the margin health bar and tier banners. Tier names here are margin health tiers, not VIP fee tiers.
Partial Liquidation Ladder
When a position crosses into T1, T2, or T3, the engine liquidates a fraction of the original position size (not the remaining size):
| Tranche | Size liquidated | Cumulative |
|---|---|---|
| T1 | 10% of original | 10% |
| T2 | 30% of original | 40% |
| T3 | 60% of original | 100% |
Between tranches the monitor pauses briefly (2s / 3s / 5s) and re-evaluates. If margin ratio recovers above 130% (120% + 10% hysteresis), the position returns to normal monitoring without further tranches.
If tranches cannot restore solvency — for example, due to timeout, repeated defer failures, or persistent deficit — the engine escalates to ADL (auto-deleveraging) against counterparties ranked by profit and leverage.
Liquidation Process
End-to-end flow:
- Monitor tick — sequencer evaluates margin ratios for all open positions
- Tier classification — position enters Warning150 / Critical120 / T1 / T2 / T3
- Alerts — margin alerts pushed to connected clients (web UI and programmatic subscribers)
- Order cancellation — at T1, all resting user orders on the account are cancelled
- Tranche execution — position slice transferred from user to the GoDark Liquidation Vault (GLV) via
transfer_tranche - Unwind — GLV inventory is unwound through internal market-making strategies
- On-chain settlement — collateral split settled on Solana (see Settlement and Collateral Vault)
On-chain liquidation settles collateral (ZK split from user remainder to GLV credit). Position sizing, tier logic, and tranche scheduling run off-chain in the sequencer.
Oracle mark prices (Pyth primary, Switchboard failover) drive PnL and liquidation math. Stale oracle data can delay or block pre-trade checks; the monitor uses the same mark feed for ongoing evaluation.
Liquidation Price
Each open position exposes a liquidation_price field — the mark price at which maintenance margin would equal equity (the boundary between Critical120 and T1).
Returned by GET /positions and the Positions Channel. Recomputed when mark price moves (update_reason: mark_price) or when the position changes due to fills or liquidations.
Approximate formulas (using maintenance rate MMR in basis points, BPS = 10_000):
Long: liq = (size × entry − collateral) × BPS / (size × (BPS − MMR))
Short: liq = (collateral + size × entry) × BPS / (size × (BPS + MMR))
Higher leverage means less initial collateral for the same size, so liquidation price sits closer to entry.
Bad Debt Backstop
When liquidation and ADL cannot fully cover a deficit (negative equity / bad debt), a three-tier backstop applies:
| Tier | Mechanism |
|---|---|
| 1 | Insurance fund — absorbs residual loss up to fund balance (funded by a fraction of trading fees; see Fee Structure) |
| 2 | Socialized loss — if the fund is exhausted, loss may be distributed across profitable positions in the same market |
| 3 | Protocol halt — if socialized loss exceeds a configurable threshold, the market is halted pending manual intervention |
Insurance fund and socialized-loss accounting are tracked off-chain in the current release; on-chain vault integration is planned for a future version.
Programmatic Integration
Use an official SDK. Subscribe to position updates on GodarkClient and read the position object — do not scrape REST or raw WebSocket frames for this.
PositionUpdate (name varies slightly by language) is the shape you watch:
| Field | Why it matters |
|---|---|
symbol, side, size | What is open |
margin, leverage | Isolated collateral on the position |
unrealized_pnl | Mark-to-market |
liquidation_price | Where this position would liquidate |
update_reason | Why the row changed (fill, mark_price, liquidation) |
Instrument limits you need for pre-trade checks live on the instrument object: initial_margin_ratio, maintenance_margin_ratio, max_leverage.
Order rejects: Error Codes.
Related
- Trade Flow — order lifecycle
- Positions — position snapshot API
- Settlement — batch settlement and oracle role
- VIP Tiers — fee tiers (distinct from margin health tiers)