Liquidaciones Automáticas

En resumen
Las Liquidaciones Automáticas convierten automáticamente los depósitos entrantes al activo de su preferencia en cualquier blockchain. Defina las reglas una sola vez y todos los depósitos coincidentes se intercambian y enrutan a su cadena de destino, sin intervención manual.

Requisitos previos

Antes de configurar reglas de liquidación automática, asegúrese de contar con:

Clave de API

Obtenga su clave de API desde el Panel de Blockradar. Diríjase a Developers para generar una.

Master Wallet creada

Cree una master wallet en el Panel de Blockradar. Las reglas se configuran por wallet; puede consultar una con Get Wallet.

Wallet de destino

Si liquida entre cadenas, asegúrese de tener una wallet en la blockchain de destino para recibir los activos convertidos.

Gas suficiente

Financie sus wallets con tokens nativos (ETH, BNB, MATIC, etc.) para cubrir las comisiones de swap y transferencia.

Webhook configurado

Configure webhooks para recibir notificaciones de liquidación. La familia de eventos depende del tipo de liquidación que se ejecutó: swap.*, withdraw.*, gateway-deposit.* o reward-deposit.*. Consulte Notificaciones de webhook más abajo y la guía de Webhooks para más detalles.

Cómo funciona

Las Liquidaciones Automáticas le permiten convertir automáticamente los depósitos entrantes en cualquier activo de destino sobre cualquier red blockchain según las reglas que configure. Esto elimina la necesidad de intercambiar o enviar activos entre cadenas manualmente, garantizando que su tesorería pueda convertirse de forma automática a sus activos preferidos en múltiples cadenas.

Gestión de reglas

Cree y administre reglas de liquidación automática para automatizar las conversiones de activos.

Conversión de activos

Convierta automáticamente cualquier stablecoin a otro activo según sus reglas.

Multicadena

Liquide activos en cualquier red blockchain de forma fluida.

Gestión de riesgos

Aplique tolerancia de slippage y reglas para protegerse de ejecuciones desfavorables.

Cómo funcionan las Liquidaciones Automáticas

1. Creación de reglas

Defina reglas de liquidación que especifiquen cuándo y cómo se deben convertir automáticamente los depósitos.

2. Detección de depósitos

Cuando los fondos llegan a sus direcciones, Blockradar detecta automáticamente los depósitos que coinciden con sus reglas.

3. Conversión de activos

Los depósitos se intercambian automáticamente al activo de destino (normalmente USDC) en la cadena que elija.

4. Unificación de saldos

Todos los activos convertidos se consolidan en un único saldo unificado en su cadena de destino.

Tipos de liquidación

Cada regla se resuelve en uno de cuatro flujos de liquidación. Defínalo explícitamente con el campo type:

Tipo	Qué hace la regla	Campo acompañante obligatorio
`withdraw`	Transfiere el activo de origen tal cual a `destination.address` en la misma blockchain. Sin conversión.	`destination.address`, y `destination.blockchain` debe ser igual a la blockchain de origen
`swap`	Convierte a un activo distinto o traslada a otra blockchain.	Los activos de origen deben ser distintos del activo de destino cuando ambos están en la misma cadena
`gateway`	Deposita USDC en el saldo unificado de Gateway de Circle.	`isGateway: true`
`earn`	Deposita en una posición de Earn con Fija o Aave.	`isReward: true`

type es opcional por retrocompatibilidad. Las reglas creadas antes de que existiera este campo no tienen type y conservan su comportamiento inferido: Blockradar decide entre withdraw y swap comparando el activo y la cadena de origen y de destino. Envíe type en cada regla nueva para que el flujo sea explícito, y envíelo en una actualización para migrar una regla heredada al sistema explícito.

En una dirección hija, type no es solo una sugerencia. Si crea una regla en una dirección hija sin type, los campos extendidos — isReward, rewardProvider, rewardType, useTransactionAmount y deductionPercentage — se descartan silenciosamente y la regla se guarda con el formato heredado. Envíe siempre type al crear reglas en direcciones hijas.

Reglas de validación por tipo

La API rechaza las combinaciones contradictorias:

type: gateway requiere isGateway: true, y isGateway: true requiere type: gateway
type: earn requiere isReward: true, y isReward: true requiere type: earn
Una regla nunca puede ser gateway y earn a la vez
type: withdraw requiere una destination.address, y la blockchain de destino debe ser igual a la de origen
type: swap rechaza un activo de origen igual al activo de destino en la misma blockchain
Dos reglas de la misma wallet no pueden cubrir el mismo activo de origen en la misma blockchain

Las reglas de gateway pueden pasar a swap

Una regla gateway solo realiza un depósito en Gateway cuando la cadena y el activo de origen son elegibles para Gateway. Cuando no lo son, la regla continúa y se ejecuta como un swap hacia destination.blockchain / destination.asset. Los fondos se liquidan igualmente, pero usted recibe webhooks swap.* en lugar de gateway-deposit.*, así que contemple ambos cuando configure reglas de gateway en cadenas fuera del conjunto admitido por Gateway.

Reglas de Liquidación Automática

Componentes de la regla

Cada regla de liquidación automática define los siguientes parámetros:

Componente	Descripción	Ejemplo
Type	Flujo de liquidación de la regla	withdraw, swap, gateway, earn
Nombre de la regla	Nombre descriptivo de su regla de liquidación	”Swap from USDC to Optimism USDC”
Order	Preferencia de enrutamiento para el tramo de swap. Se ignora en las reglas gateway y earn	FASTEST, CHEAPEST, RECOMMENDED, NO_SLIPPAGE
Tolerancia de slippage	Desviación de precio máxima aceptable (%). Use `-1` para slippage ilimitado	5 o -1
Activos de origen	Lista de activos a liquidar automáticamente	[“USDC”, “USDT”]
Monto mín./máx. de origen	Controle el tamaño del depósito que activa la liquidación	Mín.: $1, Máx.:$ 1.000
Blockchain de destino	Red blockchain objetivo	optimism, base, ethereum
Activo de destino	Activo objetivo de la conversión	USDC, USDT, cNGN, DAI
Dirección de destino	(Opcional salvo en las reglas withdraw) Dirección específica para recibir los activos convertidos. Si no se proporciona, se aplica la lógica de fallback inteligente	0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22
Is Gateway	Enruta la liquidación a través de Gateway de Circle	false
Is Reward	Enruta la liquidación hacia una posición de Earn	false
Use Transaction Amount	Liquidar el monto del depósito que activó la regla en lugar del saldo de la dirección	false
Deduction Percentage	Porcentaje retenido del monto liquidado	”0”
Inheritance	A qué direcciones hijas se propaga una regla de la master wallet	`{ "mode": "all_children" }`

Cuánto se liquida

Por defecto, el monto de una liquidación se calcula a partir del saldo de la dirección, no del depósito que la activó. Use useTransactionAmount para elegir:

`useTransactionAmount`	Qué se liquida
`false` (por defecto)	El saldo actual del activo de origen en la dirección, que puede ser mayor que el depósito que activó la regla, por ejemplo cuando quedaron depósitos anteriores sin liquidar
`true`	Únicamente el monto del depósito que activó la regla

Después el monto se ajusta en este orden:

Se compara con source.minAmount. Por debajo de ese valor no se liquida nada.
Se limita a source.maxAmount ("-1" significa sin límite).
Se retiene deductionPercentage del resto. "2.5" liquida el 97,5 % y deja el 2,5 % en la dirección.

Use useTransactionAmount: true cuando necesite que cada depósito corresponda exactamente a una liquidación, por ejemplo para conciliar pago por pago. Déjelo en false cuando quiera vaciar la dirección en cada ocasión.

Reglas de liquidación hacia Earn

Una regla earn deposita los fondos entrantes en una posición de rendimiento en lugar de transferirlos fuera. Es el punto de entrada de la liquidación automática hacia Earn.

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

Restricciones:

Solo mainnet. Las reglas earn se rechazan en testnet.
Cada activo de source.assets debe estar soportado por el proveedor elegido en la blockchain de la wallet; de lo contrario la regla se rechaza al crearla.
rewardProvider y rewardType deben coincidir: fija es siempre regulated y aave es siempre defi.
Una regla no puede ser isGateway e isReward a la vez.

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

Las liquidaciones hacia Earn crean una transacción REWARD_DEPOSIT y emiten webhooks reward-deposit.*.

Las reglas earn basadas en saldo (useTransactionAmount: false) omiten una nueva liquidación mientras ya hay una pendiente o en proceso para la misma dirección y el mismo activo, porque esa liquidación en curso absorberá igualmente los fondos recién llegados. Las reglas earn basadas en monto (useTransactionAmount: true) nunca se omiten.

Opciones de configuración de la regla

Umbrales de monto

Monto mínimo: Solo liquidar cuando el monto supere este umbral
Monto máximo: Limitar el tamaño de cada liquidación individual
Acumulación: Con useTransactionAmount: false (el valor por defecto), la regla liquida todo el saldo del activo de origen en la dirección, de modo que los depósitos que individualmente quedaron por debajo de minAmount se recogen juntos en cuanto el saldo lo supera

Protección frente a slippage

Ilimitado: -1 (sin límite de slippage)
Conservador: 0,1 % - 0,5 % (impacto mínimo en el precio)
Moderado: 0,5 % - 1,0 % (enfoque equilibrado)
Agresivo: 1,0 % - 2,0 % (ejecución más rápida)

Antes de ejecutar, la liquidación obtiene una cotización y compara su slippage con su tolerancia. Si la cotización supera la tolerancia, la liquidación falla en lugar de ejecutarse a un precio peor.

Envíe siempre slippageTolerance de forma explícita en las reglas de swap. "-1" significa ilimitado, y un valor como "5" significa 5 %. Una tolerancia de "0" solo permite una liquidación con slippage exactamente cero, lo que rechaza prácticamente cualquier cotización real. Las reglas gateway y earn no utilizan la tolerancia de slippage.

Dirección de destino (Opcional)

El campo destination.address es opcional en las reglas swap, gateway y earn. Cuando no se proporciona, el sistema utiliza una lógica de fallback inteligente para determinar la dirección destinataria:

Escenario	Comportamiento de fallback
Dirección explícita proporcionada	Utiliza la dirección especificada
Liquidación en la misma cadena	Utiliza la dirección de depósito (dirección de origen)
Cross-chain entre EVM	Utiliza la misma dirección en la cadena de destino
Cross-chain (destino no EVM)	Utiliza la dirección de la master wallet en la cadena de destino

Para la mayoría de casos de uso, puede omitir la dirección de destino y dejar que el sistema enrute automáticamente los fondos a la dirección adecuada según el tipo de liquidación.

Las reglas withdraw son la excepción: requieren una destination.address explícita, y destination.blockchain debe ser la misma blockchain que la de origen. destination.blockchain y destination.asset son siempre obligatorios, en cualquier tipo de regla.

Preferencias de ejecución

Fastest: Prioriza la velocidad sobre el costo
Cheapest: Optimiza para las comisiones más bajas
Recommended: Equilibra velocidad y costo con confiabilidad
No Slippage: Ejecutar solo cuando no haya desviación de precio

Jerarquía y precedencia de reglas

Cómo se aplican las reglas

Concepto clave: Por defecto, las reglas creadas en una master wallet se aplican a la master wallet y a todas las child addresses bajo ella. Una regla en una child address tiene precedencia sobre las reglas de la master wallet para el depósito con el que coincide.

Nivel de regla	Alcance	Comportamiento
Reglas de Master Wallet	La master wallet, más las child addresses seleccionadas por el ajuste `inheritance` de la regla (todas ellas por defecto)	Reglas por defecto para la jerarquía de la wallet
Reglas de Child Address	Únicamente esa dirección específica	Tienen precedencia sobre las reglas de la master wallet para cualquier depósito con el que coincidan

Orden de aplicación de las reglas

La precedencia se evalúa por depósito, no por dirección:

Buscar una regla coincidente en la child address. Una regla coincide cuando está activa y sus campos source.assets y source.blockchain cubren el depósito.
Recurrir a las reglas de la master wallet. Una regla de la master wallet solo se considera entonces si su ajuste inheritance le permite aplicarse a la dirección que recibió el depósito.
Sin coincidencia en ninguno de los niveles: no se realiza ninguna liquidación automática.

Que una child address tenga algunas reglas no desactiva las reglas de la master wallet para esa dirección. Si ninguna de las reglas de la child address coincide con el activo y la cadena depositados, se evalúan a continuación las reglas de la master wallet. Para impedir que una regla de la master wallet alcance una dirección, defina explícitamente el inheritance de esa regla, como se explica más abajo.

Herencia por regla

Cada regla de la master wallet controla a qué child addresses se propaga mediante el objeto opcional inheritance:

`mode`	La regla se aplica a
`all_children`	La master wallet y todas las child addresses
`master_only`	Únicamente la master wallet; esta regla ignora los depósitos en las child addresses
`selected_children`	La master wallet más las direcciones concretas indicadas en `childAddressIds`

Omitir inheritance por completo conserva el comportamiento original y 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 '{
    "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"
    }
}'

Reglas para selected_children:

childAddressIds debe estar presente y no vacío; de lo contrario la solicitud falla con At least one child address must be selected.
Cada ID debe ser una dirección activa que pertenezca a su negocio en la misma red.
Las direcciones deben coincidir con la familia de cadenas de la wallet. Una regla en una wallet no EVM (por ejemplo Tron, Solana o Stellar) solo acepta direcciones de esa misma cadena; una regla en una wallet EVM acepta cualquier dirección EVM. Una discrepancia falla con One or more selected child addresses are not valid for this chain or are inactive.

inheritance solo existe en las reglas de la master wallet. Una regla creada directamente en una child address no tiene nada a lo que propagarse, por lo que el campo se ignora y nunca se guarda ahí.

Reglas específicas por blockchain

Importante: Las reglas están aisladas y vinculadas a cada blockchain. Una regla configurada para una blockchain (por ejemplo, Ethereum) NO afectará a depósitos en otra blockchain (por ejemplo, Base u Optimism).

Esto significa que:

Debe crear reglas separadas para cada blockchain de origen que desee liquidar automáticamente
Una regla para “USDC en Ethereum” no se activará para “USDC en Base”
Esto permite un control granular del comportamiento de liquidación por cadena

Ejemplo: Si desea liquidar automáticamente depósitos de USDC tanto desde Ethereum como desde Base hacia Optimism, necesita dos reglas separadas:

Regla para Ethereum USDC → Optimism USDC
Regla para Base USDC → Optimism USDC

Casos de uso para cada nivel

Reglas de Master Wallet

Estrategia consistente: Mismo comportamiento de liquidación en todas las child addresses
Gestión simplificada: Un único lugar para configurar el comportamiento por defecto
Operaciones masivas: Aplicar reglas a varias direcciones a la vez
Estandarización: Garantizar el cumplimiento y la consistencia

Reglas de Child Address

Pruebas: Probar diferentes estrategias de liquidación en direcciones específicas
Requisitos personalizados: Necesidades de liquidación específicas por dirección
Anular valores por defecto: Modificar el comportamiento para casos de uso particulares
Control granular: Ajustar con precisión la liquidación para direcciones específicas

Creación de reglas de Liquidación Automática

Mediante el panel

Diríjase a la sección Auto Settlements de su wallet
Haga clic en “Create New Rule”
Configure los parámetros de la regla
Establezca los umbrales de monto y la tolerancia de slippage
Elija los activos/cadenas de origen y destino
Guarde y active la regla

Mediante la API

Cree reglas de liquidación de forma programática usando la 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"
    }
}'

En este ejemplo, slippageTolerance se establece en -1 para slippage ilimitado, y se omite destination.address. El sistema utilizará automáticamente la lógica de fallback inteligente para determinar la dirección destinataria.

Con dirección de destino explícita:

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 reglas entre wallets

Las reglas son por blockchain, así que desplegar una misma estrategia en todas las cadenas en las que opera implicaría recrear la misma regla muchas veces. El endpoint de copia lo hace en una sola llamada:

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"
    ]
}'

Las reglas se envían por valor, no por ID, de modo que el origen puede ser las reglas de una master wallet, las de una child address o un payload que usted mismo componga. El campo source.blockchain de cada regla se reescribe con la blockchain de la wallet de destino antes de guardarla.

El éxito parcial es normal

La llamada devuelve 200 incluso cuando se omiten algunas reglas o fallan algunas wallets. Lea siempre la respuesta en lugar de fiarse del código de estado:

{
  "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`	La regla se escribió en esa wallet
`skipped`	La regla se rechazó solo para esa wallet: el activo no está habilitado allí, ya existe una regla que cubre ese activo en esa cadena, o la regla no superó la validación para esa wallet
`failed`	No se pudo escribir la wallet completa, por ejemplo porque no existe o está inactiva en esta red

Cada wallet de destino se bloquea y se escribe en su propia transacción, de modo que un fallo en una nunca deja otra escrita a medias. Aplicar al menos una regla a una wallet también activa la liquidación automática en esa wallet.

La solicitud en sí falla con 400 cuando el array rules está mal formado, cuando rules o targetWalletIds está vacío, o cuando la única wallet indicada como destino es la wallet de origen (el origen siempre se elimina de la lista de destinos).

Casos de uso

Gestión de tesorería

Conversión flexible de activos: Convertir a cualquier activo preferido (USDC, ETH, USDT, etc.)
Operaciones cross-chain: Mantener saldos en múltiples redes
Consolidación automatizada: Sin intervención manual
Estrategia multiactivo: Compatible con diversas preferencias y estrategias de activos

Operaciones empresariales

Procesamiento de pagos: Liquidar automáticamente los pagos entrantes a los activos preferidos
Gestión de ingresos: Convertir varias stablecoins al activo de destino elegido
Mitigación de riesgos: Aplicar protección frente a slippage automáticamente
Diversificación de activos: Mantener asignaciones de activos objetivo automáticamente

Integración con DeFi

Yield farming: Liquidar automáticamente las recompensas al activo preferido
Gestión de liquidez: Consolidar recompensas y comisiones de LP
Reequilibrio de cartera: Mantener asignaciones objetivo de activos

Mejores prácticas

Configuración de reglas

Empiece de forma conservadora: Comience con baja tolerancia de slippage
Supervise el rendimiento: Realice un seguimiento de las tasas de éxito de las liquidaciones
Ajuste gradualmente: Afine las reglas según las condiciones del mercado
Pruebe en testnet: Valide las reglas antes del despliegue en mainnet

Gestión de riesgos

Límites de slippage: Establezca niveles de tolerancia adecuados
Topes de monto: Limite el tamaño máximo de las liquidaciones
Selección de red: Elija cadenas de destino confiables
Reglas de respaldo: Cree opciones de liquidación alternativas

Eficiencia operativa

Acumulación: Deje useTransactionAmount en false para que los depósitos pequeños se liquiden juntos en cuanto el saldo supere minAmount
Optimización temporal: Considere los patrones de congestión de la red
Análisis de costos: Equilibre las preferencias de velocidad vs. costo
Monitoreo: Configure alertas para liquidaciones fallidas

Monitoreo y alertas

Monitoreo desde el panel

Estado de las reglas: Indicadores de regla activa/inactiva
Historial de liquidaciones: Seguimiento de liquidaciones exitosas y fallidas
Métricas de rendimiento: Tasas de éxito y tiempos de ejecución
Saldos de activos: Supervisar el crecimiento del saldo unificado

Notificaciones por webhook

Las liquidaciones automáticas activan eventos de webhook cuando se ejecutan las liquidaciones. La familia de eventos que recibe depende del tipo de liquidación que se ejecutó:

Tipo de liquidación	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`

Una regla gateway en una cadena que no es elegible para Gateway pasa a ejecutarse como swap, por lo que emite eventos swap.* en lugar de gateway-deposit.*. Suscríbase a ambos si utiliza reglas de gateway fuera de las cadenas admitidas por Gateway.

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

Identificación de transacciones de liquidación automática

La mejor manera de identificar las transacciones de liquidación automática es revisando el campo metadata. Según la acción, el metadata contendrá una de estas claves:

Clave de metadata	Descripción
`swapAutoSettlement`	Presente cuando la liquidación automática activó una operación de swap
`gatewayAutoSettlement`	Presente cuando la liquidación automática activó una operación de Gateway
`withdrawAutoSettlement`	Presente cuando la liquidación automática activó una operación de retiro
`rewardAutoSettlement`	Presente cuando la liquidación automática activó un depósito en Earn

Los objetos de swap, gateway y retiro contienen:

Campo	Descripción
`rule`	Payload completo de la regla de liquidación automática que activó esta transacción
`settleAmount`	Monto liquidado conforme a la regla

rewardAutoSettlement tiene una forma distinta: lleva el ID de la regla en lugar de la regla completa:

Campo	Descripción
`ruleId`	ID de la regla earn que activó este depósito
`settleAmount`	Monto liquidado conforme a la regla
`sourceTransactionId`	ID de la transacción de depósito que activó la liquidación

Cuando alguna de estas claves de metadata está presente, la transacción fue activada por una regla de liquidación automática. En las liquidaciones de swap, gateway y retiro el campo rule contiene la configuración completa de la regla, no solo un ID; en las liquidaciones earn, busque la regla mediante ruleId.

Campos clave de los datos del webhook

Campo	Descripción
`toAmount`	Monto final recibido tras el swap (considerando comisiones y slippage)
`rate`	Tasa de cambio utilizada para el swap
`toAsset`	Detalles del activo de destino (USDT en este ejemplo)
`toBlockchain`	Red blockchain de destino (Optimism en este ejemplo)
`toWallet`	Wallet de destino que recibió los activos convertidos
`assetSwept`	Si los activos originales fueron barridos tras la conversión

Referencia de la API

Endpoints

Liquidaciones Automáticas de Master Wallet

Endpoint	Método	Descripción	Referencia de la API
`/v1/wallets/{walletId}/auto-settlements/rules`	GET	Listar todas las reglas de liquidación de la master wallet	Get All Rules
`/v1/wallets/{walletId}/auto-settlements/rules`	POST	Crear nueva regla de liquidación para la master wallet	Create Rule
`/v1/wallets/{walletId}/auto-settlements/rules/copy`	POST	Copiar reglas de liquidación a otras master wallets	Copy Rules
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	GET	Obtener detalles de una regla específica de la master wallet	Get Rule
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	PATCH	Actualizar una regla existente de la master wallet	Update Rule
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	DELETE	Eliminar una regla de liquidación de la master wallet	Delete Rule
`/v1/wallets/{walletId}/auto-settlements`	GET	Obtener el historial de liquidaciones de la master wallet	Get Settlement
`/v1/wallets/{walletId}/auto-settlements`	PATCH	Actualizar la configuración de liquidación de la master wallet	Update Settlement

Liquidaciones Automáticas de Child Address

Endpoint	Método	Descripción	Referencia de la API
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules`	GET	Listar todas las reglas de liquidación para una dirección específica	Get All Rules
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules`	POST	Crear nueva regla de liquidación para una dirección específica	Create Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	GET	Obtener detalles de la regla de una dirección específica	Get Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	PATCH	Actualizar una regla de dirección existente	Update Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	DELETE	Eliminar la regla de liquidación de la dirección	Delete Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`	GET	Obtener el historial de liquidaciones de la dirección	Get Settlement
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`	PATCH	Actualizar la configuración de liquidación de la dirección	Update Settlement

No existe un endpoint de copia para las child addresses: la copia siempre tiene como destino master wallets, aunque las reglas que copie pueden provenir de una child address.

La semántica de actualización difiere según el nivel

Endpoint	Tratamiento del body
`PATCH /wallets/{walletId}/auto-settlements/rules/{id}`	Fusión parcial. Envíe solo los campos que va a cambiar; el resto conserva su valor actual. Los objetos anidados como `source` y `destination` se reemplazan por completo, así que envíelos completos cuando los envíe
`PATCH /wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	Regla completa. `source` y `destination` son obligatorios, y cualquier campo opcional que omita se restablece a su valor por defecto: `order` a `RECOMMENDED`, `slippageTolerance` y `deductionPercentage` a `"0"`, `useTransactionAmount` a `false`, `isActive` a `true`, `source.minAmount` a `"0"` y `source.maxAmount` a `"-1"`

Lea primero la regla y envíe el objeto completo al actualizar una regla de child address. Enviar solo el campo que quiere cambiar restablecerá silenciosamente el resto de la regla a los valores por defecto.

En ambos casos la regla fusionada se vuelve a validar, por lo que una actualización puede rechazarse por un campo que usted no envió.

Parámetros de la regla

Parámetro	Tipo	Requerido	Descripción
`type`	string	No	Flujo de liquidación: `withdraw`, `swap`, `gateway` o `earn`. Envíelo en cada regla nueva
`name`	string	No	Nombre de la regla para identificación
`isActive`	boolean	No	Si la regla está habilitada. Por defecto `true`
`order`	string	No	Preferencia de enrutamiento (FASTEST/CHEAPEST/RECOMMENDED/NO_SLIPPAGE). Por defecto `RECOMMENDED`; se ignora en las reglas gateway y earn
`slippageTolerance`	string	No	Slippage máximo aceptable (%). Use `-1` para ilimitado. Envíelo explícitamente en las reglas de swap
`isGateway`	boolean	No	Enruta a través de Gateway de Circle. Obligatorio con `type: gateway`
`isReward`	boolean	No	Enruta hacia una posición de Earn. Obligatorio con `type: earn`. Solo mainnet
`rewardProvider`	string	Condicional	`fija` o `aave`. Obligatorio cuando `isReward` es `true`
`rewardType`	string	Condicional	`regulated` para `fija`, `defi` para `aave`. Obligatorio cuando `isReward` es `true`
`useTransactionAmount`	boolean	No	`false` (por defecto) liquida el saldo de la dirección; `true` liquida solo el depósito que activó la regla
`deductionPercentage`	string	No	Porcentaje retenido del monto liquidado. Por defecto `"0"`
`inheritance.mode`	string	No	`master_only`, `all_children` o `selected_children`. Solo en reglas de la master wallet
`inheritance.childAddressIds`	array	Condicional	Obligatorio y no vacío cuando el modo es `selected_children`
`source.assets`	array	Sí	Lista de activos de origen a liquidar automáticamente
`source.minAmount`	string	No	Monto mínimo para activar la liquidación. Por defecto `"0"`
`source.maxAmount`	string	No	Monto máximo por liquidación. Use `-1` para ilimitado (por defecto)
`source.blockchain`	string	No	Se ignora al crear: siempre se establece a la blockchain de la propia wallet
`destination.blockchain`	string	Sí	Red blockchain objetivo. Debe ser igual a la de origen en las reglas `withdraw`
`destination.asset`	string	Sí	Activo objetivo de la conversión. Se fuerza a USDC en las reglas gateway
`destination.address`	string	Condicional	Obligatorio en las reglas `withdraw`. En el resto es opcional: se utiliza la lógica de fallback inteligente (ver arriba)

Primeros pasos

1. Active las Liquidaciones Automáticas

Diríjase a la configuración de su wallet
Habilite la funcionalidad de liquidación automática
Configure las preferencias por defecto

2. Cree su primera regla

Empiece con una regla sencilla de USDT a ETH (o cualquier activo que prefiera)
Establezca una tolerancia de slippage conservadora
Elija su cadena y activo de destino preferidos

3. Pruebe y monitoree

Despliegue primero en testnet
Supervise las tasas de éxito de las liquidaciones
Ajuste los parámetros según sea necesario

4. Escale gradualmente

Añada reglas para activos adicionales
Implemente procesamiento por lotes
Optimice para su caso de uso

Soporte y recursos

Cómo obtener ayuda

Correo electrónico: [email protected]
Referencia de la API: Auto Settlement Rules
Documentación: Configuración de Gateway

Las liquidaciones automáticas son una forma poderosa de automatizar la gestión de su tesorería. Comience con reglas sencillas y añada complejidad gradualmente a medida que se familiarice con el sistema.

​Requisitos previos

​Cómo funciona

Gestión de reglas

Conversión de activos

Multicadena

Gestión de riesgos

​Cómo funcionan las Liquidaciones Automáticas

​1. Creación de reglas

​2. Detección de depósitos

​3. Conversión de activos

​4. Unificación de saldos

​Tipos de liquidación

​Reglas de validación por tipo

​Las reglas de gateway pueden pasar a swap

​Reglas de Liquidación Automática

​Componentes de la regla

​Cuánto se liquida

​Reglas de liquidación hacia Earn

​Opciones de configuración de la regla

​Umbrales de monto

​Protección frente a slippage

​Dirección de destino (Opcional)

​Preferencias de ejecución

​Jerarquía y precedencia de reglas

​Cómo se aplican las reglas

​Orden de aplicación de las reglas

​Herencia por regla

​Reglas específicas por blockchain

​Casos de uso para cada nivel

​Reglas de Master Wallet

​Reglas de Child Address

​Creación de reglas de Liquidación Automática

​Mediante el panel

​Mediante la API

​Copiar reglas entre wallets

​El éxito parcial es normal

​Casos de uso

​Gestión de tesorería

​Operaciones empresariales

​Integración con DeFi

​Mejores prácticas

​Configuración de reglas

​Gestión de riesgos

​Eficiencia operativa

​Monitoreo y alertas

​Monitoreo desde el panel

​Notificaciones por webhook

​Ejemplo de payload de webhook

​Identificación de transacciones de liquidación automática

​Campos clave de los datos del webhook

​Referencia de la API

​Endpoints

​Liquidaciones Automáticas de Master Wallet

​Liquidaciones Automáticas de Child Address

​La semántica de actualización difiere según el nivel

​Parámetros de la regla

​Primeros pasos

​1. Active las Liquidaciones Automáticas

​2. Cree su primera regla

​3. Pruebe y monitoree

​4. Escale gradualmente

​Soporte y recursos

​Cómo obtener ayuda

Requisitos previos

Cómo funciona

Cómo funcionan las Liquidaciones Automáticas

1. Creación de reglas

2. Detección de depósitos

3. Conversión de activos

4. Unificación de saldos

Tipos de liquidación

Reglas de validación por tipo

Las reglas de gateway pueden pasar a swap

Reglas de Liquidación Automática

Componentes de la regla

Cuánto se liquida

Reglas de liquidación hacia Earn

Opciones de configuración de la regla

Umbrales de monto

Protección frente a slippage

Dirección de destino (Opcional)

Preferencias de ejecución

Jerarquía y precedencia de reglas

Cómo se aplican las reglas

Orden de aplicación de las reglas

Herencia por regla

Reglas específicas por blockchain

Casos de uso para cada nivel

Reglas de Master Wallet

Reglas de Child Address

Creación de reglas de Liquidación Automática

Mediante el panel

Mediante la API

Copiar reglas entre wallets

El éxito parcial es normal

Casos de uso

Gestión de tesorería

Operaciones empresariales

Integración con DeFi

Mejores prácticas

Configuración de reglas

Gestión de riesgos

Eficiencia operativa

Monitoreo y alertas

Monitoreo desde el panel

Notificaciones por webhook

Ejemplo de payload de webhook

Identificación de transacciones de liquidación automática

Campos clave de los datos del webhook

Referencia de la API

Endpoints

Liquidaciones Automáticas de Master Wallet

Liquidaciones Automáticas de Child Address

La semántica de actualización difiere según el nivel

Parámetros de la regla

Primeros pasos

1. Active las Liquidaciones Automáticas

2. Cree su primera regla

3. Pruebe y monitoree

4. Escale gradualmente

Soporte y recursos

Cómo obtener ayuda