CantorFi / Bots
Base SepoliaMIT
Bots and automations

Run your own CantorFi liquidation bot.

Liquidations on CantorFi are permissionless. This open-source bot finds unhealthy vault positions and, when you decide, repays them with your own capital for the liquidation bonus. No executor contract, no API key, no CantorFi key.

Read-only by defaultNode.js 20+One dependency: ethers

Why run it

Keep lending vaults solvent, receive the bonus

Each CantorFi vault lends one token against collateral in that same token. When a position's debt rises above the vault's liquidation threshold, anyone may repay part or all of the debt with liquidatePartial and receive the matching collateral plus the vault's liquidation bonus, minus the protocol share of that bonus.

The bot does exactly that, from your machine and your wallet. Started without a key, it only reads the chain and reports what could be liquidated and for how much.

There is no zero-capital liquidation

To liquidate, your wallet must hold the vault's token (USDC for the USDC vault, WETH for the WETH vault) and a little ETH for gas. The profit is paid in that same token.

Mechanics

How one pass works

  1. Discover. The bot reads the vault list from the protocol registry, then every Borrowed event since the deployment block. Borrowers are cached in a state file, so later passes only scan new blocks.
  2. Preview. For each borrower it calls previewLiquidation: the exact amount to repay, the collateral you receive, your profit and any bad debt, at the current block. A healthy position returns zero and is skipped.
  3. Liquidate (only with EXECUTE=1). It approves exactly the capital needed, simulates liquidatePartial in the latest block, sends it, then resets the approval to zero. A position already repaid or liquidated by someone else fails in simulation and costs nothing.

Copy these values

Network values · Base Sepolia

ValueBase Sepolia
Chain id84532
Public RPChttps://sepolia.base.org
Protocol registry0x81dEe1...afD428
Deployment block47408113
USDC vault0xafbd36...36A282
WETH vault0x0a4256...0d87b9

No key, nothing signed

Read-only quick start

Download the two published files and install the single dependency:

mkdir cantorfi-liquidation-bot && cd cantorfi-liquidation-bot
curl -fsSLO https://www.cantorfi.xyz/bots/liquidation/package.json
curl -fsSLO https://www.cantorfi.xyz/bots/liquidation/liquidation-bot.mjs
npm install

Then run one pass. The bot lists every vault and every position that can be liquidated now:

RPC_URL=https://sepolia.base.org \
PROTOCOL_ADDRESS=0x81dEe1B70a19C752c813BE537BCCa440CCafD428 \
FROM_BLOCK=47408113 \
CHAIN_ID=84532 \
npm start -- --once

The first scan is long on the public RPC

The public RPC limits each log query to 200 blocks, so reading the whole history since the deployment block takes several hours per vault. Progress is saved in the state file: the scan can be stopped and resumed, and later passes take seconds. An RPC that accepts wider log ranges needs far fewer requests.

Your wallet, your capital

Liquidate with your wallet

Use a wallet dedicated to the bot, holding only the capital you accept to use and some ETH for gas. Add the key and EXECUTE=1, then leave it watching:

RPC_URL=https://sepolia.base.org \
PROTOCOL_ADDRESS=0x81dEe1B70a19C752c813BE537BCCa440CCafD428 \
FROM_BLOCK=47408113 \
CHAIN_ID=84532 \
LIQUIDATOR_PRIVATE_KEY=<your dedicated wallet key> \
EXECUTE=1 \
MAX_REPAY=1000 \
MIN_PROFIT=1 \
npm start

MAX_REPAY caps the capital engaged per liquidation and MIN_PROFIT skips opportunities below your threshold (both in the vault token). The key is read locally by ethers and never leaves your machine.

Environment

Configuration

VariableUseDescription
RPC_URLRequiredJSON-RPC endpoint of the CantorFi network.
PROTOCOL_ADDRESSRequiredCantorFiProtocol registry: the bot lists every vault from it.
FROM_BLOCKRequiredProtocol deployment block, where the borrower scan starts.
CHAIN_IDRecommendedExpected chain id; the bot stops on any other network.
LIQUIDATOR_PRIVATE_KEYExecutionYour own wallet. It holds the repayment capital and the gas. Never shared.
EXECUTEExecutionSet to 1 to send transactions. Without it the bot only reads and reports.
MAX_REPAYOptionalCapital cap per liquidation, in the vault token (default: whole balance).
MIN_PROFITOptionalMinimum profit per liquidation, in the vault token (default 0).
INTERVAL_SECONDSOptionalDelay between passes in watch mode (default 30).
CONFIRMATIONS / REORG_DEPTHOptionalBlocks behind head, and blocks rescanned each pass (defaults 2 and 64).
LOG_RANGEOptionalBlocks per eth_getLogs request (default 2000, halved automatically if the RPC refuses).
STATE_FILEOptionalBorrower cache; keep it so restarts only scan new blocks.

--once runs a single pass and exits; without it the bot runs a pass every INTERVAL_SECONDS until Ctrl+C. --help prints this list.

Logs

Output

Every line is one JSON event, easy to pipe into your own alerts: started, vault, opportunity, skipped (with its reason), executed and error.

{"event":"started","chainId":"84532","mode":"read-only","liquidator":null}
{"event":"vault","vault":"0xafbd36597603bE94b89AEed91f18ba7e5f36A282","token":"USDC","borrowers":12,"liquidationsPaused":false}
{"event":"opportunity","borrower":"0x…","token":"USDC","repay":"850.000007","receive":"888.250007","profit":"38.25","badDebt":"0.0"}
{"event":"executed","borrower":"0x…","tx":"0x…","debtRepaid":"850.000027","collateralSeized":"892.500028"}

Before you run it

Safety and risks

  • Read-only unless you set both a key and EXECUTE=1.
  • Exact approval before each liquidation, reset to zero right after: no standing allowance.
  • Every transaction is simulated in the latest block before it is sent.
  • The bot stops if CHAIN_ID does not match the RPC network.
  • You pay the gas. Another liquidator may be faster; a failed simulation costs nothing, a mined transaction that loses a race can.
  • Liquidations can be paused by governance; the bot then reports liquidations_paused and sends nothing.

Provided as-is

This bot is provided as-is, without warranty. CantorFi is not responsible for gas fees, failed transactions, capital used or losses. Read the source before running it with funds.

MIT licence

Source files

Two short files, readable in full before you run anything:

The protocol side is described in the developer documentation.