Liquidation

La liquidation protège le système contre les comptes qui ne peuvent plus honorer leurs obligations de marge. Lorsque les fonds propres d'un compte passent sous son exigence de marge de maintenance, Hypercall tente d'abord de rétablir le compte en clôturant les options vendues. Si cela ne suffit pas à temps, le compte passe en liquidation totale.

Conditions de déclenchement

La liquidation se déclenche lorsqu'un compte devient déficitaire :

Marge de portefeuille :

$$\text{Fonds propres} < \text{Marge de maintenance requise}$$

Marge standard :

$$\text{Liquidités} < \text{MM requise}$$

La liquidation en SM est déterminée par la marge de maintenance disponible en liquidités (cash - mm_required), et non par les fonds propres : les valorisations des options achetées qui augmentent la NAV n'empêchent donc pas un déficit de liquidités. Le champ d'API maintenance_margin = equity - mm_required est toujours renvoyé, mais ce n'est pas le déclencheur de liquidation en SM. Voir Marge standard.

Pour un compte en marge de portefeuille, les fonds propres sont nets de toute somme due au pool de prêt PM, et l'exigence de maintenance tient aussi compte de la liquidation de vos contrats perpétuels par Hyperliquid sur HyperCore. Hyperliquid peut toujours liquider ces contrats perpétuels selon ses propres règles, indépendamment de Hypercall. Voir Marge de portefeuille.

Hypercall vérifie la santé de chaque compte détenant des positions toutes les 5 secondes.

États

État	Ce qui se passe	Ordres
Healthy	PM : fonds propres égaux ou supérieurs à la MM requise. SM : liquidités égales ou supérieures à la MM requise.	Tous les ordres sont autorisés
PreLiquidation	Liquidation partielle : Hypercall place des ordres de clôture sur les options vendues du compte	Uniquement les ordres qui réduisent une position existante
InLiquidation	Liquidation totale. Marge standard : le portefeuille de positions du compte est proposé à un liquidateur	Uniquement les ordres qui réduisent une position existante
Liquidated	Un liquidateur a repris les positions du compte	Uniquement les ordres qui réduisent une position existante

Les retraits et les transferts automatiques de liquidités PM sont désactivés en PreLiquidation et en InLiquidation. Dès qu'un compte PM est en cours de vidage pour liquidation totale, tous ses ordres sont bloqués.

Transitions d'état

1. Healthy vers PreLiquidation : le compte passe sous son seuil de MM.
2. PreLiquidation vers Healthy : le compte atteint la cible avec marge de sécurité, MM requise × 1,05, et aucun de ses ordres de liquidation n'est encore ouvert. La borne est incluse.
3. PreLiquidation vers InLiquidation : le compte est toujours sous la cible et l'une des conditions d'escalade ci-dessous est remplie.
4. InLiquidation vers Healthy : le compte se rétablit avant qu'un liquidateur ne le reprenne, et la liquidation totale est arrêtée.
5. InLiquidation vers Liquidated : un liquidateur reprend le compte.

Liquidation partielle

Lorsqu'un compte entre en PreLiquidation :

1. Les ordres qui ajouteraient du risque sont immédiatement rejetés. Les ordres qui réduisent une position existante restent acceptés.
2. Hypercall annule vos ordres ouverts qui ajoutent du risque et place des ordres d'achat reduce-only sur vos options vendues, dimensionnés pour ramener le compte à MM requise × 1,05. Il clôture en premier les positions courtes qui libèrent le plus de marge par contrat.
3. Chaque ordre est valorisé au meilleur ask (ou au mid, ou au bid, en l'absence d'ask) plus un bonus de liquidation. Le bonus commence à 0,5 % et augmente linéairement jusqu'à 10 % sur 5 minutes. Les ordres sont révisés toutes les 5 secondes.
4. Dès que le compte revient au niveau de la cible ou au-dessus et que les ordres de liquidation ont disparu, il repasse en Healthy.

Le bonus est un coût pour vous : c'est ce que vous payez au-dessus du marché pour que vos positions courtes soient clôturées rapidement.

Profitez de cette fenêtre pour rétablir le compte vous-même :

• Déposez des garanties
• Clôturez des positions, en particulier les options vendues
• Annulez les ordres qui ajoutent du risque

Escalade vers la liquidation totale

Un compte en PreLiquidation toujours sous la cible passe en liquidation totale dès que l'une de ces conditions est remplie :

• Les fonds propres sont négatifs.
• Il n'a plus d'options vendues que la liquidation partielle pourrait clôturer.
• L'échéance d'escalade est dépassée. Elle intervient 20 minutes après l'entrée du compte en PreLiquidation.

Cette fenêtre de 20 minutes signifie aussi qu'une valorisation erronée passagère ne fait pas basculer directement un compte en liquidation totale.

Liquidation totale

Pour un compte en marge standard, la liquidation totale confie les positions du compte à un liquidateur au sein du moteur Hypercall. Hypercall annule d'abord tous les ordres ouverts du compte, puis propose le compte.

• Le liquidateur doit ramener le compte à MM requise × 1,05 : il apporte donc la marge qui manque au compte.
• Si le compte a encore des fonds propres positifs, le liquidateur vous verse ces fonds propres.
• Le liquidateur reprend toutes les positions et les liquidités du compte.

Si le compte se rétablit avant qu'un liquidateur ne le reprenne, la liquidation totale est arrêtée et le compte repasse en Healthy.

Pour un compte en marge de portefeuille, c'est la liquidation partielle décrite ci-dessus qu'il faut anticiper. Dès qu'un compte PM passe en escalade, ses ordres ouverts sont annulés et ses ordres sont bloqués pendant son traitement ; cette page décrira la suite de cette étape une fois celle-ci finalisée.

Pertes au-delà des fonds propres

Une perte au-delà des fonds propres d'un compte n'est jamais couverte en clôturant les positions d'autres traders ; Hypercall n'a pas d'auto-deleveraging. Qui l'absorbe dépend du mode de marge.

Marge standard. Le liquidateur reprend les positions et la trésorerie du compte en l'état, déficit compris. Un déficit dû à des fonds propres négatifs reste à la charge du liquidateur.

Marge de portefeuille. Ce que le compte doit encore après la liquidation (prêts du pool et règlements impayés) passe par une cascade fixe :

1. Le collatéral de l'emprunteur. Hypercall prélève sur le collatéral HyperCore du compte. Voir recouvrement. Un prêt n'est passé en perte qu'une fois le recouvrement épuisé.
2. La réserve de première perte. Elle paie d'abord les comptes auxquels l'emprunteur doit encore un règlement, lot le plus ancien en premier, puis couvre le prêt passé en perte.
3. Les prêteurs du pool. Ce que la réserve ne peut pas couvrir fait baisser le prix de la part du pool.

La dette n'est pas annulée. Tout ce qui est recouvré plus tard auprès de l'emprunteur paie d'abord les contreparties de settlement encore dues, du lot le plus ancien au plus récent, puis tout prêt du pool encore ouvert ; seul le reliquat va à la réserve et aux prêteurs, au prorata de ce que chacun a perdu. La réserve de première perte ne couvre que les prêts PM ; il n'existe pas de fonds d'assurance à l'échelle de la plateforme.

Points de terminaison de l'API

Obtenir le statut de liquidation

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

data vaut null pour un compte qui n'a jamais quitté l'état Healthy.

Réponse :

{
  "success": true,
  "data": {
    "wallet": "0x...",
    "state": "pre_liquidation",
    "liquidation_mode": "partial",
    "margin_mode": "portfolio",
    "equity": "4500.00",
    "mm_required": "5000.00",
    "maintenance_margin": "-500.00",
    "shortfall": "500.00",
    "partial_liquidation": {
      "entered_at": 1737312000000,
      "target_equity": "5250.00",
      "mm_shortfall": "500.00",
      "escalation_deadline": 1737313200000,
      "bonus_bps": 50
    },
    "full_liquidation": null
  }
}

partial_liquidation liste également les identifiants des ordres de liquidation ouverts. full_liquidation contient les détails de la reprise, notamment margin_needed, winner et l'offre requise actuelle.

Obtenir l'historique de liquidation

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

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

Obtenir l'historique public des liquidations

GET /liquidations?limit=50

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

Paramètres de requête

• cursor : curseur opaque renvoyé par la page précédente.
• limit : taille de page, 50 par défaut, 100 au maximum.
• wallet : filtre facultatif par portefeuille.
• status ou state : filtre facultatif par état de transition de liquidation. Valeurs acceptées : healthy, pre_liquidation, in_liquidation et liquidated.
• margin_mode : filtre facultatif par mode de marge. Valeurs acceptées : standard et portfolio.
• liquidation_mode : filtre facultatif par mode de liquidation. Valeurs acceptées : 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 de l'enchère

GET /liquidation/auction/{auction_id}

Renvoie le statut, les positions et les détails de règlement de la liquidation totale.

Notifications WebSocket

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

{
  "type": "LiquidationStateChange",
  "wallet_address": "0x...",
  "previous_state": "healthy",
  "new_state": "pre_liquidation",
  "liquidation_mode": "partial",
  "margin_mode": "portfolio",
  "equity": "4500.00",
  "mm_required": "5000.00",
  "maintenance_margin": "-500.00",
  "shortfall": "500.00",
  "partial_liquidation": { "escalation_deadline": 1737313200000, "bonus_bps": 50 },
  "full_liquidation": null,
  "timestamp": 1737312000000
}

partial_liquidation et full_liquidation contiennent les mêmes champs que le point de terminaison de statut. Abonnez-vous pour recevoir les mises à jour en temps réel de votre portefeuille.

Paramètres

Paramètre	Valeur	Description
Intervalle de vérification de santé	5 secondes	Fréquence de vérification de la santé des comptes
Cible de rétablissement	MM requise × 1,05	Fonds propres (PM) ou liquidités (SM) nécessaires pour repasser en Healthy, et niveau rétabli par une liquidation totale
Déficit minimum	0	Tout déficit déclenche la liquidation partielle
Bonus de liquidation	De 0,5 % à 10 % sur 5 minutes	Prime au-dessus du prix de référence sur les ordres de liquidation partielle
Intervalle de révision des prix	5 secondes	Fréquence de révision du prix des ordres de liquidation partielle
Échéance d'escalade	20 minutes	Durée en PreLiquidation avant le début de la liquidation totale

Bonnes pratiques

Pour les traders

1. Surveillez votre ratio de marge : maintenez des fonds propres bien au-dessus de la MM (une marge de sécurité de 2x est recommandée)
2. Configurez des alertes : utilisez le WebSocket pour détecter la pré-liquidation au plus tôt
3. Gardez des réserves : conservez des garanties disponibles, prêtes à être déposées
4. Clôturez vos positions courtes vous-même : vous ne payez aucun bonus de liquidation sur les ordres que vous placez

Interroger la santé du compte

Vérifiez régulièrement l'état de votre marge :

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

# Look for:
# - span_margin.equity vs span_margin.maintenance_margin_required (portfolio)
# - margin_summary.standard_margin.maintenance_margin_headroom (standard)

---

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 influent sur le seuil de liquidation
• Financement PM : comment la dette PM est recouvrée
• Paramètres de risque PM : le ratio de MM et tous les autres paramètres PM en vigueur
• Simuler le risque PM : vérifier la marge de MM disponible sur un portefeuille hypothétique