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 no Painel da Blockradar. As regras são configuradas por wallet — consulte uma com Get 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. A família de eventos depende do tipo de liquidação executado: swap.*, withdraw.*, gateway-deposit.* ou reward-deposit.*. Consulte Notificações por webhook abaixo e o guia de 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.

Tipos de liquidação

Cada regra se resolve em um de quatro fluxos de liquidação. Defina-o explicitamente com o campo type:

Tipo	O que a regra faz	Campo acompanhante obrigatório
`withdraw`	Transfere o ativo de origem como está para `destination.address` na mesma blockchain. Sem conversão.	`destination.address`, e `destination.blockchain` deve ser igual à blockchain de origem
`swap`	Converte para um ativo diferente e/ou para outra blockchain.	Os ativos de origem devem ser diferentes do ativo de destino quando ambos estão na mesma cadeia
`gateway`	Deposita USDC no saldo unificado do Gateway da Circle.	`isGateway: true`
`earn`	Deposita em uma posição de Earn com Fija ou Aave.	`isReward: true`

type é opcional por retrocompatibilidade. As regras criadas antes de esse campo existir não têm type e mantêm o comportamento inferido: a Blockradar decide entre withdraw e swap comparando o ativo e a cadeia de origem e de destino. Envie type em toda regra nova para que o fluxo seja explícito, e envie-o em uma atualização para migrar uma regra legada para o sistema explícito.

Em um child address, type não é apenas uma sugestão. Se você criar uma regra em um child address sem type, os campos estendidos — isReward, rewardProvider, rewardType, useTransactionAmount e deductionPercentage — são descartados silenciosamente e a regra é salva no formato legado. Sempre envie type ao criar regras em child addresses.

Regras de validação por tipo

A API rejeita combinações contraditórias:

type: gateway exige isGateway: true, e isGateway: true exige type: gateway
type: earn exige isReward: true, e isReward: true exige type: earn
Uma regra nunca pode ser gateway e earn ao mesmo tempo
type: withdraw exige um destination.address, e a blockchain de destino deve ser igual à de origem
type: swap rejeita um ativo de origem igual ao ativo de destino na mesma blockchain
Duas regras da mesma wallet não podem cobrir o mesmo ativo de origem na mesma blockchain

As regras de gateway podem recair para swap

Uma regra gateway só faz um depósito no Gateway quando a cadeia e o ativo de origem são elegíveis para o Gateway. Quando não são, a regra prossegue e é executada como um swap para destination.blockchain / destination.asset. Os fundos são liquidados do mesmo jeito, mas você recebe webhooks swap.* em vez de gateway-deposit.*, então trate ambos ao configurar regras de gateway em cadeias fora do conjunto suportado pelo Gateway.

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
Type	Fluxo de liquidação da regra	withdraw, swap, gateway, earn
Nome da regra	Nome descritivo para sua regra de liquidação	”Swap from USDC to Optimism USDC”
Order	Preferência de roteamento para a etapa de swap. Ignorado nas regras gateway e earn	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, exceto nas regras withdraw) 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	Roteia a liquidação pelo Gateway da Circle	false
Is Reward	Roteia a liquidação para uma posição de Earn	false
Use Transaction Amount	Liquidar o valor do depósito que acionou a regra em vez do saldo do endereço	false
Deduction Percentage	Percentual retido do valor liquidado	”0”
Inheritance	Para quais child addresses uma regra da master wallet se propaga	`{ "mode": "all_children" }`

Quanto é liquidado

Por padrão, o valor de uma liquidação é calculado a partir do saldo do endereço, não do depósito que a acionou. Use useTransactionAmount para escolher:

`useTransactionAmount`	O que é liquidado
`false` (padrão)	O saldo atual do ativo de origem no endereço, que pode ser maior que o depósito que acionou a regra, por exemplo quando depósitos anteriores ficaram sem liquidar
`true`	Apenas o valor do depósito que acionou a regra

Em seguida, o valor é ajustado nesta ordem:

É comparado com source.minAmount. Abaixo desse valor, nada é liquidado.
É limitado a source.maxAmount ("-1" significa sem limite).
deductionPercentage é retido do restante. "2.5" liquida 97,5% e deixa 2,5% no endereço.

Use useTransactionAmount: true quando precisar que cada depósito corresponda exatamente a uma liquidação, por exemplo para conciliação pagamento a pagamento. Deixe em false quando quiser esvaziar o endereço a cada vez.

Regras de liquidação para Earn

Uma regra earn deposita os fundos recebidos em uma posição de rendimento em vez de transferi-los para fora. É o ponto de entrada da liquidação automática para o Earn.

Campo	Valor
`type`	`earn`
`isReward`	`true`
`rewardProvider`	`fija` ou `aave`
`rewardType`	`regulated` para `fija`, `defi` para `aave`

Restrições:

Apenas mainnet. As regras earn são rejeitadas na testnet.
Cada ativo em source.assets deve ser suportado pelo provedor escolhido na blockchain da wallet, caso contrário a regra é rejeitada na criação.
rewardProvider e rewardType devem corresponder: fija é sempre regulated e aave é sempre defi.
Uma regra não pode ser isGateway e isReward ao mesmo tempo.

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 '{
    "type": "earn",
    "name": "Earn on Base USDC deposits",
    "isReward": true,
    "rewardProvider": "aave",
    "rewardType": "defi",
    "source": {
        "assets": ["USDC"],
        "minAmount": "10",
        "maxAmount": "-1"
    },
    "destination": {
        "blockchain": "base",
        "asset": "USDC"
    }
}'

As liquidações para o Earn criam uma transação REWARD_DEPOSIT e emitem webhooks reward-deposit.*.

As regras earn baseadas em saldo (useTransactionAmount: false) pulam uma nova liquidação enquanto já houver uma pendente ou em processamento para o mesmo endereço e ativo, porque a liquidação em andamento absorverá os fundos recém-chegados de qualquer forma. As regras earn baseadas em valor (useTransactionAmount: true) nunca são puladas.

Opções de configuração da regra

Limites de valor

Valor mínimo: Liquidar apenas quando o valor estiver acima desse limite
Valor máximo: Limitar o tamanho de cada liquidação individual
Acumulação: Com useTransactionAmount: false (o padrão), a regra liquida todo o saldo do ativo de origem no endereço, de modo que depósitos que individualmente ficaram abaixo de minAmount são recolhidos juntos assim que o saldo o ultrapassa

Proteção contra slippage

Ilimitado: -1 (sem limite de slippage)
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)

Antes de executar, a liquidação obtém uma cotação e compara o slippage dela com a sua tolerância. Se a cotação ultrapassar a tolerância, a liquidação falha em vez de ser executada a um preço pior.

Sempre envie slippageTolerance explicitamente nas regras de swap. "-1" significa ilimitado, e um valor como "5" significa 5%. Uma tolerância de "0" só permite uma liquidação com slippage exatamente zero, o que rejeita praticamente qualquer cotação real. As regras gateway e earn não usam a tolerância de slippage.

Endereço de destino (Opcional)

O campo destination.address é opcional nas regras swap, gateway e earn. 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.

As regras withdraw são a exceção: exigem um destination.address explícito, e destination.blockchain deve ser a mesma blockchain da origem. destination.blockchain e destination.asset são sempre obrigatórios, em qualquer tipo de regra.

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: Por padrão, as regras criadas em uma master wallet aplicam-se à master wallet e a todas as child addresses sob ela. Uma regra em uma child address tem precedência sobre as regras da master wallet para o depósito com o qual ela corresponde.

Nível da regra	Escopo	Comportamento
Regras de Master Wallet	A master wallet, mais as child addresses selecionadas pela configuração `inheritance` da regra (todas elas por padrão)	Regras padrão para a hierarquia da wallet
Regras de Child Address	Apenas aquele endereço específico	Têm precedência sobre as regras da master wallet para qualquer depósito com o qual correspondam

Ordem de aplicação das regras

A precedência é avaliada por depósito, não por endereço:

Procurar uma regra correspondente na child address. Uma regra corresponde quando está ativa e seus campos source.assets e source.blockchain cobrem o depósito.
Recorrer às regras da master wallet. Uma regra da master wallet só é considerada então se a configuração inheritance dela permitir que se aplique ao endereço que recebeu o depósito.
Sem correspondência em nenhum dos níveis: nenhuma liquidação automática ocorre.

O fato de uma child address ter algumas regras não desativa as regras da master wallet para aquele endereço. Se nenhuma das regras da child address corresponder ao ativo e à cadeia depositados, as regras da master wallet são avaliadas em seguida. Para impedir que uma regra da master wallet alcance um endereço, defina explicitamente o inheritance dessa regra, como explicado abaixo.

Herança por regra

Cada regra da master wallet controla para quais child addresses ela se propaga por meio do objeto opcional inheritance:

`mode`	A regra aplica-se a
`all_children`	A master wallet e todas as child addresses
`master_only`	Apenas a master wallet — esta regra ignora os depósitos nas child addresses
`selected_children`	A master wallet mais os endereços específicos listados em `childAddressIds`

Omitir inheritance por completo mantém o comportamento original e equivale a all_children.

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 '{
    "type": "swap",
    "name": "Settle USDT deposits from partner addresses",
    "slippageTolerance": "1",
    "inheritance": {
        "mode": "selected_children",
        "childAddressIds": [
            "0f9a1c3e-58c2-4a1b-9f0d-6d5f2a7c1b34",
            "7b3d9e21-4f6a-4c0e-8a52-1c9b0e4d7f88"
        ]
    },
    "source": {
        "assets": ["USDT"],
        "minAmount": "1",
        "maxAmount": "-1"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC"
    }
}'

Regras para selected_children:

childAddressIds deve estar presente e não vazio, caso contrário a requisição falha com At least one child address must be selected.
Cada ID deve ser um endereço ativo pertencente ao seu negócio na mesma rede.
Os endereços devem corresponder à família de cadeias da wallet. Uma regra em uma wallet não-EVM (por exemplo Tron, Solana ou Stellar) só aceita endereços daquela mesma cadeia; uma regra em uma wallet EVM aceita qualquer endereço EVM. Uma divergência falha com One or more selected child addresses are not valid for this chain or are inactive.

inheritance só existe nas regras da master wallet. Uma regra criada diretamente em uma child address não tem para onde se propagar, então o campo é ignorado e nunca é salvo ali.

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 '{
    "type": "swap",
    "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 '{
    "type": "swap",
    "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"
    }
}'

Copiar regras entre wallets

As regras são por blockchain, então implantar uma mesma estratégia em todas as cadeias em que você opera significaria recriar a mesma regra várias vezes. O endpoint de cópia faz isso em uma única chamada:

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules/copy \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "rules": [
        {
            "type": "withdraw",
            "name": "Sweep USDC to treasury",
            "slippageTolerance": "0",
            "source": {
                "assets": ["USDC"],
                "minAmount": "1",
                "maxAmount": "-1"
            },
            "destination": {
                "blockchain": "base",
                "asset": "USDC",
                "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
            }
        }
    ],
    "targetWalletIds": [
        "3f6c9a11-9a7e-4a3c-8f2b-0d51e6c4a7b2",
        "c81e7d40-5b6a-4f9e-9c3d-2a7f10b8e654"
    ]
}'

As regras são enviadas por valor, não por ID, de modo que a origem pode ser as regras de uma master wallet, as de uma child address ou um payload que você mesmo montar. O campo source.blockchain de cada regra é reescrito com a blockchain da wallet de destino antes de ser salvo.

Sucesso parcial é normal

A chamada retorna 200 mesmo quando algumas regras são puladas ou algumas wallets falham. Sempre leia a resposta em vez de confiar no código de status:

{
  "data": {
    "summary": {
      "walletsTargeted": 2,
      "rulesRequested": 1,
      "applied": 1,
      "skipped": 1,
      "failed": 0
    },
    "results": [
      {
        "walletId": "3f6c9a11-9a7e-4a3c-8f2b-0d51e6c4a7b2",
        "walletName": "Base Mainnet Wallet",
        "chain": "base",
        "applied": [{ "name": "Sweep USDC to treasury" }],
        "skipped": []
      },
      {
        "walletId": "c81e7d40-5b6a-4f9e-9c3d-2a7f10b8e654",
        "walletName": "Optimism Mainnet Wallet",
        "chain": "optimism",
        "applied": [],
        "skipped": [
          {
            "name": "Sweep USDC to treasury",
            "reason": "A settlement rule for USDC already exists on the optimism wallet"
          }
        ]
      }
    ]
  },
  "message": "Settlement rules copied",
  "statusCode": 200
}

Resultado	Significado
`applied`	A regra foi gravada naquela wallet
`skipped`	A regra foi rejeitada apenas para aquela wallet: o ativo não está habilitado lá, já existe uma regra cobrindo aquele ativo naquela cadeia, ou a regra não passou na validação para aquela wallet
`failed`	A wallet inteira não pôde ser gravada, por exemplo porque não existe ou está inativa nesta rede

Cada wallet de destino é bloqueada e gravada em sua própria transação, de modo que uma falha em uma nunca deixa outra gravada pela metade. Aplicar ao menos uma regra a uma wallet também ativa a liquidação automática naquela wallet.

A requisição em si falha com 400 quando o array rules está malformado, quando rules ou targetWalletIds está vazio, ou quando a única wallet indicada como destino é a wallet de origem (a origem é sempre removida da lista de destinos).

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

Acumulação: Deixe useTransactionAmount em false para que depósitos pequenos sejam liquidados juntos assim que o saldo ultrapassar minAmount
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. A família de eventos que você recebe depende do tipo de liquidação executado:

Tipo de liquidação	Eventos
`swap`	`swap.success`, `swap.failed`, `swap.cancelled`, `swap.processing`
`withdraw`	`withdraw.success`, `withdraw.failed`, `withdraw.cancelled`, `withdraw.processing`
`gateway`	`gateway-deposit.success`, `gateway-deposit.failed`, `gateway-deposit.cancelled`, `gateway-deposit.processing`
`earn`	`reward-deposit.success`, `reward-deposit.failed`, `reward-deposit.cancelled`, `reward-deposit.processing`

Uma regra gateway em uma cadeia que não é elegível para o Gateway recai para um swap, então emite eventos swap.* em vez de gateway-deposit.*. Assine ambos se você usa regras de gateway fora das cadeias suportadas pelo Gateway.

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
`rewardAutoSettlement`	Presente quando a liquidação automática acionou um depósito no Earn

Os objetos de swap, gateway e saque 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

rewardAutoSettlement tem um formato diferente: carrega o ID da regra em vez da regra inteira:

Campo	Descrição
`ruleId`	ID da regra earn que acionou este depósito
`settleAmount`	Valor liquidado conforme a regra
`sourceTransactionId`	ID da transação de depósito que acionou a liquidação

Quando qualquer uma dessas chaves de metadata está presente, a transação foi acionada por uma regra de liquidação automática. Nas liquidações de swap, gateway e saque o campo rule contém a configuração completa da regra, e não apenas um ID; nas liquidações earn, busque a regra pelo ruleId.

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/copy`	POST	Copiar regras de liquidação para outras master wallets	Copy Rules
`/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

Não existe um endpoint de cópia para child addresses: a cópia sempre tem master wallets como destino, embora as regras que você copia possam vir de uma child address.

A semântica de atualização difere por nível

Endpoint	Tratamento do body
`PATCH /wallets/{walletId}/auto-settlements/rules/{id}`	Mesclagem parcial. Envie apenas os campos que vai alterar; todo o resto mantém o valor atual. Objetos aninhados como `source` e `destination` são substituídos por inteiro, então envie-os completos quando os enviar
`PATCH /wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	Regra completa. `source` e `destination` são obrigatórios, e qualquer campo opcional que você omitir volta ao padrão: `order` para `RECOMMENDED`, `slippageTolerance` e `deductionPercentage` para `"0"`, `useTransactionAmount` para `false`, `isActive` para `true`, `source.minAmount` para `"0"` e `source.maxAmount` para `"-1"`

Leia a regra primeiro e envie o objeto completo ao atualizar uma regra de child address. Enviar apenas o campo que você quer alterar redefine silenciosamente o resto da regra para os padrões.

Em ambos os casos a regra mesclada é revalidada, então uma atualização pode ser rejeitada por causa de um campo que você não enviou.

Parâmetros da regra

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Não	Fluxo de liquidação: `withdraw`, `swap`, `gateway` ou `earn`. Envie em toda regra nova
`name`	string	Não	Nome da regra para identificação
`isActive`	boolean	Não	Se a regra está habilitada. Padrão `true`
`order`	string	Não	Preferência de roteamento (FASTEST/CHEAPEST/RECOMMENDED/NO_SLIPPAGE). Padrão `RECOMMENDED`; ignorado nas regras gateway e earn
`slippageTolerance`	string	Não	Slippage máximo aceitável (%). Use `-1` para ilimitado. Envie explicitamente nas regras de swap
`isGateway`	boolean	Não	Roteia pelo Gateway da Circle. Obrigatório com `type: gateway`
`isReward`	boolean	Não	Roteia para uma posição de Earn. Obrigatório com `type: earn`. Apenas mainnet
`rewardProvider`	string	Condicional	`fija` ou `aave`. Obrigatório quando `isReward` é `true`
`rewardType`	string	Condicional	`regulated` para `fija`, `defi` para `aave`. Obrigatório quando `isReward` é `true`
`useTransactionAmount`	boolean	Não	`false` (padrão) liquida o saldo do endereço; `true` liquida apenas o depósito que acionou a regra
`deductionPercentage`	string	Não	Percentual retido do valor liquidado. Padrão `"0"`
`inheritance.mode`	string	Não	`master_only`, `all_children` ou `selected_children`. Apenas em regras da master wallet
`inheritance.childAddressIds`	array	Condicional	Obrigatório e não vazio quando o modo é `selected_children`
`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. Padrão `"0"`
`source.maxAmount`	string	Não	Valor máximo por liquidação. Use `-1` para ilimitado (padrão)
`source.blockchain`	string	Não	Ignorado na criação: sempre definido como a blockchain da própria wallet
`destination.blockchain`	string	Sim	Rede blockchain alvo. Deve ser igual à de origem nas regras `withdraw`
`destination.asset`	string	Sim	Ativo alvo da conversão. Forçado para USDC nas regras gateway
`destination.address`	string	Condicional	Obrigatório nas regras `withdraw`. Nas demais é opcional: 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

​Tipos de liquidação

​Regras de validação por tipo

​As regras de gateway podem recair para swap

​Regras de Liquidação Automática

​Componentes da regra

​Quanto é liquidado

​Regras de liquidação para Earn

​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

​Herança por regra

​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

​Copiar regras entre wallets

​Sucesso parcial é normal

​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

​A semântica de atualização difere por nível

​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

Tipos de liquidação

Regras de validação por tipo

As regras de gateway podem recair para swap

Regras de Liquidação Automática

Componentes da regra

Quanto é liquidado

Regras de liquidação para Earn

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

Herança por regra

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

Copiar regras entre wallets

Sucesso parcial é normal

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

A semântica de atualização difere por nível

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