Liquidação

A liquidação protege o sistema contra contas que não conseguem mais cumprir suas obrigações de margem. Quando o patrimônio de uma conta cai abaixo do seu requisito de margem de manutenção, o processo de liquidação transfere as posições para contrapartes solventes.

Condições de Acionamento

A liquidação é acionada quando uma conta fica subaquática:

Margem de Portfólio:

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

Margem Padrão:

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

Onde margem de manutenção = patrimônio - MM exigida.

O sistema consulta continuamente todas as contas com posições para verificar a saúde.

Máquina de Estados

As contas progridem por quatro estados de liquidação:

Estado	Descrição	Restrições de Ordens
Healthy	Patrimônio > MM exigida	Nenhuma
PreLiquidation	Patrimônio < MM, período de carência ativo	Ordens que aumentam o risco bloqueadas
InLiquidation	Leilão em andamento	Todas as ordens bloqueadas
Liquidated	Leilão concluído	Conta encerrada

Transições de Estado

1. Healthy → PreLiquidation: A conta cai abaixo do limiar de MM
2. PreLiquidation → Healthy: A conta se recupera acima da MM (usuário adicionou fundos ou fechou posições)
3. PreLiquidation → InLiquidation: O período de carência expira sem recuperação
4. InLiquidation → Liquidated: O leilão é concluído com sucesso

Período de Carência da Pré-Liquidação

Quando uma conta entra em pré-liquidação:

1. Ordens que aumentam o risco são bloqueadas imediatamente
2. Ordens que reduzem o risco (fechamento de posições) continuam permitidas
3. Um período de carência de 60 segundos começa
4. Se a conta se recuperar (patrimônio > MM) antes do fim da carência, ela retorna ao estado Healthy
5. Se ainda estiver subaquática após a carência, o leilão de liquidação começa

O período de carência dá aos usuários tempo para:

• Depositar colateral adicional
• Fechar posições para reduzir o requisito de margem
• Reagir a movimentos bruscos do mercado

Leilão de Liquidação

Quando o período de carência expira, um leilão holandês começa:

Leilão Solvente (Patrimônio > 0)

Preço inicial = patrimônio × (1 - penalidade), decrescendo ao longo do tempo.

Os liquidadores dão lances para assumir as posições da conta em troca de:

• Patrimônio da conta (menos a penalidade)
• Responsabilidade por todas as posições

A penalidade cria incentivo para que os liquidadores participem.

Leilão Insolvente (Patrimônio < 0)

Se a conta estiver insolvente (patrimônio negativo), o fundo de seguro fornece um bônus para incentivar os liquidadores a absorver as posições subaquáticas.

Transferência de Posições

Quando uma liquidação é concluída:

1. Todas as posições são transferidas da conta liquidada para o liquidador
2. O liquidador recebe (solvente) ou paga (recebe bônus se insolvente) o valor de settlement
3. A raiz de margem é atualizada on-chain
4. O estado da conta transiciona para Liquidated

Liquidação Parcial vs Total

Tipo	Condição	Comportamento
Parcial	≤ 5 posições	Liquida posições específicas até restaurar a MM
Total	> 5 posições	Liquida a conta inteira

A liquidação parcial é determinística:

• As posições são ordenadas por um algoritmo consistente (não aleatório)
• O liquidador recebe as posições em ordem definida
• O processo para quando a conta retorna ao estado saudável

Cascata de Insolvência

Quando a liquidação não consegue recuperar o valor total, as perdas são absorvidas na seguinte ordem:

1. Patrimônio da Conta: O usuário liquidado absorve a perda até o limite do seu patrimônio
2. Fundo de Seguro: Cobre o déficit se o patrimônio for insuficiente
3. ADL (Auto-Deleveraging): Se o fundo de seguro for esgotado, contrapartes lucrativas são desalavancadas proporcionalmente
4. Perda Socializada: Última proteção (não implementada atualmente)

Fundo de Seguro

O fundo de seguro:

• Acumula a partir das penalidades de liquidação
• Cobre liquidações insolventes
• É reabastecido por meio de taxas de negociação e penalidades
• Possui uma meta mínima de reserva

ADL (Auto-Deleveraging)

Se o fundo de seguro não puder cobrir as perdas:

• Contrapartes com posições lucrativas são selecionadas
• As posições são fechadas forçadamente ao preço de marcação
• A seleção prioriza maior lucro e alavancagem
• Os usuários afetados recebem notificação

Endpoints da API

Obter Status de Liquidação

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

Resposta:

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

Obter Histórico de Liquidação

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

Retorna o histórico de transições de estado de uma conta.

Obter Histórico Público de Liquidações

GET /liquidations?limit=50

Retorna o histórico de transições de liquidação de todas as carteiras, do mais recente para o mais antigo. O endpoint é público e usa paginação por cursor para bots liquidadores e ferramentas de monitoramento.

Parâmetros de consulta

• cursor: Cursor opaco retornado pela página anterior.
• limit: Tamanho da página, padrão 50, máximo 100.
• wallet: Filtro opcional por carteira.
• status ou state: Filtro opcional por estado de transição de liquidação. Os valores aceitos são healthy, pre_liquidation, in_liquidation e liquidated.
• margin_mode: Filtro opcional por modo de margem. Os valores aceitos são standard e portfolio.
• liquidation_mode: Filtro opcional por modo de liquidação. Os valores aceitos são partial e full.

Resposta: PublicLiquidationsResponse com entradas de transição de liquidação e page.next_cursor para a próxima requisição.

Obter Detalhes do Leilão

GET /liquidation/auction/{auction_id}

Retorna o status do leilão, posições e detalhes de settlement.

Notificações via WebSocket

Mudanças de estado de liquidação são transmitidas no 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
}

Assine para receber atualizações em tempo real da sua carteira.

Parâmetros

Parâmetro	Valor	Descrição
poll_interval	5 segundos	Frequência da verificação de saúde
grace_period	60 segundos	Tempo antes do início do leilão
min_shortfall_threshold	0	Déficit mínimo para acionar a pré-liquidação
partial_liquidation_threshold	5 posições	Abaixo disso, a liquidação parcial é usada

Boas Práticas

Para Traders

1. Monitore a razão de margem: Mantenha o patrimônio bem acima da MM (recomenda-se um buffer de 2x)
2. Configure alertas: Use o WebSocket para detectar a pré-liquidação com antecedência
3. Mantenha reservas prontas: Tenha colateral extra pronto para depositar
4. Use stop-losses: Automatize a redução de posições antes da liquidação

Consultando a Saúde

Verifique regularmente seu status de margem:

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

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

Recuperação Durante o Período de Carência

Se você entrar em pré-liquidação:

1. Deposite colateral por meio do fluxo de aporte de fundos
2. Feche posições para reduzir o requisito de margem
3. Cancele ordens abertas que aumentam o risco

Ações que reduzem o risco são sempre permitidas, mesmo em pré-liquidação.

On-Chain vs Off-Chain

Componente	Localização	Observações
Monitoramento de saúde	Off-chain	Consulta a cada 5 segundos
Transições de estado	Off-chain	Registradas e persistidas
Cronômetro do período de carência	Off-chain	Configurável
Execução do leilão	On-chain	Transferência de posições no contrato Controller
Settlement	On-chain	Transferência de valor e atualização da raiz de margem

O mecanismo off-chain lida com detecção e orquestração; a execução on-chain garante a finalidade do settlement.

---

Veja também:

• Margem de Portfólio: Cálculo de MM para contas de portfólio
• Margem Padrão: Cálculo de MM para contas padrão
• Piso de Margem: Pisos de segurança que afetam o limiar de liquidação