Liquidación

La liquidación protege al sistema de cuentas que ya no pueden cumplir con sus obligaciones de margen. Cuando el equity de una cuenta cae por debajo de su requisito de margen de mantenimiento, el proceso de liquidación transfiere las posiciones a contrapartes solventes.

Condiciones de Activación

La liquidación se activa cuando una cuenta queda bajo el agua (underwater):

Margen de Portafolio:

$$\text{Equity} < \text{Margen de Mantenimiento Requerido}$$

Margen Estándar:

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

Donde margen de mantenimiento = equity - MM requerido.

El sistema consulta continuamente todas las cuentas con posiciones para verificar su salud.

Máquina de Estados

Las cuentas avanzan a través de cuatro estados de liquidación:

Estado	Descripción	Restricciones de Órdenes
Healthy	Equity > MM requerido	Ninguna
PreLiquidation	Equity < MM, período de gracia activo	Órdenes que aumentan el riesgo bloqueadas
InLiquidation	Subasta en curso	Todas las órdenes bloqueadas
Liquidated	Subasta completada	Cuenta liquidada

Transiciones de Estado

1. Healthy → PreLiquidation: La cuenta cae por debajo del umbral de MM
2. PreLiquidation → Healthy: La cuenta se recupera por encima del MM (el usuario agregó fondos o cerró posiciones)
3. PreLiquidation → InLiquidation: El período de gracia expira sin recuperación
4. InLiquidation → Liquidated: La subasta se completa con éxito

Período de Gracia de Pre-Liquidación

Cuando una cuenta entra en pre-liquidación:

1. Las órdenes que aumentan el riesgo se bloquean inmediatamente
2. Las órdenes que reducen el riesgo (cerrar posiciones) siguen permitidas
3. Comienza un período de gracia de 60 segundos
4. Si la cuenta se recupera (equity > MM) antes de que expire el período de gracia, vuelve al estado Healthy
5. Si sigue bajo el agua después del período de gracia, comienza la subasta de liquidación

El período de gracia da a los usuarios tiempo para:

• Depositar colateral adicional
• Cerrar posiciones para reducir el requisito de margen
• Reaccionar ante movimientos repentinos del mercado

Subasta de Liquidación

Cuando expira el período de gracia, comienza una subasta holandesa:

Subasta Solvente (Equity > 0)

Precio inicial = equity × (1 - penalización), decreciendo con el tiempo.

Los liquidadores pujan para asumir las posiciones de la cuenta a cambio de:

• El equity de la cuenta (menos la penalización)
• La responsabilidad de todas las posiciones

La penalización crea un incentivo para que los liquidadores participen.

Subasta Insolvente (Equity < 0)

Si la cuenta es insolvente (equity negativo), el fondo de seguro proporciona un bono para incentivar a los liquidadores a absorber las posiciones bajo el agua.

Transferencia de Posiciones

Cuando se completa una liquidación:

1. Todas las posiciones se transfieren de la cuenta liquidada al liquidador
2. El liquidador recibe (si es solvente) o paga (recibe un bono si es insolvente) el valor de settlement
3. La raíz de margen se actualiza on-chain
4. El estado de la cuenta pasa a Liquidated

Liquidación Parcial vs Total

Tipo	Condición	Comportamiento
Parcial	≤ 5 posiciones	Liquidar posiciones específicas hasta restaurar el MM
Total	> 5 posiciones	Liquidar toda la cuenta

La liquidación parcial es determinista:

• Las posiciones se ordenan mediante un algoritmo consistente (no aleatorio)
• El liquidador recibe las posiciones en un orden definido
• El proceso se detiene cuando la cuenta vuelve a un estado saludable

Cascada de Insolvencia

Cuando la liquidación no puede recuperar el valor completo, las pérdidas se absorben en orden:

1. Equity de la Cuenta: El usuario liquidado absorbe la pérdida hasta el límite de su equity
2. Fondo de Seguro: Cubre el déficit si el equity es insuficiente
3. ADL (Auto-Deleveraging): Si el fondo de seguro se agota, las contrapartes con posiciones rentables son desapalancadas proporcionalmente
4. Pérdida Socializada: Respaldo final (no implementado actualmente)

Fondo de Seguro

El fondo de seguro:

• Se acumula a partir de las penalizaciones de liquidación
• Cubre liquidaciones insolventes
• Se repone mediante comisiones de trading y penalizaciones
• Tiene un objetivo de reserva mínima

ADL (Auto-Deleveraging)

Si el fondo de seguro no puede cubrir las pérdidas:

• Se seleccionan contrapartes con posiciones rentables
• Las posiciones se cierran forzosamente al precio de marca
• La selección prioriza la mayor ganancia y apalancamiento
• Los usuarios afectados reciben una notificación

Endpoints de API

Obtener Estado de Liquidación

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

Respuesta:

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

Obtener Historial de Liquidación

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

Devuelve el historial de transiciones de estado de una cuenta.

Obtener Historial Público de Liquidaciones

GET /liquidations?limit=50

Devuelve el historial de transiciones de liquidación de todas las wallets, ordenado de más reciente a más antiguo. El endpoint es público y usa paginación por cursor para bots liquidadores y herramientas de monitoreo.

Parámetros de consulta

• cursor: Cursor opaco devuelto por la página anterior.
• limit: Tamaño de página, por defecto 50, máximo 100.
• wallet: Filtro opcional por wallet.
• status o state: Filtro opcional por estado de transición de liquidación. Los valores aceptados son healthy, pre_liquidation, in_liquidation y liquidated.
• margin_mode: Filtro opcional por modo de margen. Los valores aceptados son standard y portfolio.
• liquidation_mode: Filtro opcional por modo de liquidación. Los valores aceptados son partial y full.

Respuesta: PublicLiquidationsResponse con las entradas de transiciones de liquidación y page.next_cursor para la siguiente solicitud.

Obtener Detalles de la Subasta

GET /liquidation/auction/{auction_id}

Devuelve el estado de la subasta, las posiciones y los detalles del settlement.

Notificaciones por WebSocket

Los cambios de estado de liquidación se transmiten en el 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
}

Suscríbase para recibir actualizaciones en tiempo real de su wallet.

Parámetros

Parámetro	Valor	Descripción
poll_interval	5 segundos	Frecuencia de verificación de salud
grace_period	60 segundos	Tiempo antes de que comience la subasta
min_shortfall_threshold	0	Déficit mínimo para activar la pre-liquidación
partial_liquidation_threshold	5 posiciones	Por debajo de este valor, se usa liquidación parcial

Mejores Prácticas

Para Traders

1. Monitoree el ratio de margen: Mantenga el equity bien por encima del MM (se recomienda un colchón de 2x)
2. Configure alertas: Use WebSocket para detectar la pre-liquidación con anticipación
3. Prepare reservas: Mantenga colateral de reserva listo para depositar
4. Use stop-losses: Automatice la reducción de posiciones antes de la liquidación

Consultar la Salud de la Cuenta

Verifique su estado de margen con regularidad:

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

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

Recuperación Durante el Período de Gracia

Si entra en pre-liquidación:

1. Deposite colateral mediante el flujo de fondeo
2. Cierre posiciones para reducir el requisito de margen
3. Cancele órdenes abiertas que aumenten el riesgo

Las acciones que reducen el riesgo siempre están permitidas, incluso en pre-liquidación.

On-Chain vs Off-Chain

Componente	Ubicación	Notas
Monitoreo de salud	Off-chain	Consultas cada 5 segundos
Transiciones de estado	Off-chain	Registradas y persistidas
Temporizador del período de gracia	Off-chain	Configurable
Ejecución de la subasta	On-chain	Transferencia de posiciones en el contrato Controller
Settlement	On-chain	Transferencia de valor y actualización de la raíz de margen

El motor off-chain se encarga de la detección y la orquestación; la ejecución on-chain garantiza la finalidad del settlement.

---

Vea también:

• Portfolio Margin: Cálculo del MM para cuentas de portafolio
• Standard Margin: Cálculo del MM para cuentas estándar
• Margin Floor: Pisos de seguridad que afectan el umbral de liquidación