Skip to main content

Liquidation bot

Introduction

The Euler liquidation bot is an open-source tool for identifying and executing profitable liquidations within the Euler ecosystem. The source code is available in the GitHub repository.

This documentation provides an overview of how the bot works, its core components, and key areas for integration and optimisation.

How it works

1. Account monitoring​

  • The bot identifies accounts at risk of liquidation by scanning for AccountStatusCheck events emitted by the Euler Vault Controller (EVC) contract.
  • This event is triggered whenever a borrow position is created or modified, providing both the account and vault addresses.
  • The bot calculates account health scores using the accountLiquidity function implemented by vaults.
  • Accounts are added to a priority queue based on their health score and position size, with lower-health accounts checked more frequently.
  • On startup, the bot batches and processes historical EVC logs to catch up to the latest block, then continuously monitors for new events.

2. Liquidation opportunity detection​

  • When an account’s health score falls below 1, the bot simulates a liquidation across all collateral assets.
  • It requests a quote to swap collateral assets into debt assets and simulates a liquidation transaction on the Liquidator.sol contract.
  • The bot estimates gas costs and checks if the liquidation yields a net profit in ETH.
  • If profitable, the bot proceeds with the liquidation transaction.

3. Liquidation execution (Liquidator.sol)​

If a liquidation is deemed profitable, the bot:

  1. Calls liquidateSingleCollateral on the Liquidator contract.
  2. The Liquidator contract executes a batch of actions via the EVC:
    • Enables the borrow vault as a controller.
    • Enables the collateral vault for use.
    • Calls liquidate() on the borrower’s position in the borrow vault, seizing both collateral and debt positions.
    • Withdraws collateral from the vault to the swapper contract.
    • Uses a multicall to swap seized collateral, repay debt, and retrieve any leftover assets.
    • Transfers remaining collateral to the profit receiver.
    • Submits the batch to the EVC.
  3. A secondary flow (in development) will allow the bot to operate on behalf of another account, directly acquiring the debt position alongside collateral. This is particularly useful for permissioned real-world asset liquidations or scenarios where collateral should not be swapped into debt assets.

4. Swap quotation​

  • The bot currently leverages Euler’s Swap API meta-aggregator for obtaining swap quotes. Setup instructions are available here.
  • By default, the bot swaps all collateral into debt assets to repay the debt.
  • Future optimisations could implement partial swaps (swapping only the necessary amount), requiring binary search logic for venues that do not support exact output swaps.

5. Profit handling​

  • Any profit generated from liquidations is sent to a designated profit receiver address.
  • Profits are received in the overswapped debt asset (that is, surplus from liquidation).

6. Slack notifications​

  • The bot can send notifications for:
    • Unhealthy accounts detected
    • Successful liquidations
    • Errors or failures
  • Periodic reports on low-health accounts can be configured in config.yaml.
  • To enable Slack notifications, set up a Slack channel and provide a webhook URL in the .env file.

How to run the bot

Installation​

The bot can be run using Docker or locally via Python. It runs as a Flask app to expose endpoints for account health dashboards and metrics.

1. Environment setup​

Before starting, configure the .env file:

  1. Copy .env.example and update it with contract addresses, a private key, and API keys.
  2. Verify config.yaml to ensure contract addresses, chain configurations, and ABI paths are correct.

2. Running locally​

  1. Install dependencies and build contracts. Requires Foundry, which can be installed from the Foundry Book.
foundryup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cd redstone_script && npm install && cd ..
forge install && forge build
cd lib/evk-periphery && forge build && cd ../..
mkdir logs state
  1. Start the bot:
python flask run --port 8080
  1. Modify the port as needed in routes.py.

3. Running with Docker​

  1. Build and start the bot:
docker compose build --progress=plain && docker compose up
  1. Additional configuration may be needed for the Docker image to ensure a Python-enabled container.

Configuration

Required .env variables​

... (Table remains unchanged)

Deploying a custom liquidator contract

To deploy a new instance of Liquidator.sol, run:

forge script contracts/DeployLiquidator.sol --rpc-url $RPC_URL --broadcast --ffi -vvv --slow

Additional notes

Pull oracles​

  • Many Euler vaults use pull oracles, requiring price updates before executing actions.
  • The bot implements logic for Pyth and Redstone oracles in PullOracleHandler.

Swap API enhancements​

  • The bot uses Euler's Swap API, but additional swap venues can be integrated.
  • To add new venues, modify the Quoter class to check token pairs and route swaps accordingly.

Potential optimisations​

  • Store enabled collateral and controller states in the liquidator contract to reduce EVC calls.
  • Reduce RPC calls with smarter caching.
  • Improve gas pricing and slippage checks for better profitability estimation.
  • Construct liquidation batches off-chain to optimise execution.
  • Implement partial swaps to prevent overswapping.
  • Optimise oracle batch updates by skipping unused updates.
  • Improve transaction security using Flashbots bundling.