Liquidações Automáticas

Em resumo
As Liquidações Automáticas convertem automaticamente os depósitos recebidos no ativo de sua preferência em qualquer blockchain. Defina as regras uma única vez e todos os depósitos correspondentes são trocados e roteados para sua cadeia de destino — sem intervenção manual.

Pré-requisitos

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

Chave de API

Obtenha sua chave de API no Painel Blockradar. Acesse Developers para gerar uma.

Master Wallet criada

Crie uma master wallet via API Create Wallet ou pelo painel. As regras são configuradas por wallet.

Wallet de destino

Se for liquidar entre cadeias, certifique-se de ter uma wallet na blockchain de destino para receber os ativos convertidos.

Gas suficiente

Financie suas wallets 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á os eventos swap.success/swap.failed, gateway.success/gateway.failed ou withdraw.success/withdraw.failed. Consulte Webhooks para mais detalhes.

Como funciona

As Liquidações Automáticas permitem converter automaticamente os depósitos recebidos em qualquer ativo de destino em qualquer rede blockchain com base nas regras que você configurar. Isso elimina a necessidade de fazer swap ou bridge de ativos manualmente, garantindo que sua tesouraria possa ser convertida automaticamente para os ativos preferidos em várias cadeias.

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 em outro ativo com base em suas regras.

Multicadeia

Liquide ativos em qualquer rede blockchain de forma fluida.

Gestão de risco

Aplique tolerância de slippage e regras para se proteger contra execuções desfavoráveis.

Como funcionam as Liquidações Automáticas

1. Criação de regras

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

2. Detecção de depósitos

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

3. Conversão de ativos

Os depósitos passam por swap automático para o ativo de destino (geralmente USDC) na cadeia escolhida.

4. Unificação de saldos

Todos os ativos convertidos são consolidados em um único saldo unificado em sua cadeia 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	”Swap from USDC to Optimism USDC”
Order	Preferência de prioridade de execução	FASTEST, CHEAPEST, RECOMMENDED, NO_SLIPPAGE
Tolerância de slippage	Desvio de preço máximo aceitável (%). Use `-1` para slippage ilimitado	5 ou -1
Ativos de origem	Lista de ativos para liquidação automática	[“USDC”, “USDT”]
Valor mín./máx. de origem	Controla o tamanho do depósito que aciona a liquidação	Mín.: $1, Máx.:$ 1.000
Blockchain de destino	Rede blockchain alvo	optimism, base, ethereum
Ativo de destino	Ativo alvo da conversão	USDC, USDT, cNGN, DAI
Endereço de destino	(Opcional) Endereço específico para receber os ativos convertidos. Se não for fornecido, aplica-se a lógica de fallback inteligente	0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22
Is Gateway	Habilita a funcionalidade de gateway para a regra	false

Opções de configuração da regra

Limites de valor

Valor mínimo: Liquidar apenas depósitos acima desse limite
Valor máximo: Limitar o tamanho de cada liquidação individual
Processamento em lote: Agrupar vários depósitos pequenos para maior eficiência

Proteção contra 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. Esse é o comportamento padrão se não for 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 uma lógica de fallback inteligente para determinar o endereço destinatário:

Cenário	Comportamento de fallback
Endereço explícito fornecido	Usa o endereço especificado
Liquidação na mesma cadeia	Usa o endereço de depósito (endereço de origem)
Cross-chain entre EVM	Usa o mesmo endereço na cadeia de destino
Cross-chain (destino não-EVM)	Usa o endereço da master wallet na cadeia 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 em vez de custo
Cheapest: Otimiza para as menores taxas
Recommended: Equilibra velocidade e custo com confiabilidade
No Slippage: Executa apenas quando não houver desvio de preço

Hierarquia e precedência das regras

Como as regras são aplicadas

Conceito-chave: As regras criadas em uma master wallet são aplicadas automaticamente a todas as child addresses sob essa wallet. No entanto, se você criar regras diretamente em uma child address, essas regras substituirão completamente as regras da master wallet para aquele endereço específico.

Nível da regra	Escopo	Comportamento
Regras de Master Wallet	Aplicam-se à master wallet E a todas as child addresses	Regras padrão para toda a hierarquia da wallet
Regras de Child Address	Aplicam-se apenas àquele endereço específico	Substituem completamente as regras da master wallet quando presentes

Ordem de aplicação das regras

Verificar regras de Child Address: Se o endereço receptor tiver suas próprias regras, use exclusivamente essas
Recorrer às regras da Master Wallet: Se não existirem regras de child address, aplique as regras da master wallet
Sem regras: Se nenhum dos níveis tiver regras configuradas, nenhuma liquidação automática ocorre

Quando uma child address tem suas próprias regras, as regras da master wallet são completamente ignoradas para aquele 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 uma blockchain (por exemplo, Ethereum) NÃO afetará depósitos em outra blockchain (por exemplo, Base ou Optimism).

Isso significa que:

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

Exemplo: Se você quer liquidar automaticamente depósitos de USDC tanto da Ethereum quanto da Base para a Optimism, 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 Master Wallet

Estratégia consistente: Mesmo comportamento de liquidação em todas as child addresses
Gestão simplificada: Local único para configurar o comportamento padrão
Operações em massa: Aplique regras a vários endereços de uma só vez
Padronização: Garanta conformidade e consistência

Regras de Child Address

Testes: Experimente diferentes estratégias de liquidação em endereços específicos
Requisitos personalizados: Necessidades de liquidação específicas por endereço
Substituir padrões: Modifique o 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

Pelo Painel

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

Pela API

Crie regras de liquidação programaticamente usando a API de Auto Settlement Rules:

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": "Swap from USDC to Optimism USDC",
    "order": "FASTEST",
    "slippageTolerance": "-1",
    "source": {
        "assets": [
            "USDC",
            "USDT"
        ],
        "minAmount": "1",
        "maxAmount": "1000"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC"
    }
}'

Neste exemplo, slippageTolerance é definido como -1 para slippage ilimitado, e destination.address é omitido. O sistema usará automaticamente a lógica de fallback inteligente para determinar o endereço 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": "Swap from USDC to Optimism USDC",
    "order": "FASTEST",
    "slippageTolerance": "5",
    "source": {
        "assets": [
            "USDC",
            "USDT"
        ],
        "minAmount": "1",
        "maxAmount": "1000"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC",
        "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
    }
}'

Casos de uso

Gestão de tesouraria

Conversão flexível de ativos: Converta para qualquer ativo preferido (USDC, ETH, USDT, etc.)
Operações cross-chain: Mantenha saldos em várias redes
Consolidação automatizada: Sem necessidade de intervenção manual
Estratégia multiativos: Suporte para várias preferências e estratégias de ativos

Operações empresariais

Processamento de pagamentos: Liquide automaticamente os pagamentos recebidos para os ativos preferidos
Gestão de receitas: Converta diversas stablecoins para o ativo de destino escolhido
Mitigação de riscos: Aplique proteção contra slippage automaticamente
Diversificação de ativos: Mantenha as alocações de ativos-alvo automaticamente

Integração com DeFi

Yield farming: Liquide automaticamente as recompensas para o ativo preferido
Gestão de liquidez: Consolide recompensas e taxas de LP
Rebalanceamento de portfólio: Mantenha as alocações de ativos-alvo

Boas práticas

Configuração de regras

Comece de forma conservadora: Inicie com baixa tolerância de slippage
Monitore o desempenho: Acompanhe as taxas de sucesso das liquidações
Ajuste gradualmente: Refine as regras conforme as condições de mercado
Teste em testnet: Valide as regras antes do deploy em mainnet

Gestão de risco

Limites de slippage: Defina níveis de tolerância apropriados
Tetos de valor: Limite o tamanho máximo das liquidações
Seleção de rede: Escolha cadeias 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 maior eficiência
Otimização de tempo: Considere padrões de congestionamento da rede
Análise de custos: Equilibre as preferências de velocidade vs. custo
Monitoramento: Configure alertas para liquidações falhas

Monitoramento e alertas

Monitoramento pelo painel

Status das regras: Indicadores de regra ativa/inativa
Histórico de liquidações: Acompanhe liquidações bem-sucedidas e falhas
Métricas de desempenho: Taxas de sucesso e tempos de execução
Saldos de ativos: Monitore o crescimento do saldo unificado

Notificações por webhook

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

Evento	Descrição
`swap.success`	O swap da liquidação automática foi executado com sucesso
`swap.failed`	O swap da liquidação automática falhou ao ser executado

Exemplo de payload 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 to USDC on 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"
    }
  }
}

Identificando transações de liquidação automática

A melhor maneira de identificar as transações de liquidação automática é verificando o campo metadata. Dependendo da ação, o metadata conterá uma destas chaves:

Chave de metadata	Descrição
`swapAutoSettlement`	Presente quando a liquidação automática acionou uma operação de swap
`gatewayAutoSettlement`	Presente quando a liquidação automática acionou uma operação de Gateway
`withdrawAutoSettlement`	Presente quando a liquidação automática acionou uma operação de saque

Cada objeto metadata contém:

Campo	Descrição
`rule`	Payload completo da regra de liquidação automática que acionou esta transação
`settleAmount`	Valor liquidado conforme a regra

Quando qualquer uma dessas chaves de metadata (swapAutoSettlement, gatewayAutoSettlement ou withdrawAutoSettlement) está presente, a transação foi acionada por uma regra de liquidação automática. O campo rule contém a configuração completa da regra, e não apenas um ID.

Campos-chave dos dados do webhook

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

Referência da API

Endpoints

Liquidações Automáticas de Master Wallet

Endpoint	Método	Descrição	Referência da API
`/v1/wallets/{walletId}/auto-settlements/rules`	GET	Listar todas as regras de liquidação da master wallet	Get All Rules
`/v1/wallets/{walletId}/auto-settlements/rules`	POST	Criar nova regra de liquidação para a master wallet	Create Rule
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	GET	Obter detalhes de uma regra específica da master wallet	Get Rule
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	PATCH	Atualizar regra existente da master wallet	Update Rule
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	DELETE	Excluir regra de liquidação da master wallet	Delete Rule
`/v1/wallets/{walletId}/auto-settlements`	GET	Obter histórico de liquidações da master wallet	Get Settlement
`/v1/wallets/{walletId}/auto-settlements`	PATCH	Atualizar configurações de liquidação da master wallet	Update Settlement

Liquidações Automáticas de Child Address

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 um endereço específico	Get All Rules
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules`	POST	Criar nova regra de liquidação para um endereço específico	Create Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	GET	Obter detalhes da regra de um endereço específico	Get Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	PATCH	Atualizar regra existente do endereço	Update Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	DELETE	Excluir regra de liquidação do endereço	Delete Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`	GET	Obter histórico de liquidações do endereço	Get Settlement
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`	PATCH	Atualizar configurações de liquidação do endereço	Update Settlement

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	Habilita a funcionalidade de gateway para a regra
`source.assets`	array	Sim	Lista de ativos de origem para liquidação automática
`source.minAmount`	string	Não	Valor mínimo para acionar a 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 alvo
`destination.asset`	string	Sim	Ativo alvo da conversão
`destination.address`	string	Não	Endereço de destino. Se omitido, usa a lógica de fallback inteligente (ver acima)

Primeiros passos

1. Habilite as Liquidações Automáticas

Acesse as configurações da sua wallet
Habilite a funcionalidade de liquidação automática
Configure as preferências padrão

2. Crie sua primeira regra

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

3. Teste e monitore

Faça o deploy primeiro em testnet
Monitore as taxas de sucesso das liquidações
Ajuste os parâmetros conforme necessário

4. Escale gradualmente

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

Suporte e recursos

Como obter ajuda

E-mail: [email protected]
Referência da API: Auto Settlement Rules
Documentação: Configuração do Gateway

As liquidações automáticas são uma forma poderosa de automatizar a gestão da sua tesouraria. Comece com regras simples e adicione complexidade gradualmente, à medida que se familiarizar com o sistema.

​Pré-requisitos

​Como funciona

Gerenciamento de regras

Conversão de ativos

Multicadeia

Gestão de risco

​Como funcionam as Liquidações Automáticas

​1. Criação de regras

​2. Detecção de depósitos

​3. Conversão de ativos

​4. Unificação de saldos

​Regras de Liquidação Automática

​Componentes da regra

​Opções de configuração da regra

​Limites de valor

​Proteção contra slippage

​Endereço de destino (Opcional)

​Preferências de execução

​Hierarquia e precedência das regras

​Como as regras são aplicadas

​Ordem de aplicação das regras

​Regras específicas por blockchain

​Casos de uso para cada nível

​Regras de Master Wallet

​Regras de Child Address

​Criando regras de Liquidação Automática

​Pelo Painel

​Pela API

​Casos de uso

​Gestão de tesouraria

​Operações empresariais

​Integração com DeFi

​Boas práticas

​Configuração de regras

​Gestão de risco

​Eficiência operacional

​Monitoramento e alertas

​Monitoramento pelo painel

​Notificações por webhook

​Exemplo de payload de webhook

​Identificando transações de liquidação automática

​Campos-chave dos dados do webhook

​Referência da API

​Endpoints

​Liquidações Automáticas de Master Wallet

​Liquidações Automáticas de Child Address

​Parâmetros da regra

​Primeiros passos

​1. Habilite as Liquidações Automáticas

​2. Crie sua primeira regra

​3. Teste e monitore

​4. Escale gradualmente

​Suporte e recursos

​Como obter ajuda

Pré-requisitos

Como funciona

Como funcionam as Liquidações Automáticas

1. Criação de regras

2. Detecção de depósitos

3. Conversão de ativos

4. Unificação de saldos

Regras de Liquidação Automática

Componentes da regra

Opções de configuração da regra

Limites de valor

Proteção contra slippage

Endereço de destino (Opcional)

Preferências de execução

Hierarquia e precedência das regras

Como as regras são aplicadas

Ordem de aplicação das regras

Regras específicas por blockchain

Casos de uso para cada nível

Regras de Master Wallet

Regras de Child Address

Criando regras de Liquidação Automática

Pelo Painel

Pela API

Casos de uso

Gestão de tesouraria

Operações empresariais

Integração com DeFi

Boas práticas

Configuração de regras

Gestão de risco

Eficiência operacional

Monitoramento e alertas

Monitoramento pelo painel

Notificações por webhook

Exemplo de payload de webhook

Identificando transações de liquidação automática

Campos-chave dos dados do webhook

Referência da API

Endpoints

Liquidações Automáticas de Master Wallet

Liquidações Automáticas de Child Address

Parâmetros da regra

Primeiros passos

1. Habilite as Liquidações Automáticas

2. Crie sua primeira regra

3. Teste e monitore

4. Escale gradualmente

Suporte e recursos

Como obter ajuda