Key Takeaways
- What it is: A record of when a lending contract's internal accounting judged a position undercollateralized, and of what was repaid and seized in response.
- The trigger: Health factor below 1, computed from threshold-weighted collateral over debt, with every price taken from the protocol oracle rather than a market.
- Three parameters decide the outcome: The liquidation threshold sets when, the close factor sets how much of the debt one call may clear, and the liquidation bonus sets what the liquidator takes.
- Why spikes cluster: Oracle feeds update discretely, so an entire band of positions becomes liquidatable in the same block when a feed refreshes.
- Main limitation: Realized liquidation volume is jointly determined by price, feed latency, liquidator capital, gas cost, and collateral market depth. Attributing it to price alone is always wrong.
- Practical rule: Read liquidatable value from current protocol state at a range of candidate prices rather than from realized history, and track bad debt separately.
Who This Guide Is For
This page is for anyone who has watched a liquidation chart spike and reached for a market explanation. Part of the spike is the market. A large part of it is the schedule on which a price feed happens to publish, and the two are separable. It is also for borrowers who read health factor as a percentage cushion, which it is not.
This is educational material and not individualized financial advice.
What Does DeFi Lending Metrics Measure?
A liquidation series measures state transitions inside a smart contract. It records the moment the contract's own accounting concluded that a borrower's collateral no longer covered their debt by the required margin, using prices the contract was told rather than prices that existed anywhere else.
A lending contract has no access to markets. It reads a number from an oracle contract, and that number is whatever a reporter last wrote there. If the reporter last wrote 1,750 and the market is at 1,690, the price inside the protocol is 1,750, and a position already past its trigger at market prices remains fully healthy in the contract's view.
Plain-language definition
A liquidation is a forced partial repayment of somebody's loan, performed by a third party paid a discount on the seized collateral for doing it. It is triggered by an arithmetic condition on posted prices, not by a decision anyone makes.
The three parameters that govern it
- Liquidation threshold. The share of a collateral asset's value that counts toward supporting debt. It is higher than the maximum loan-to-value used at origination, and the gap between them is the borrower's designed buffer.
- Close factor. The largest fraction of outstanding debt a single liquidation call may repay, commonly half, so a marginal breach does not close the whole position. Clearing a deeply unhealthy position therefore takes several sequential calls at several oracle prices.
- Liquidation bonus. The discount at which the liquidator receives collateral, paid out of the borrower's equity, which is what makes the mechanism run without any central actor. Most protocols route the whole discount to the liquidator, so it is rarely protocol revenue.
How Is DeFi Lending Metrics Constructed?
Liquidation series are built from contract event logs, and every protocol emits a different event with different fields and different units. The raw records live in the logs and traces tables described in Dune: Data Explorer and Raw Tables.
What a liquidation event contains
Typically the borrower address, the debt asset, the amount repaid in debt-token units, the collateral asset, the amount seized in collateral-token units, and the liquidator address. Whether the seized amount includes the bonus, whether protocol fee is netted out, and whether a partial versus full close is distinguished all vary by protocol.
The dollar conversion problem
Turning token units into a dollar figure needs a price at a timestamp, and there are two defensible choices. The protocol oracle price reproduces the accounting the contract performed. A market price at the block time measures what the seized collateral was worth to the liquidator. In a fast decline these differ, and the gap is precisely the liquidator's risk. Published liquidation volume rarely states which was used.
Records that inflate the series
- Multi-call transactions. One transaction can liquidate many positions, so counting transactions instead of calls undercounts.
- Flash-loan funded liquidations. The borrow and repayment inside the same transaction are not lending demand and should not appear in borrow volume.
- Self-liquidation. A borrower unwinding their own position cheaply, which is an exit rather than a distress event.
- Auction-based designs. Where collateral is sold through a descending-price auction rather than an instant fixed-discount seizure, the liquidation spans blocks and has no single execution price.
Formula and Measurement Logic
Health factor = sum over collateral of (oracle price x quantity x liquidation threshold) / sum over debt of (oracle price x quantity). Liquidatable when this falls below 1.
Every price in that expression is an oracle price. Almost all of the interesting behaviour of the metric comes from the properties of those price inputs.
How a push oracle actually behaves
A push feed writes a new value on-chain under two conditions: when the reference price has moved further than a deviation threshold since the last write, or when a heartbeat interval has elapsed with no write. The on-chain price is therefore a staircase. Within a deviation band the contract price is simply wrong by up to that band, indefinitely.
Pull-based and low-latency designs invert this. The price is supplied inside the transaction that consumes it, so a liquidator brings a fresh price with them. That changes what a liquidation timestamp means: under a push feed it dates the refresh, under a pull feed it dates the liquidator.
Why health factor is not a percentage cushion
Health factor scales linearly with collateral price when debt is stable-valued, so the tolerable decline is one minus its reciprocal. That is far smaller than a linear reading suggests near the trigger.
| Health factor | Tolerable collateral price decline |
|---|---|
| 1.05 | 4.8% |
| 1.25 | 20.0% |
| 1.50 | 33.3% |
| 2.00 | 50.0% |
| 3.00 | 66.7% |
Inputs that must be recorded
- Oracle design, deviation threshold, and heartbeat per collateral asset.
- Whether that asset is priced at market or by a redemption or exchange rate.
- Liquidation threshold, close factor, and bonus, which are per-asset and often per-market.
- Which price basis was used for dollar conversion.
- Whether flash-loan and self-liquidation records were separated.
How Should DeFi Lending Metrics Be Interpreted?
Treat realized liquidation volume as a joint measurement, never as a stress reading. It reflects the price move, the feed refresh schedule, the capital liquidators had available, the gas cost of competing, and the market depth in which seized collateral could be sold.
The better question
Instead of asking how much was liquidated, ask how much could be. Every position's trigger price is computable from current protocol state, so the total debt that becomes liquidatable at any candidate price is a state reading, available before anything happens and free of every confounder above.
What bad debt tells you that liquidations do not
Bad debt is the outcome: the amount of debt left standing with no collateral behind it, readable directly from protocol state. High liquidation volume with no bad debt means the system functioned as designed. Low liquidation volume with rising bad debt means liquidators declined to act, which is the failure mode worth detecting.
What a spike in a single block means
Usually that a feed refreshed. Positions whose trigger prices fall between the previous posted price and the new one all become eligible simultaneously, and liquidators clear them in the same block or the next. Measuring the offset between liquidations and oracle updates separates this mechanical clustering from genuine sequential deterioration.
Step-by-Step Workflow
- Identify the oracle design, deviation threshold, and heartbeat for each collateral asset.
- Note which assets are priced by redemption or exchange rate instead of market price.
- Pull liquidation events and separate calls from transactions.
- Exclude self-liquidations and mark flash-loan funded ones.
- Record which price basis the dollar conversion used.
- Measure the block offset between each liquidation and the preceding oracle update.
- Compute the liquidatable-value ladder from current state across a range of candidate prices.
- Read bad debt from state as positions whose collateral value sits below their debt.
- Check collateral market depth, since the bonus is only collectable if the asset can be sold.
- Report volume, ladder, and bad debt together.
Worked Hypothetical Scenario
A hypothetical position, with parameters chosen so every figure can be checked. This describes no real protocol or market.
A borrower deposits 100 units of a collateral asset priced by the oracle at 2,000, giving 200,000 of collateral value. The asset has a maximum loan-to-value of 75% and a liquidation threshold of 82.5%. The borrower takes 140,000 of stable-valued debt, a loan-to-value of 70% and therefore permitted.
| Quantity | Arithmetic | Result |
|---|---|---|
| Threshold-weighted collateral | 200,000 x 0.825 | 165,000 |
| Health factor at open | 165,000 / 140,000 | 1.179 |
| Tolerable price decline | 1 minus 140,000 / 165,000 | 15.15% |
| Trigger price | 140,000 / (100 x 0.825) | 1,696.97 |
The oracle step
Suppose the feed last posted 1,750 and the market falls quickly to 1,690, with the next write not yet landed on chain. At the posted price the health factor is 100 x 1,750 x 0.825 / 140,000, which is 144,375 / 140,000, or 1.031. The position is comfortably healthy in the contract's view. At the market price it is 139,425 / 140,000, or 0.996, already past the trigger. Nothing happens, because nothing can. When the feed does write 1,690, the health factor drops from 1.031 to 0.996 in a single step, and so does that of every other position whose trigger price sits between 1,690 and 1,750. They all become liquidatable in the same block.
The liquidation itself
With a close factor of 50% the liquidator repays 70,000 of the debt. With a 5% liquidation bonus they receive collateral worth 73,500, which at the oracle price of 1,690 is 43.49 units. The borrower is left with 56.51 units worth 95,502 and 70,000 of debt, giving a health factor of 95,502 x 0.825 / 70,000, or 1.126. One call restored the position from 0.996 to 1.126, which is exactly what the close factor is for. The liquidator's gross margin is the 3,500 difference, before gas and before whatever the collateral is worth by the time they sell it.
How bad debt appears
Now take the harder case: the price gaps from 1,750 to 1,300 with no intervening write, which a long heartbeat or a stalled feed permits. Collateral is worth 130,000 against 140,000 of debt, a health factor of 107,250 / 140,000, or 0.766. Liquidators can still act, but only while the collateral covers repayment plus bonus. At a 5% bonus the collateral can back at most 130,000 / 1.05 = 123,810 of repaid debt, leaving 16,190 with nothing behind it, or 11.6% of the original loan.
Raise the bonus to 15% to attract liquidators faster and the capacity falls to 130,000 / 1.15 = 113,043, leaving 26,957 unbacked, or 19.3%. The parameter that speeds up clearing in ordinary conditions enlarges the loss in severe ones, and a protocol that raises it after a stressful episode has traded one failure mode for another.
What Can Make the Interpretation Wrong?
- Assuming market prices trigger liquidations. Only the posted oracle price exists inside the contract, and it lags by design.
- Reading health factor as a linear cushion. The tolerable decline is one minus its reciprocal, which is far smaller than the number suggests near the trigger.
- Treating maximum loan-to-value as the danger level. The liquidation threshold is higher, and the gap is the intended buffer.
- Attributing a volume spike to market stress alone. Feed refresh timing manufactures clustering independently of how the price moved.
- Ignoring the collateral pricing basis. An asset priced by redemption rate does not respond to a market dislocation in that asset at all, while an otherwise identical protocol pricing it at market is fully exposed.
- Believing overcollateralization prevents loss. The bonus consumes collateral, so a residue of unbacked debt appears well before collateral reaches zero.
- Counting the bonus as protocol revenue. It usually goes to the liquidator, and it is paid out of borrower equity in either case.
- Using value locked as a risk measure. Exposure depends on utilization, collateral composition, and threshold settings, none of which a single locked-value figure carries. Utilization is covered in the lending utilization guide.
Cross-Network and Provider Comparison
The same protocol name on two chains is often not the same risk system, because the oracle configuration is chain-specific.
Deviation thresholds and heartbeats are set per feed and per deployment, so a collateral asset can refresh several times more often on one chain than another, and comparing liquidation volume across deployments partly compares feed budgets. Rollups add a further mechanism: when a sequencer stalls, no oracle write can land, and protocols that recognize this add a grace period after the sequencer restarts so that borrowers are not liquidated on the first stale-then-fresh price step. The presence or absence of that grace period changes the liquidation record without any difference in market conditions.
Protocol design differs just as much. Close factors range from partial to full, bonuses can be fixed or scale with how unhealthy a position is, isolated markets carry their own parameters, and auction-based systems replace the instant discount entirely. Between data providers, the reconciliation points are the price basis, whether calls or transactions are counted, and whether self-liquidations are stripped. See the on-chain data quality methodology guide.
Advanced Analytical Methods
Liquidatable-value ladder
For a grid of candidate prices, compute the total debt that would cross its trigger. This is derived from current positions and parameters, so it is available in advance and carries none of the confounders in realized volume.
Oracle lag distribution
Compare the posted price series against a reference market series and measure the distribution of the gap and of the interval between writes. The tail of that distribution is the risk: it is the size of the step that will eventually arrive all at once.
Clustering by block offset
Tag every liquidation with its distance in blocks from the preceding oracle write for the relevant asset. A distribution concentrated at zero and one confirms that the feed schedule, not sequential deterioration, is producing the observed bursts.
Exit depth for seized collateral
The bonus is only real if the collateral can be sold near the oracle price. Pairing position sizes against available market depth shows where a liquidation is profitable in principle and unprofitable in practice, which is the condition under which bad debt accumulates while liquidations do not appear.
Practical Checklist
- I know the oracle design, deviation threshold, and heartbeat for each collateral asset.
- I know which assets are priced by redemption rate rather than market price.
- I recorded liquidation threshold, close factor, and bonus per asset and per market.
- I separated liquidation calls from transactions.
- I excluded self-liquidations and marked flash-loan funded ones.
- I stated which price basis the dollar figures use.
- I measured block offset from the preceding oracle update.
- I computed the liquidatable-value ladder from current state.
- I read bad debt from state rather than inferring it from volume.
- I checked market depth for the seized collateral.
Frequently Asked Questions
Does a liquidation happen at the market price?
No. It happens at the price the protocol oracle has posted on-chain, which is the only price the contract can see. A push oracle updates when the price moves past a deviation threshold or when a heartbeat interval expires, so between updates the contract price is frozen while the market keeps moving. A position can be well past its trigger at market prices and remain untouchable until the feed refreshes.
What does a health factor of 1.5 actually mean?
It means collateral value can fall by 33.3 percent before the position becomes liquidatable, not 50 percent. Health factor is threshold-weighted collateral divided by debt, so the tolerable fall is one minus the reciprocal of the health factor. A health factor of 1.25 allows a 20 percent fall, 2.0 allows 50 percent, and 1.05 allows only 4.8 percent. Reading the number as a linear buffer overstates the cushion at every level.
How can bad debt arise if every loan is overcollateralized?
Because the bonus has to come from somewhere. Once total collateral value falls below the debt plus the bonus, the last slices of debt cannot be cleared profitably and liquidators stop acting. If collateral is worth 130,000 against 140,000 of debt with a 5 percent bonus, only 123,810 of debt can be repaid profitably and roughly 16,190 is left unbacked. A larger bonus makes that residue larger, not smaller.
Does a larger liquidation bonus make a protocol safer?
Only in mild conditions. A larger bonus attracts liquidators faster when collateral is still comfortably above debt, which reduces the time positions sit unhealthy. In a deep drawdown it does the opposite, because every unit of bonus is collateral that cannot be used to repay debt, so the unbacked residue grows. The parameter trades speed in ordinary conditions against loss size in severe ones.
What is the difference between a loan-to-value ratio and a liquidation threshold?
The loan-to-value ratio is what a borrower may draw against collateral at the moment they borrow. The liquidation threshold is the higher ratio at which the position becomes eligible for liquidation. The gap between them is deliberate headroom, so a position opened at the maximum permitted loan-to-value does not become liquidatable on the first small adverse move. Both are set per collateral asset, with volatile and illiquid assets given lower limits and narrower gaps.
Who performs a liquidation, and why do they compete?
Anyone can, because liquidation is an open function on the protocol that pays a bonus to whoever calls it. That design outsources the work to a competitive market of automated participants who monitor positions and act the moment one crosses its threshold. The competition is why liquidations execute within blocks of becoming eligible, and it is also why the profit is bid away through transaction fees and priority payments rather than accruing to any single participant.
How does oracle update frequency create liquidation risk?
A protocol acts on the price its oracle reports, not on the market price. If the oracle updates only when the price has moved beyond a threshold or after a set interval, a position can be economically underwater before the protocol can see it, and it can be liquidated on a reported price that no longer matches the market by the time the transaction executes. Both directions produce outcomes a borrower watching market prices would not have anticipated.
What is a partial liquidation in a lending protocol?
It is a design that permits a liquidator to repay only a portion of a borrower's debt and seize the matching collateral, rather than closing the whole position. The intent is to restore the position to health with less damage to the borrower and less collateral dumped into the market at once. It requires the remaining position to be viable afterwards, so protocols cap the share liquidatable in one transaction, and a position deteriorating fast can still be liquidated repeatedly in quick succession.
Why do liquidations cluster rather than arrive evenly?
Because borrowers concentrate at similar risk levels. Interfaces suggest similar loan-to-value settings, common strategies produce similar positions, and many participants borrow against the same few collateral assets. A price move that crosses one cohort's threshold crosses many, so liquidations arrive in bursts. The collateral sold then pushes the price further in the same direction, which can carry the next cohort across its threshold, which is the mechanism behind cascade events.
References
These sources should be reviewed during editorial verification. They support data structures and methods, not the hypothetical conclusion. Provider formulas, chain rules, and APIs can change, confirm current documentation before publication.
- Dune: Data Explorer and Raw Tables: Logs and traces, the raw records liquidation events are read from.
- Dune: Curated Data Overview: Normalized cross-protocol datasets, including the trade data used to assess exit depth for seized collateral.
- DefiLlama: Data Definitions: Value-locked, fee, and revenue definitions, needed to avoid treating the liquidation bonus as protocol revenue.
- DefiLlama: Methodology: How lending protocol aggregates are assembled across deployments.
- Etherscan API Documentation: Contract and token lookups for confirming decimals and market parameters.
- Ethereum.org: Technical Introduction: Contract accounts and state, the basis for reading protocol parameters and positions directly.