Liquidações Automáticas

Em resumo
Liquidações Automáticas convertem automaticamente depósitos recebidos para seu ativo preferido em qualquer blockchain. Defina regras uma vez, e todos os depósitos correspondentes são trocados e roteados para sua chain de destino—sem intervenção manual necessária.

Pré-requisitos

Antes de configurar regras de liquidação automática, certifique-se de ter:

Chave API

Obtenha sua chave API no Painel da Blockradar. Navegue até Developers para gerar uma.

Carteira Mestra Criada

Crie uma carteira mestra via API Criar Carteira ou painel. Regras são configuradas por carteira.

Carteira de Destino

Se liquidar cross-chain, certifique-se de ter uma carteira na blockchain de destino para receber os ativos convertidos.

Gas Suficiente

Financie suas carteiras com tokens nativos (ETH, BNB, MATIC, etc.) para cobrir taxas de swap e transferência.

Webhook Configurado

Configure webhooks para receber notificações de liquidação. Dependendo da ação, você receberá eventos swap.success/swap.failed, gateway.success/gateway.failed, ou withdraw.success/withdraw.failed. Veja Webhooks para detalhes.

Como Funciona

Liquidações Automáticas permitem que você converta automaticamente depósitos recebidos em qualquer ativo de destino em qualquer rede blockchain com base em suas regras configuradas. Isso elimina a necessidade de trocar ou fazer bridge de ativos manualmente, garantindo que seu tesouro possa ser automaticamente convertido para seus ativos preferidos em múltiplas chains.

Gerenciamento de Regras

Crie e gerencie regras de liquidação automática para automatizar conversões de ativos.

Conversão de Ativos

Converta automaticamente qualquer stablecoin para qualquer outro ativo com base em suas regras.

Cross-Chain

Liquide ativos para qualquer rede blockchain sem problemas.

Gerenciamento de Risco

Aplique tolerância de slippage e regras para proteger contra execuções ruins.

Como Funcionam as Liquidações Automáticas

1. Criação de Regra

Defina regras de liquidação que especificam quando e como os depósitos devem ser automaticamente convertidos.

2. Detecção de Depósito

Quando os fundos chegam aos seus endereços, o Blockradar detecta automaticamente depósitos que correspondem às suas regras.

3. Conversão de Ativos

Os depósitos são automaticamente trocados para o seu ativo de destino (normalmente USDC) na chain escolhida.

4. Unificação de Saldo

Todos os ativos convertidos são consolidados em um único saldo unificado na sua chain de destino.

Regras de Liquidação Automática

Componentes da Regra

Cada regra de liquidação automática define os seguintes parâmetros:

Componente	Descrição	Exemplo
Nome da Regra	Nome descritivo para sua regra de liquidação	”Trocar de USDC para USDC Optimism”
Ordem	Preferência de prioridade de execução	FASTEST, CHEAPEST, RECOMMENDED, NO_SLIPPAGE
Tolerância de Slippage	Desvio máximo aceitável de preço (%). Use `-1` para slippage ilimitado	5 ou -1
Ativos de Origem	Array de ativos para liquidar automaticamente	[“USDC”, “USDT”]
Valor Mín/Máx de Origem	Controle o tamanho do depósito que aciona a liquidação	Mín: $1, Máx:$ 1,000
Blockchain de Destino	Rede blockchain de destino	optimism, base, ethereum
Ativo de Destino	Ativo de destino para conversão	USDC, USDT, cNGN, DAI
Endereço de Destino	(Opcional) Endereço específico para receber ativos convertidos. Se não fornecido, aplica-se lógica de fallback inteligente	0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22
É Gateway	Habilitar funcionalidade de gateway para a regra	false

Opções de Configuração de Regra

Limites de Valor

Valor Mínimo: Liquidar apenas depósitos acima deste limite
Valor Máximo: Limite o tamanho de liquidações individuais
Processamento em Lote: Agrupe múltiplos depósitos pequenos para eficiência

Proteção de Slippage

Ilimitado: -1 (sem limite de slippage - comportamento padrão)
Conservador: 0.1% - 0.5% (impacto mínimo no preço)
Moderado: 0.5% - 1.0% (abordagem equilibrada)
Agressivo: 1.0% - 2.0% (execução mais rápida)

Definir slippageTolerance como -1 significa tolerância de slippage ilimitada. Este é o comportamento padrão se não especificado, permitindo que as liquidações sejam executadas independentemente do desvio de preço.

Endereço de Destino (Opcional)

O campo destination.address agora é opcional. Quando não fornecido, o sistema usa lógica de fallback inteligente para determinar o endereço do destinatário:

Cenário	Comportamento de Fallback
Endereço explícito fornecido	Usa o endereço especificado
Liquidação na mesma chain	Usa o endereço de depósito (endereço de origem)
Cross-chain EVM-para-EVM	Usa o mesmo endereço na chain de destino
Cross-chain (destino não-EVM)	Usa o endereço da carteira principal da chain de destino

Para a maioria dos casos de uso, você pode omitir o endereço de destino e deixar o sistema rotear automaticamente os fundos para o endereço apropriado com base no tipo de liquidação.

Preferências de Execução

Fastest: Prioriza velocidade sobre custo
Cheapest: Otimiza para taxas mais baixas
Recommended: Equilibra velocidade e custo com confiabilidade
No Slippage: Executa apenas quando não há desvio de preço

Hierarquia e Precedência de Regras

Como as Regras se Aplicam

Conceito Chave: Regras criadas em uma carteira principal se aplicam automaticamente a todos os endereços filhos sob essa carteira. No entanto, se você criar regras diretamente em um endereço filho, essas regras substituirão completamente as regras da carteira principal para esse endereço específico.

Nível de Regra	Escopo	Comportamento
Regras de Carteira Principal	Aplicam-se à carteira principal E todos os endereços filhos	Regras padrão para toda a hierarquia da carteira
Regras de Endereço Filho	Aplicam-se apenas a esse endereço específico	Substituem completamente as regras da carteira principal quando presentes

Ordem de Aplicação de Regras

Verificar Regras de Endereço Filho: Se o endereço receptor tem suas próprias regras, usar essas exclusivamente
Recorrer às Regras da Carteira Principal: Se não existirem regras de endereço filho, aplicar regras da carteira principal
Sem Regras: Se nenhum nível tiver regras configuradas, nenhuma liquidação automática ocorre

Quando um endereço filho tem suas próprias regras, as regras da carteira principal são completamente ignoradas para esse endereço—não há mesclagem ou combinação de regras.

Regras Específicas por Blockchain

Importante: As regras são isoladas e vinculadas a cada blockchain. Uma regra configurada para um blockchain (ex. Ethereum) NÃO afetará depósitos em outro blockchain (ex. Base ou Optimism).

Isso significa:

Você deve criar regras separadas para cada blockchain de origem que deseja liquidar automaticamente
Uma regra para “USDC no Ethereum” não será acionada para “USDC na Base”
Isso permite controle granular sobre o comportamento de liquidação por chain

Exemplo: Se você quiser liquidar automaticamente depósitos de USDC tanto do Ethereum quanto da Base para Optimism, você precisa de duas regras separadas:

Regra para Ethereum USDC → Optimism USDC
Regra para Base USDC → Optimism USDC

Casos de Uso para Cada Nível

Regras de Carteira Principal

Estratégia Consistente: Mesmo comportamento de liquidação em todos os endereços filhos
Gerenciamento Simplificado: Local único para configurar comportamento padrão
Operações em Massa: Aplicar regras a múltiplos endereços de uma vez
Padronização: Garantir conformidade e consistência

Regras de Endereço Filho

Teste: Experimente diferentes estratégias de liquidação em endereços específicos
Requisitos Personalizados: Necessidades de liquidação específicas do endereço
Substituir Padrões: Modificar comportamento para casos de uso particulares
Controle Granular: Ajuste fino da liquidação para endereços específicos

Criando Regras de Liquidação Automática

Via Dashboard

Navegue até a seção Auto Settlements da sua carteira
Clique em “Create New Rule”
Configure os parâmetros da regra
Defina limites de valor e tolerância de slippage
Escolha ativos/chains de origem e destino
Salve e ative a regra

Via API

Crie regras de liquidação programaticamente usando a API de Regras de Liquidação Automática:

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Trocar de USDC para USDC Optimism",
    "order": "FASTEST",
    "slippageTolerance": "-1",
    "source": {
        "assets": [
            "USDC",
            "USDT"
        ],
        "minAmount": "1",
        "maxAmount": "1000"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC"
    }
}'

Neste exemplo, slippageTolerance está definido como -1 para slippage ilimitado, e destination.address está omitido. O sistema usará automaticamente a lógica de fallback inteligente para determinar o endereço do destinatário.

Com endereço de destino explícito:

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Trocar de USDC para USDC Optimism",
    "order": "FASTEST",
    "slippageTolerance": "5",
    "source": {
        "assets": [
            "USDC",
            "USDT"
        ],
        "minAmount": "1",
        "maxAmount": "1000"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC",
        "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
    }
}'

Casos de Uso

Gerenciamento de Tesouro

Conversão Flexível de Ativos: Converta para qualquer ativo preferido (USDC, ETH, USDT, etc.)
Operações Cross-Chain: Mantenha saldos em múltiplas redes
Consolidação Automatizada: Nenhuma intervenção manual necessária
Estratégia Multi-Ativos: Suporte várias preferências e estratégias de ativos

Operações de Negócios

Processamento de Pagamentos: Liquide automaticamente pagamentos recebidos para ativos preferidos
Gerenciamento de Receita: Converta várias stablecoins para seu ativo de destino escolhido
Mitigação de Risco: Aplique proteção de slippage automaticamente
Diversificação de Ativos: Mantenha alocações de ativos alvo automaticamente

Integração DeFi

Yield Farming: Liquide automaticamente recompensas para ativo preferido
Gerenciamento de Liquidez: Consolide recompensas e taxas de LP
Rebalanceamento de Portfólio: Mantenha alocações de ativos alvo

Melhores Práticas

Configuração de Regra

Comece Conservador: Comece com tolerância de slippage baixa
Monitore Desempenho: Rastreie taxas de sucesso de liquidação
Ajuste Gradualmente: Ajuste regras com base nas condições de mercado
Teste na Testnet: Valide regras antes da implantação na mainnet

Gerenciamento de Risco

Limites de Slippage: Defina níveis de tolerância apropriados
Limites de Valor: Limite tamanhos máximos de liquidação
Seleção de Rede: Escolha chains de destino confiáveis
Regras de Fallback: Crie opções de liquidação de backup

Eficiência Operacional

Processamento em Lote: Agrupe depósitos pequenos para eficiência
Otimização de Tempo: Considere padrões de congestionamento de rede
Análise de Custo: Equilibre preferências de velocidade vs. custo
Monitoramento: Configure alertas para liquidações falhadas

Monitoramento e Alertas

Monitoramento via Dashboard

Status da Regra: Indicadores de regra ativa/inativa
Histórico de Liquidação: Rastreie liquidações bem-sucedidas e falhadas
Métricas de Desempenho: Taxas de sucesso e tempos de execução
Saldos de Ativos: Monitore crescimento de saldo unificado

Notificações de Webhook

Liquidações automáticas acionam eventos de webhook quando as liquidações são executadas:

Evento	Descrição
`swap.success`	Swap de liquidação automática foi executado com sucesso
`swap.failed`	Swap de liquidação automática falhou ao executar

Exemplo de Carga Útil de Webhook

{
  "event": "swap.success",
  "data": {
    "id": "99a2b490-0798-460b-9265-4d99f182fe52",
    "reference": "ZMxcorDGtf",
    "senderAddress": "0xAA2d5fd5e7bE97E214f8565DCf3a4862719960b5",
    "recipientAddress": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43",
    "amount": "5",
    "status": "SUCCESS",
    "type": "SWAP",
    "network": "mainnet",
    "toAmount": "4.965398",
    "rate": "0.9930796000000001",
    "asset": {
      "name": "USD Coin",
      "symbol": "USDC",
      "network": "mainnet"
    },
    "toAsset": {
      "name": "Tether USD",
      "symbol": "USDT",
      "network": "mainnet"
    },
    "toBlockchain": {
      "name": "optimism",
      "slug": "optimism"
    },
    "toWallet": {
      "name": "Optimism Mainnet Wallet",
      "address": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43"
    },
    "metadata": {
      "swapAutoSettlement": {
        "rule": {
          "id": "rule-id-123",
          "name": "USDT para USDC na Base",
          "order": "RECOMMENDED",
          "slippageTolerance": 5,
          "source": {
            "assets": ["USDC", "USDT"],
            "minAmount": "1",
            "maxAmount": "1000"
          },
          "destination": {
            "blockchain": "optimism",
            "asset": "USDC",
            "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
          }
        },
        "settleAmount": "5"
      },
      "transactionId": "transaction-id"
    }
  }
}

Distinguindo Liquidações Automáticas de Swaps Regulares

A carga útil do webhook inclui metadados que ajudam a identificar transações de liquidação automática:

Campo	Descrição
`metadata.swapAutoSettlement.rule`	Carga útil completa da regra de liquidação automática que acionou este swap
`metadata.swapAutoSettlement.settleAmount`	Valor que foi liquidado de acordo com a regra
`metadata.transactionId`	ID interno da transação para rastreamento

Quando metadata.swapAutoSettlement está presente, o swap foi acionado por uma regra de liquidação automática. O campo rule contém a configuração completa da regra, não apenas um ID.

Campos Principais de Dados do Webhook

Campo	Descrição
`toAmount`	Valor final recebido após o swap (contabilizando taxas e slippage)
`rate`	Taxa de câmbio usada para o swap
`toAsset`	Detalhes do ativo de destino (USDT neste exemplo)
`toBlockchain`	Rede blockchain de destino (Optimism neste exemplo)
`toWallet`	Carteira de destino que recebeu os ativos convertidos
`assetSwept`	Se os ativos originais foram swept após a conversão

Referência da API

Endpoints

Liquidações Automáticas da Carteira Principal

Endpoint	Método	Descrição	Referência da API
`/v1/wallets/{walletId}/auto-settlements/rules`	GET	Listar todas as regras de liquidação para carteira principal	Obter Todas as Regras
`/v1/wallets/{walletId}/auto-settlements/rules`	POST	Criar nova regra de liquidação para carteira principal	Criar Regra
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	GET	Obter detalhes específicos da regra da carteira principal	Obter Regra
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	PATCH	Atualizar regra existente da carteira principal	Atualizar Regra
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	DELETE	Excluir regra de liquidação da carteira principal	Excluir Regra
`/v1/wallets/{walletId}/auto-settlements`	GET	Obter histórico de liquidação da carteira principal	Obter Liquidação
`/v1/wallets/{walletId}/auto-settlements`	PATCH	Atualizar configurações de liquidação da carteira principal	Atualizar Liquidação

Liquidações Automáticas de Endereço Filho

Endpoint	Método	Descrição	Referência da API
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules`	GET	Listar todas as regras de liquidação para endereço específico	Obter Todas as Regras
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules`	POST	Criar nova regra de liquidação para endereço específico	Criar Regra
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	GET	Obter detalhes específicos da regra do endereço	Obter Regra
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	PATCH	Atualizar regra existente do endereço	Atualizar Regra
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	DELETE	Excluir regra de liquidação do endereço	Excluir Regra
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`	GET	Obter histórico de liquidação do endereço	Obter Liquidação
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`	PATCH	Atualizar configurações de liquidação do endereço	Atualizar Liquidação

Parâmetros da Regra

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da regra para identificação
`order`	string	Sim	Prioridade de execução (FASTEST/CHEAPEST/RECOMMENDED/NO_SLIPPAGE)
`slippageTolerance`	string	Não	Slippage máximo aceitável (%). Use `-1` para ilimitado (padrão)
`isGateway`	boolean	Não	Habilitar funcionalidade de gateway para a regra
`source.assets`	array	Sim	Array de ativos de origem para liquidar automaticamente
`source.minAmount`	string	Não	Valor mínimo para acionar liquidação. Use `-1` para sem mínimo
`source.maxAmount`	string	Não	Valor máximo por liquidação. Use `-1` para ilimitado
`destination.blockchain`	string	Sim	Rede blockchain de destino
`destination.asset`	string	Sim	Ativo de destino para conversão
`destination.address`	string	Não	Endereço de destino. Se omitido, usa lógica de fallback inteligente (ver acima)

Começando

1. Habilite Liquidações Automáticas

Navegue até as configurações da sua carteira
Habilite a funcionalidade de liquidação automática
Configure preferências padrão

2. Crie Sua Primeira Regra

Comece com uma regra simples de USDT para ETH (ou qualquer ativo que você preferir)
Defina tolerância de slippage conservadora
Escolha sua chain e ativo de destino preferidos

3. Teste e Monitore

Implante na testnet primeiro
Monitore taxas de sucesso de liquidação
Ajuste parâmetros conforme necessário

4. Escale Gradualmente

Adicione regras para ativos adicionais
Implemente processamento em lote
Otimize para seu caso de uso

Suporte e Recursos

Obtendo Ajuda

E-mail: [email protected]
Referência da API: Regras de Liquidação Automática
Documentação: Configuração de Gateway

Liquidações automáticas são uma maneira poderosa de automatizar seu gerenciamento de tesouro. Comece com regras simples e adicione complexidade gradualmente à medida que você se familiariza com o sistema.

​Pré-requisitos

​Como Funciona

Gerenciamento de Regras

Conversão de Ativos

Cross-Chain

Gerenciamento de Risco

​Como Funcionam as Liquidações Automáticas

​1. Criação de Regra

​2. Detecção de Depósito

​3. Conversão de Ativos

​4. Unificação de Saldo

​Regras de Liquidação Automática

​Componentes da Regra

​Opções de Configuração de Regra

​Limites de Valor

​Proteção de Slippage

​Endereço de Destino (Opcional)

​Preferências de Execução

​Hierarquia e Precedência de Regras

​Como as Regras se Aplicam

​Ordem de Aplicação de Regras

​Regras Específicas por Blockchain

​Casos de Uso para Cada Nível

​Regras de Carteira Principal

​Regras de Endereço Filho

​Criando Regras de Liquidação Automática

​Via Dashboard

​Via API

​Casos de Uso

​Gerenciamento de Tesouro

​Operações de Negócios

​Integração DeFi

​Melhores Práticas

​Configuração de Regra

​Gerenciamento de Risco

​Eficiência Operacional

​Monitoramento e Alertas

​Monitoramento via Dashboard

​Notificações de Webhook

​Exemplo de Carga Útil de Webhook

​Distinguindo Liquidações Automáticas de Swaps Regulares

​Campos Principais de Dados do Webhook

​Referência da API

​Endpoints

​Liquidações Automáticas da Carteira Principal

​Liquidações Automáticas de Endereço Filho

​Parâmetros da Regra

​Começando

​1. Habilite Liquidações Automáticas

​2. Crie Sua Primeira Regra

​3. Teste e Monitore

​4. Escale Gradualmente

​Suporte e Recursos

​Obtendo Ajuda

Pré-requisitos

Como Funciona

Como Funcionam as Liquidações Automáticas

1. Criação de Regra

2. Detecção de Depósito

3. Conversão de Ativos

4. Unificação de Saldo

Regras de Liquidação Automática

Componentes da Regra

Opções de Configuração de Regra

Limites de Valor

Proteção de Slippage

Endereço de Destino (Opcional)

Preferências de Execução

Hierarquia e Precedência de Regras

Como as Regras se Aplicam

Ordem de Aplicação de Regras

Regras Específicas por Blockchain

Casos de Uso para Cada Nível

Regras de Carteira Principal

Regras de Endereço Filho

Criando Regras de Liquidação Automática

Via Dashboard

Via API

Casos de Uso

Gerenciamento de Tesouro

Operações de Negócios

Integração DeFi

Melhores Práticas

Configuração de Regra

Gerenciamento de Risco

Eficiência Operacional

Monitoramento e Alertas

Monitoramento via Dashboard

Notificações de Webhook

Exemplo de Carga Útil de Webhook

Distinguindo Liquidações Automáticas de Swaps Regulares

Campos Principais de Dados do Webhook

Referência da API

Endpoints

Liquidações Automáticas da Carteira Principal

Liquidações Automáticas de Endereço Filho

Parâmetros da Regra

Começando

1. Habilite Liquidações Automáticas

2. Crie Sua Primeira Regra

3. Teste e Monitore

4. Escale Gradualmente

Suporte e Recursos

Obtendo Ajuda