dYdX Liquidation bot

In this tutorial we will create a dYdX liquidation bot. dYdX is a decentralized exchange on the Ethereum blockchain. It is a set of Solidity smart contracts that enables users to trade with no intermediaries. The exchange supports perpetual swaps, spot trading, and lending capabilities. To build a dYdX liquidation bot we will focus on their lending functionality.

liquidations on dYdX

dYdX supports liquidations on margin trading and perpetual swaps. In both cases one borrows an asset and must maintain a minimum amount of collateral. All borrowed assets must be over collateralized. Accounts are liquidated when the minimum amount of collateral is not maintained.

dYdX requires users to maintain a minimum of 115% collateral for borrow assets. When the minimum maintenance requirement is not met leveraged positions will be liquidated. If you are using isolated margin, assign a specific amount of an asset as margin, your liquidation point cannot be impacted because your collateral is locked. If you are using cross margin any deposits, withdrawals or trades can impact your collateralization level and liquidation level.

For example if you have $112 worth of assets posted as collateral and $100 worth of borrowed assets your account is under collateralized. You need at least 115% of posted collateral. Since you are under collateralized any liquidator can repay your $100 worth of borrowed assets in exchange for $105 worth of your collateral. This would close out your borrowed position and as a result would leave you with $5 less collateral.

dydx liquidation process and example

From the liquidators perspective a dYdX liquidation involves automatically repaying another accounts borrowed asset (principal plus interest). In return the liquidator receives the other accounts collateral plus a liquidation fee of 5%. Liquidations on dYdX have a reward of 5% spread on top of the current oracle prices for the assets being liquidated and used as collateral.

Participate in dYdX liquidations

Anyone can participate and liquidate an under collateralized account. The easiest way to get started as a liquidator is to operate the open source dYdX liquidation bot. This bot works for margin trading accounts and will automatically liquidate under collateralized and expired dYdX accounts.

dydx liquidation bot process flow

Liquidations on dYdX occurs between internal accounts, so you will need an already funded dYdX account to participate in liquidations. You can liquidate assets you do not have in your account provided you have another asset as collateral, which will just cause your dYdX account balance to go negative in that asset. Keep in mind that liquidations work on a first come first served basis.

Set up the dYdX liquidation bot

The process to setup the open source dYdX liquidation bot is straight forward. You will need a computer to run the bot (24/7) a node to connect to the blockchain, and a funded dYdX account.

dydx liquidation bot process flow using a node. Infura or geth

Fund your account on the dYdX exchange

In order to participate in liquidations on the dYdX exchange you need to have a funded dYdX exchange account.

  • Fund your dYdX account with WETH, DAI or USDC
  • You can chose to make a deposit any one token. You will still be able to participate in liquidation opportunities in the other tokens.
  • dYdX protocol will automatically take out a loan in your account to cover the token borrowed.
  • There is no maximum or minimum amount needed to participate in a liquidation. Opportunities will be limited if you do not have proper funding.

In order to participate in liquidations you need to fund your account in the dYdX smart contract. In order to add funds to your wallet follow the steps below:

  1. Fund your MetaMask wallet with DAI, WETH or USDC
  2. Go to https://margin.dydx.exchange/
  3. Select Deposit
  4. Choose your wallet
  5. Deposit your assets into your dYdX exchange account
  6. Finally, after your deposit is complete you are ready to participate in liquidations
dYdX Liquidation bot setup

Where should you operate your liquidation bot?

You can run your liquidation bot on any machine that is operating an Ethereum node and available 24 hours a day 7 days a week. A few options are as follows:

  1. Operate a Geth Node and your choice of hardware
  2. Quick Node and your choice of hardware
  3. Infra and your choice of hardware
  4. Alchemy Super node and your choice of hardware

For hardware you can use a local pc, Digital Ocean, Amazon Web Services, etc. If you plan to build a local server to run consider one of the following options:

Setup the liquidation bot

Once you have a node and hardware setup you are ready to install the dYdX liquidation bot on your machine. Before we begin make sure you have Docker installed on your machine. To download Docker visit their website.

Docker is an open source containerization platform. It allows developers to package applications into containers which are standard executable components. They combine application source code with the operating system libraries and dependencies required to run that code in any environment. It is very easy to use and makes deployments very simple. List of commonly used Docker commands.

Finally, after Docker is installed on your computer perform the following steps:

  • Navigate to the directory where you want to pull your Docker image
  • Copy and paste the commands below in your terminal window. These commands:
    • Pull the latest dYdX liquidation bot image from Docker Hub
    • Enter your node URL
    • Configures the liquidation bot with specific parameters
    • Starts the liquidation bot

In addition, a private key is required to sign a liquidation transaction sent to compound.

docker run \
  -e ETHEREUM_NODE_URL=https://eth-mainnet.alchemyapi.io/v2/YOUR_ALCHEMY_KEY \

Read here for a list of additional variables that you can configure for your dYdX liquidation bot.

Improve the bot

Lastly, after you learn the basics read the code in the dYdX liquidation bot repository to understand how it works. Fork the code and make your own improvements to give yourself a competitive advantage. https://github.com/dydxprotocol/liquidator


Blockchain Networks

Below is a list of EVM compatible Mainnet and Testnet blockchain networks. Each link contains network configuration, links to multiple faucets for test ETH and tokens, bridge details, and technical resources for each blockchain. Basically everything you need to test and deploy smart contracts or decentralized applications on each chain. For a list of popular Ethereum forums and chat applications click here.

Ethereum test network configuration and test ETH faucet information
Optimistic Ethereum Mainnet and Testnet configuration, bridge details, etc.
Polygon network Mainnet and Testnet configuration, faucets for test MATIC tokens, bridge details, etc.
Binance Smart Chain Mainnet and Testnet configuration, faucets for test BNB tokens, bridge details, etc.
Fanton networt Mainnet and Testnet configuration, faucets for test FTM tokens, bridge details, etc.
Kucoin Chain Mainnet and Testnet configuration, faucets for test KCS tokens, bridge details, etc.

Web3 Software Libraries

You can use the following libraries to interact with an EVM compatible blockchain.


Learn how to run a Geth node. Read getting started with Geth to run an Ethereum node.

Fix a transaction

How to fix a pending transaction stuck on Ethereum or EVM compatible chain

Next – Compound Finance liquidation bot