Liquidation

Die Liquidation schützt das System vor Konten, die ihren Margin-Verpflichtungen nicht mehr nachkommen können. Wenn das Eigenkapital eines Kontos unter seine Maintenance-Margin-Anforderung fällt, überträgt der Liquidationsprozess Positionen an solvente Gegenparteien.

Auslösebedingungen

Die Liquidation wird ausgelöst, wenn ein Konto unterdeckt ist:

Portfolio-Margin:

$$\text{Equity} < \text{Maintenance Margin Required}$$

Standard-Margin:

$$\text{Maintenance Margin} < 0$$

Dabei gilt: Maintenance Margin = Eigenkapital − erforderliche MM.

Das System fragt kontinuierlich alle Konten mit Positionen ab, um deren Gesundheit zu prüfen.

Zustandsmaschine

Konten durchlaufen vier Liquidationszustände:

Zustand	Beschreibung	Order-Beschränkungen
Healthy	Eigenkapital > erforderliche MM	Keine
PreLiquidation	Eigenkapital < MM, Schonfrist aktiv	Risikoerhöhende Orders blockiert
InLiquidation	Auktion läuft	Alle Orders blockiert
Liquidated	Auktion abgeschlossen	Konto bereinigt

Zustandsübergänge

1. Healthy → PreLiquidation: Konto fällt unter die MM-Schwelle
2. PreLiquidation → Healthy: Konto erholt sich über die MM (Nutzer hat Mittel hinzugefügt oder Positionen geschlossen)
3. PreLiquidation → InLiquidation: Schonfrist läuft ohne Erholung ab
4. InLiquidation → Liquidated: Auktion wird erfolgreich abgeschlossen

Pre-Liquidation-Schonfrist

Wenn ein Konto in die Pre-Liquidation eintritt:

1. Risikoerhöhende Orders werden sofort blockiert
2. Risikoreduzierende Orders (Schließen von Positionen) bleiben erlaubt
3. Eine 60-sekündige Schonfrist beginnt
4. Wenn sich das Konto vor Ablauf der Schonfrist erholt (Eigenkapital > MM), kehrt es in den Zustand Healthy zurück
5. Ist das Konto nach Ablauf der Schonfrist weiterhin unterdeckt, beginnt die Liquidationsauktion

Die Schonfrist gibt Nutzern Zeit, um:

• Zusätzliche Sicherheiten einzuzahlen
• Positionen zu schließen, um die Margin-Anforderung zu reduzieren
• Auf plötzliche Marktbewegungen zu reagieren

Liquidationsauktion

Wenn die Schonfrist abläuft, beginnt eine holländische Auktion:

Solvente Auktion (Eigenkapital > 0)

Startpreis = Eigenkapital × (1 − Strafgebühr), im Zeitverlauf abnehmend.

Liquidatoren bieten, um die Positionen des Kontos zu übernehmen, im Austausch gegen:

• Das Konteneigenkapital (abzüglich Strafgebühr)
• Die Verantwortung für alle Positionen

Die Strafgebühr schafft einen Anreiz für Liquidatoren, sich zu beteiligen.

Insolvente Auktion (Eigenkapital < 0)

Wenn das Konto insolvent ist (negatives Eigenkapital), stellt der Versicherungsfonds einen Bonus bereit, um Liquidatoren zu motivieren, die unterdeckten Positionen zu übernehmen.

Positionsübertragung

Wenn eine Liquidation abgeschlossen wird:

1. Alle Positionen werden vom liquidierten Konto auf den Liquidator übertragen
2. Der Liquidator erhält (solvent) oder zahlt (erhält bei Insolvenz einen Bonus) den Settlement-Wert
3. Die Margin-Root wird on-chain aktualisiert
4. Der Kontozustand wechselt zu Liquidated

Teilweise vs. vollständige Liquidation

Typ	Bedingung	Verhalten
Teilweise	≤ 5 Positionen	Bestimmte Positionen liquidieren, bis die MM wiederhergestellt ist
Vollständig	> 5 Positionen	Gesamtes Konto liquidieren

Die teilweise Liquidation ist deterministisch:

• Positionen werden nach einem konsistenten Algorithmus geordnet (nicht zufällig)
• Der Liquidator erhält Positionen in definierter Reihenfolge
• Der Prozess stoppt, wenn das Konto in einen gesunden Zustand zurückkehrt

Insolvenz-Wasserfall

Wenn die Liquidation nicht den vollen Wert zurückgewinnen kann, werden Verluste in folgender Reihenfolge absorbiert:

1. Konteneigenkapital: Der liquidierte Nutzer trägt den Verlust bis zur Höhe seines Eigenkapitals
2. Versicherungsfonds: Deckt den Fehlbetrag, wenn das Eigenkapital nicht ausreicht
3. ADL (Auto-Deleveraging): Ist der Versicherungsfonds erschöpft, werden profitable Gegenparteien proportional entschuldet
4. Sozialisierter Verlust: Letzte Absicherung (derzeit nicht implementiert)

Versicherungsfonds

Der Versicherungsfonds:

• Akkumuliert aus Liquidations-Strafgebühren
• Deckt insolvente Liquidationen
• Wird durch Handelsgebühren und Strafgebühren wieder aufgefüllt
• Hat ein Mindestreserveziel

ADL (Auto-Deleveraging)

Wenn der Versicherungsfonds die Verluste nicht decken kann:

• Gegenparteien mit profitablen Positionen werden ausgewählt
• Positionen werden zwangsweise zum Mark-Preis geschlossen
• Die Auswahl priorisiert den höchsten Gewinn und Hebel
• Betroffene Nutzer erhalten eine Benachrichtigung

API-Endpunkte

Liquidationsstatus abrufen

GET /liquidation/status?wallet=0x...

Antwort:

{
  "success": true,
  "data": {
    "wallet": "0x...",
    "state": "pre_liquidation",
    "margin_mode": "portfolio",
    "equity": "4500.00",
    "mm_required": "5000.00",
    "maintenance_margin": "-500.00",
    "entered_pre_liq_at": 1737312000000,
    "mm_shortfall": "500.00",
    "auction_id": null
  }
}

Liquidationshistorie abrufen

GET /liquidation/history?wallet=0x...&limit=20

Gibt die Zustandsübergangshistorie für ein Konto zurück.

Öffentliche Liquidationshistorie abrufen

GET /liquidations?limit=50

Gibt die Historie der Liquidationsübergänge über alle Wallets hinweg zurück, neueste zuerst. Der Endpunkt ist öffentlich und verwendet Cursor-Paginierung für Liquidator-Bots und Monitoring-Tools.

Query-Parameter

• cursor: Opaker Cursor, der von der vorherigen Seite zurückgegeben wurde.
• limit: Seitengröße, Standard 50, Maximum 100.
• wallet: Optionaler Wallet-Filter.
• status oder state: Optionaler Filter für den Zustand des Liquidationsübergangs. Zulässige Werte sind healthy, pre_liquidation, in_liquidation und liquidated.
• margin_mode: Optionaler Margin-Modus-Filter. Zulässige Werte sind standard und portfolio.
• liquidation_mode: Optionaler Liquidationsmodus-Filter. Zulässige Werte sind partial und full.

Antwort: PublicLiquidationsResponse mit Einträgen zu Liquidationsübergängen und page.next_cursor für die nächste Anfrage.

Auktionsdetails abrufen

GET /liquidation/auction/{auction_id}

Gibt Auktionsstatus, Positionen und Settlement-Details zurück.

WebSocket-Benachrichtigungen

Änderungen des Liquidationszustands werden auf dem Kanal liquidation gesendet:

{
  "type": "LiquidationStateChange",
  "wallet": "0x...",
  "previous_state": "healthy",
  "new_state": "pre_liquidation",
  "equity": "4500.00",
  "mm_required": "5000.00",
  "shortfall": "500.00",
  "auction_id": null,
  "timestamp": 1737312000000
}

Abonnieren Sie den Kanal, um Echtzeit-Updates für Ihre Wallet zu erhalten.

Parameter

Parameter	Wert	Beschreibung
poll_interval	5 Sekunden	Frequenz der Gesundheitsprüfung
grace_period	60 Sekunden	Zeit bis zum Auktionsstart
min_shortfall_threshold	0	Minimaler Fehlbetrag, um die Pre-Liquidation auszulösen
partial_liquidation_threshold	5 Positionen	Unterhalb dieses Werts wird die teilweise Liquidation verwendet

Best Practices

Für Trader

1. Margin-Quote überwachen: Halten Sie das Eigenkapital deutlich über der MM (empfohlen ist ein 2x-Puffer)
2. Alarme einrichten: Nutzen Sie WebSocket, um eine Pre-Liquidation frühzeitig zu erkennen
3. Reserven bereithalten: Halten Sie zusätzliche Sicherheiten für Einzahlungen bereit
4. Stop-Losses verwenden: Automatisieren Sie die Positionsreduzierung vor der Liquidation

Gesundheitsstatus abfragen

Prüfen Sie Ihren Margin-Status regelmäßig:

# Portfolio margin
curl "https://api.hypercall.xyz/portfolio?wallet=0x..."

# Look for:
# - equity vs maintenance_margin_required
# - margin_ratio (equity / IM)

Erholung während der Schonfrist

Wenn Sie in die Pre-Liquidation eintreten:

1. Sicherheiten einzahlen über den Funding-Flow
2. Positionen schließen, um die Margin-Anforderung zu reduzieren
3. Offene Orders stornieren, die das Risiko erhöhen

Risikoreduzierende Aktionen sind immer erlaubt, auch in der Pre-Liquidation.

On-Chain vs. Off-Chain

Komponente	Ort	Anmerkungen
Gesundheitsüberwachung	Off-chain	5-Sekunden-Polling
Zustandsübergänge	Off-chain	Protokolliert und persistiert
Schonfrist-Timer	Off-chain	Konfigurierbar
Auktionsausführung	On-chain	Positionsübertragung auf dem Controller-Contract
Settlement	On-chain	Wertübertragung und Aktualisierung der Margin-Root

Die Off-Chain-Engine übernimmt Erkennung und Orchestrierung; die On-Chain-Ausführung gewährleistet die Finalität des Settlements.

---

Siehe auch:

• Portfolio-Margin: MM-Berechnung für Portfolio-Konten
• Standard-Margin: MM-Berechnung für Standard-Konten
• Margin-Floor: Sicherheitsuntergrenzen, die die Liquidationsschwelle beeinflussen