Liquidation

La liquidation protège le système contre les comptes qui ne peuvent plus respecter leurs obligations de marge. Lorsque les capitaux propres d'un compte tombent en dessous de son exigence de marge de maintenance, le processus de liquidation transfère les positions vers des contreparties solvables.

Conditions de déclenchement

La liquidation se déclenche lorsqu'un compte devient insolvable (underwater) :

Marge de portefeuille :

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

Marge standard :

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

Où marge de maintenance = capitaux propres - MM requise.

Le système interroge en continu tous les comptes ayant des positions pour vérifier leur santé.

Machine à états

Les comptes progressent à travers quatre états de liquidation :

État	Description	Restrictions d'ordres
Healthy	Capitaux propres > MM requise	Aucune
PreLiquidation	Capitaux propres < MM, période de grâce active	Ordres augmentant le risque bloqués
InLiquidation	Enchère en cours	Tous les ordres bloqués
Liquidated	Enchère terminée	Compte apuré

Transitions d'état

1. Healthy → PreLiquidation : Le compte tombe en dessous du seuil de MM
2. PreLiquidation → Healthy : Le compte se rétablit au-dessus de la MM (l'utilisateur a ajouté des fonds ou fermé des positions)
3. PreLiquidation → InLiquidation : La période de grâce expire sans rétablissement
4. InLiquidation → Liquidated : L'enchère se termine avec succès

Période de grâce de pré-liquidation

Lorsqu'un compte entre en pré-liquidation :

1. Les ordres augmentant le risque sont bloqués immédiatement
2. Les ordres réduisant le risque (fermeture de positions) restent autorisés
3. Une période de grâce de 60 secondes commence
4. Si le compte se rétablit (capitaux propres > MM) avant l'expiration de la grâce, il revient à l'état Healthy
5. S'il est toujours insolvable après la grâce, l'enchère de liquidation commence

La période de grâce donne aux utilisateurs le temps de :

• Déposer du collatéral supplémentaire
• Fermer des positions pour réduire l'exigence de marge
• Réagir à des mouvements de marché soudains

Enchère de liquidation

Lorsque la période de grâce expire, une enchère hollandaise commence :

Enchère solvable (capitaux propres > 0)

Prix de départ = capitaux propres × (1 - pénalité), décroissant au fil du temps.

Les liquidateurs enchérissent pour reprendre les positions du compte en échange de :

• Les capitaux propres du compte (moins la pénalité)
• La responsabilité de toutes les positions

La pénalité crée une incitation pour les liquidateurs à participer.

Enchère insolvable (capitaux propres < 0)

Si le compte est insolvable (capitaux propres négatifs), le fonds d'assurance fournit un bonus pour inciter les liquidateurs à absorber les positions déficitaires.

Transfert de positions

Lorsqu'une liquidation se termine :

1. Toutes les positions sont transférées du compte liquidé vers le liquidateur
2. Le liquidateur reçoit (si solvable) ou paie (reçoit un bonus si insolvable) la valeur de règlement
3. La racine de marge est mise à jour on-chain
4. L'état du compte passe à Liquidated

Liquidation partielle vs totale

Type	Condition	Comportement
Partielle	≤ 5 positions	Liquider des positions spécifiques jusqu'au rétablissement de la MM
Totale	> 5 positions	Liquider l'intégralité du compte

La liquidation partielle est déterministe :

• Les positions sont ordonnées par un algorithme cohérent (non aléatoire)
• Le liquidateur reçoit les positions dans un ordre défini
• Le processus s'arrête lorsque le compte revient à un état sain

Cascade d'insolvabilité

Lorsque la liquidation ne peut pas récupérer la valeur totale, les pertes sont absorbées dans l'ordre suivant :

1. Capitaux propres du compte : L'utilisateur liquidé absorbe la perte à hauteur de ses capitaux propres
2. Fonds d'assurance : Couvre le déficit si les capitaux propres sont insuffisants
3. ADL (désendettement automatique) : Si le fonds d'assurance est épuisé, les contreparties profitables sont désendettées proportionnellement
4. Perte socialisée : Ultime filet de sécurité (non implémenté actuellement)

Fonds d'assurance

Le fonds d'assurance :

• S'accumule à partir des pénalités de liquidation
• Couvre les liquidations insolvables
• Est réapprovisionné par les frais de trading et les pénalités
• Dispose d'un objectif de réserve minimum

ADL (désendettement automatique)

Si le fonds d'assurance ne peut pas couvrir les pertes :

• Les contreparties ayant des positions profitables sont sélectionnées
• Les positions sont fermées de force au prix de marque
• La sélection priorise le profit et l'effet de levier les plus élevés
• Les utilisateurs concernés reçoivent une notification

Points de terminaison de l'API

Obtenir le statut de liquidation

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

Réponse :

{
  "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
  }
}

Obtenir l'historique de liquidation

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

Renvoie l'historique des transitions d'état pour un compte.

Obtenir l'historique public des liquidations

GET /liquidations?limit=50

Renvoie l'historique des transitions de liquidation, du plus récent au plus ancien, pour tous les portefeuilles. Le point de terminaison est public et utilise une pagination par curseur pour les bots de liquidation et les outils de surveillance.

Paramètres de requête

• cursor : Curseur opaque renvoyé par la page précédente.
• limit : Taille de page, par défaut 50, maximum 100.
• wallet : Filtre de portefeuille optionnel.
• status ou state : Filtre optionnel sur l'état de transition de liquidation. Les valeurs acceptées sont healthy, pre_liquidation, in_liquidation et liquidated.
• margin_mode : Filtre optionnel sur le mode de marge. Les valeurs acceptées sont standard et portfolio.
• liquidation_mode : Filtre optionnel sur le mode de liquidation. Les valeurs acceptées sont partial et full.

Réponse : PublicLiquidationsResponse avec les entrées de transition de liquidation et page.next_cursor pour la requête suivante.

Obtenir les détails d'une enchère

GET /liquidation/auction/{auction_id}

Renvoie le statut de l'enchère, les positions et les détails du règlement.

Notifications WebSocket

Les changements d'état de liquidation sont diffusés sur le canal liquidation :

{
  "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
}

Abonnez-vous pour recevoir des mises à jour en temps réel pour votre portefeuille.

Paramètres

Paramètre	Valeur	Description
poll_interval	5 secondes	Fréquence de vérification de la santé
grace_period	60 secondes	Délai avant le début de l'enchère
min_shortfall_threshold	0	Déficit minimum pour déclencher la pré-liquidation
partial_liquidation_threshold	5 positions	En dessous de ce seuil, la liquidation partielle est utilisée

Bonnes pratiques

Pour les traders

1. Surveillez le ratio de marge : Maintenez vos capitaux propres bien au-dessus de la MM (buffer de 2x recommandé)
2. Configurez des alertes : Utilisez le WebSocket pour détecter la pré-liquidation au plus tôt
3. Gardez des réserves : Conservez du collatéral disponible prêt à être déposé
4. Utilisez des stop-loss : Automatisez la réduction de positions avant la liquidation

Interroger la santé du compte

Vérifiez régulièrement votre statut de marge :

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

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

Rétablissement pendant la période de grâce

Si vous entrez en pré-liquidation :

1. Déposez du collatéral via le flux de financement
2. Fermez des positions pour réduire l'exigence de marge
3. Annulez les ordres ouverts qui augmentent le risque

Les actions réduisant le risque sont toujours autorisées, même en pré-liquidation.

On-chain vs off-chain

Composant	Emplacement	Notes
Surveillance de la santé	Off-chain	Interrogation toutes les 5 secondes
Transitions d'état	Off-chain	Journalisées et persistées
Minuteur de période de grâce	Off-chain	Configurable
Exécution des enchères	On-chain	Transfert de positions sur le contrat Controller
Règlement	On-chain	Transfert de valeur et mise à jour de la racine de marge

Le moteur off-chain gère la détection et l'orchestration ; l'exécution on-chain garantit la finalité du règlement.

---

Voir aussi :

• Marge de portefeuille : Calcul de la MM pour les comptes en marge de portefeuille
• Marge standard : Calcul de la MM pour les comptes standard
• Plancher de marge : Planchers de sécurité qui affectent le seuil de liquidation