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
Mechanics
How one pass works
- Discover. The bot reads the vault list from the protocol registry, then every
Borrowedevent since the deployment block. Borrowers are cached in a state file, so later passes only scan new blocks. - 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. - Liquidate (only with
EXECUTE=1). It approves exactly the capital needed, simulatesliquidatePartialin 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
| Value | Base Sepolia |
|---|---|
| Chain id | 84532 |
| Public RPC | https://sepolia.base.org |
| Protocol registry | 0x81dEe1...afD4280x81dEe1B70a19C752c813BE537BCCa440CCafD428 |
| Deployment block | 47408113 |
| USDC vault | 0xafbd36...36A2820xafbd36597603bE94b89AEed91f18ba7e5f36A282 |
| WETH vault | 0x0a4256...0d87b90x0a425605Dd1aE80528De2AA5007e46aA410d87b9 |
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 installThen 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 -- --onceThe first scan is long on the public RPC
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 startMAX_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
| Variable | Use | Description |
|---|---|---|
| RPC_URL | Required | JSON-RPC endpoint of the CantorFi network. |
| PROTOCOL_ADDRESS | Required | CantorFiProtocol registry: the bot lists every vault from it. |
| FROM_BLOCK | Required | Protocol deployment block, where the borrower scan starts. |
| CHAIN_ID | Recommended | Expected chain id; the bot stops on any other network. |
| LIQUIDATOR_PRIVATE_KEY | Execution | Your own wallet. It holds the repayment capital and the gas. Never shared. |
| EXECUTE | Execution | Set to 1 to send transactions. Without it the bot only reads and reports. |
| MAX_REPAY | Optional | Capital cap per liquidation, in the vault token (default: whole balance). |
| MIN_PROFIT | Optional | Minimum profit per liquidation, in the vault token (default 0). |
| INTERVAL_SECONDS | Optional | Delay between passes in watch mode (default 30). |
| CONFIRMATIONS / REORG_DEPTH | Optional | Blocks behind head, and blocks rescanned each pass (defaults 2 and 64). |
| LOG_RANGE | Optional | Blocks per eth_getLogs request (default 2000, halved automatically if the RPC refuses). |
| STATE_FILE | Optional | Borrower 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_IDdoes 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_pausedand sends nothing.
Provided as-is
MIT licence
Source files
Two short files, readable in full before you run anything:
The protocol side is described in the developer documentation.