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.
| Check | Error code | Description |
|---|---|---|
| Margin sufficiency | 1410 | Available collateral insufficient for the requested size |
| Position limits | 1411 | Position size exceeds instrument cap |
| Account in liquidation | 1412 | New orders blocked while a liquidation is in progress |
| Leverage above max | 1413 | Requested leverage exceeds instrument max_leverage |
Resting orders also reserve margin optimistically (order holds) so free_collateral reflects working liquidity. See Place Order — Pre-Trade Risk Validation and Error Codes.
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 via the shielded-pool
liquidateinstruction (see Settlement and Shielded Pool)
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
REST
| Endpoint | Relevant fields |
|---|---|
GET /positions | liquidation_price, margin, leverage, unrealized_pnl |
GET /instruments | initial_margin_ratio, maintenance_margin_ratio, max_leverage |
POST /orders | Pre-trade risk rejection codes 1410–1413 |
WebSocket
Subscribe to the Positions Channel for live updates:
update_reason | Meaning |
|---|---|
mark_price | Mark moved — PnL and liquidation_price recomputed |
liquidation | Position partially or fully liquidated |
fill | Size or margin changed due to a trade |
Margin health tier alerts are delivered to connected web clients. Integrators should monitor liquidation_price, position size changes with update_reason: liquidation, and risk error codes on order placement.
Error codes
| Code | When |
|---|---|
1410 | Margin insufficient |
1411 | Position limit exceeded |
1412 | Account in liquidation — new orders blocked |
1413 | Leverage above instrument max |
Full reference: Error Codes.
Related
- Trade Flow — order lifecycle including MPC margin checks
- MPC Committee Architecture — where matching and risk evaluation run
- Positions — position snapshot API
- Settlement — batch settlement and oracle role
- VIP Tiers — fee tiers (distinct from margin health tiers)