> For the complete documentation index, see [llms.txt](https://docs.ethosis.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ethosis.org/guides/keepers.md).

# Keepers and liquidators

Independent actors keep Ethosis moving: they open auctions, accept rollovers for lenders who have delegated the decision, and send borrowers alerts. The keeper software is open source and every incentive is paid on-chain.

## Who does what

| Role        | Activity                                                                                       | Reward                                                                 |
| ----------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Keeper      | Calls `startAuction` on liquidatable loans; sends alerts; accepts rollovers on lenders' behalf | 1 point of the 3% liquidation penalty, paid for triggering the auction |
| Liquidator  | Buys collateral in a Dutch auction                                                             | The gap between the auction price and fair value                       |
| Arbitrageur | Buys in the auction, then hedges or sells elsewhere                                            | The same                                                               |

Anyone can trigger an auction. Taking delivery of collateral, whether as a buyer or in kind, needs a `LIQUIDATOR` attestation.

## Operating a keeper

The reference implementation is a TypeScript service. It reads from the indexer and sends transactions using its own key.

1. Subscribe to the loan feed from the indexer.
2. For every active loan, compute the health factor from `PriceGate.quote()` using the current session.
3. When HF is under 1.10, send the borrower's registered alerts.
4. When HF is under 1.00 or the loan has Defaulted, and `sequencerGrace` is false, call `startAuction(loanId)`.
5. For lenders who have delegated rollover acceptance, monitor open rollover auctions and submit their pre-signed acceptance once the rate hits their limit.

Apart from its key, the keeper holds no state. Any number can run in parallel; whichever `startAuction` lands first collects the keeper share.

## Bidding in an auction

1. Listen for `AuctionStarted` events.
2. Read the current price from `currentPrice(loanId)`. It falls linearly from `oracle × 1.03` to the floor over roughly 45 minutes.
3. Get a Chainlink Data Streams report for the collateral token.
4. Call `buy(loanId, collateralAmount, streamReport)`. The contract checks the report on-chain and reverts if the stream price and the feed price diverge by more than the tolerance. You may buy part of the collateral.

While the market is closed the floor is bounded at `oracle × 0.85`, and slices whose lenders chose `noClosedMarketLiquidation` are left out of the auction.

## Transaction ordering

The Robinhood Chain sequencer orders transactions first-come-first-served. Should Timeboost be switched on in future, express-lane access might change who lands `startAuction` or a `buy` first. The auction design will be reviewed for that scenario and any resulting change published. See [Sequencer and chain risk](/risk/sequencer-and-chain.md).

## Limits on keepers

* A healthy loan cannot be liquidated: `startAuction` reverts unless the on-chain conditions are met.
* The price is not theirs to set: the curve and the floor are contract parameters.
* No action is possible during the sequencer grace period that follows an outage.
* Collateral cannot be received without an eligibility attestation.


---

# 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.ethosis.org/guides/keepers.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.