> For the complete documentation index, see [llms.txt](https://docs.usegimbal.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usegimbal.app/mechanics/health-and-auctions.md).

# Health factor, warnings and the collateral auction

The health factor, the descending-price sale run by CollateralAuction, and the rules for closed markets and sequencer outages.

## Measuring health

`healthFactor(loanId)` on the desk returns:

```
HF = collateralValue × liquidationLtvBps / 10_000 / debt
```

* `collateralValue`: the escrowed amount times the `PriceSentinel` quote, in USDG.
* `liquidationLtvBps`: the tier's liquidation LTV, not the max LTV used at origination, less the closed-market haircut when the quote is from a closed session or stale.
* `debt`: principal plus interest owed, across every slice, to the second.

Two thresholds:

| Line        | Health factor | What follows                                                                                           |
| ----------- | ------------- | ------------------------------------------------------------------------------------------------------ |
| Warning     | below 1.10    | Keepers and the platform alert the borrower; the fixes are a collateral top-up or a partial repayment. |
| Liquidation | below 1.00    | `startAuction(loanId)` can be called by any address.                                                   |

A loan can also be auctioned at any health factor when it is Defaulted, meaning its rollover auction failed, or when it is Active and past maturity plus the 24-hour grace window.

## Opening an auction

`startAuction` is permissionless; the caller becomes the keeper. It refreshes the price through `PriceSentinel`, recording a move-cap checkpoint, confirms the loan qualifies, moves it to Liquidating (cancelling any running rollover), splits off opted-out slices in a closed session, settles in-kind slices, and then either finalizes with zero proceeds if nothing is left to sell or records the price schedule and emits `AuctionStarted`. A paused token, a sequencer inside its grace period, a feed gone stale during trading hours, or the liquidations pause all abort the call.

## The price schedule

| Parameter                          | Default                  | `PolicyBoard` setting    |
| ---------------------------------- | ------------------------ | ------------------------ |
| Opening price                      | quote × 1.03             | `startPremiumBps` = 300  |
| Floor, regular or extended session | quote × 0.70             | `floorBpsRegular` = 7000 |
| Floor, closed session              | quote × 0.85             | `floorBpsClosed` = 8500  |
| Window                             | 45 minutes, linear       | `duration`               |
| Target                             | debt plus the 3% penalty | `penaltyBps` = 300       |

`currentPrice(loanId)` descends to the floor across the window and holds there until someone buys or restarts.

### Buying

`buy(loanId, collateralAmount, streamReport)` needs the LIQUIDATOR role. Buyers pay the desk in USDG and take collateral out of escrow at the current price, in one purchase or several. The purchase is clipped twice: to the collateral still in escrow, and to the amount whose cost covers what remains of the target, so an auction never collects more than debt plus penalty. Where the token has a Data Streams adapter, the call must carry a signed report, verified by the sentinel before the sale; the price still comes from the schedule, which Chainlink Data Feeds drive in every case. It closes, and the desk finalizes, when proceeds reach the target or the escrow empties.

### Restarting

An auction whose window runs out short of target can be re-priced by anyone through `restart(loanId)`: start, floor, target and window are rebuilt from a fresh quote, collected proceeds carry over, and the original keeper keeps the keeper share. The liquidations pause halts `buy` and `restart` as well as opening; after it lifts, a restart rebuilds the schedule so nobody buys at prices set before the pause.

### Why an auction rather than a swap

Pooled lenders usually liquidate through an AMM, but single-name Stock Token pools are shallow and a forced sale moves the price by far more than the penalty. A descending quoted price lets anyone who has an opinion on fair value step in: the loan's own lenders, Robinhood's authorised participants, Morpho and Uniswap liquidity providers, or DEX arbitrageurs.

## The penalty and the waterfall

The penalty is 3% of debt (`penaltyBps` = 300). `keeperShareBps` = 3334 sends a third of it, one point, to the keeper. Of the two points left, `lenderPenaltyShareBps` = 5000 gives half to the lenders and the rest to the protocol.

`finalizeLiquidation` applies proceeds in this order, each tranche capped by what is left:

1. the keeper's point,
2. the lenders' claims, principal plus interest, shared by each slice's claim on the debt,
3. the lenders' penalty point,
4. the protocol's penalty point,
5. whatever remains, to the borrower.

The 10% interest share is charged on interest actually recovered and travels to the Treasury with the protocol's penalty. Unsold collateral returns to the borrower. The loan ends as Settled whether or not the lenders were made whole; a shortfall is borne by the slices pro rata, and by junior slices first once tranching arrives on the roadmap. No other loan is touched. `LiquidationFinalized` closes the record.

## Settlement in kind

A lender who set `selfLiquidate` on the offer takes collateral, valued at the checkpointed quote, rather than sale proceeds. `settleInKind` converts the slice's claim, principal plus interest owed, into tokens at that price, capped at the slice's principal-weighted share of the escrow so one lender's exit never eats into the other slices' collateral. No interest share is charged, anything above the cap is written off with the slice, and the slice leaves the auction before a token is sold. It suits lenders who prefer shares.

## Closed sessions

Equity markets shut overnight and over the weekend, and Monday can open far from Friday's close. Three rules apply while the session is reported closed, or `updatedAt` on the feed exceeds the session's staleness bound:

* **Haircut.** The haircut for the tier, 10 to 15 points, is taken off the origination ceiling and off the liquidation LTV in the health factor.
* **Higher floor.** Auctions can open, but the floor is 0.85 × quote rather than 0.70, so a weekend sale cannot become predatory.
* **Opt-out.** Setting `noClosedMarketLiquidation` keeps a lender's slice out of any auction that opens while the market is shut. Such slices, with their principal-weighted share of the collateral, move into a fresh Active loan for the same borrower on the same dates, and only the remaining slices go to sale. If every slice opted out, `startAuction` reverts with `NoClosedMarketLiquidation` until the market reopens.

## After a sequencer outage

`PriceSentinel` watches Chainlink's L2 Sequencer Uptime Feed. For one hour after the sequencer comes back (`sequencerGrace`), neither an auction nor an origination can open. Borrowers use that hour to add collateral, directly or with transactions sent through the L1 delayed inbox during the outage. See [When the sequencer stops](/risk/sequencer.md).

## The sentinel's checks come first

Nothing above runs on a quote `PriceSentinel` rejects:

* a zero or negative answer,
* an `updatedAt` older than the staleness bound for the current session,
* a checkpoint-to-checkpoint move beyond 25%, which halts the market pending manual review,
* a token whose issuer contract reports `oraclePaused()`, the signal for a corporate action in progress.

See [Pricing, sessions and the price checks](/risk/pricing.md).

## Worked example

Consider a Tier A position (70% liquidation LTV) with 250 NVDA in escrow and 20,000 USDG owed, interest included.

| NVDA price | Collateral value | HF     | Standing    |
| ---------- | ---------------- | ------ | ----------- |
| 176.40     | 44,100           | 1.54   | healthy     |
| 125.00     | 31,250           | 1.09   | warning     |
| 114.00     | 28,500           | 0.9975 | auctionable |

A keeper opens the auction at 117.42 (114 × 1.03) with a target of 20,600 and a floor of 79.80. At 113.00 a liquidator bids for all 250 tokens; the purchase is clipped to the target, so they pay 20,600 USDG for 182.30 NVDA. The auction closes: about 200 USDG goes to the keeper, 20,000 to the slices, about 200 to the lenders as their penalty point and about 200 to the Treasury. The unsold 67.70 NVDA return to the borrower.

Had the same loan been marked on a Saturday, the 10-point haircut would put the liquidation LTV at 60%. The loan then needs 33,333 of collateral value to stay above 1.0, becomes auctionable when NVDA prints 133.33, and the floor is held at 113.33.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.usegimbal.app/mechanics/health-and-auctions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.