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

# Keepers, liquidators and auction bidders

Running the open-source keeper, triggering and bidding in collateral auctions, and the limits the contracts place on both.

Independent operators do the protocol's station-keeping: they open auctions, accept rollovers for lenders who delegated the decision, and send borrowers their alerts. The keeper software is open source and every reward is paid on-chain.

## Roles and rewards

| Role        | What they do                                                                                          | What they earn                                                    |
| ----------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Keeper      | Calls `startAuction` on liquidatable loans; sends alerts; accepts rollovers for lenders who delegated | 1 point of the 3% liquidation penalty, for triggering the auction |
| Liquidator  | Buys collateral in a Dutch auction                                                                    | The difference between the auction price and fair value           |
| Arbitrageur | Buys in the auction and hedges or sells elsewhere                                                     | The same                                                          |

Triggering an auction is open to anyone. Receiving collateral, whether by buying it or taking it in kind, requires a `LIQUIDATOR` attestation.

## Running a keeper

The reference keeper is a TypeScript service. It reads the indexer and submits transactions with its own key.

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

The keeper is stateless apart from its key. Run as many as you like in parallel; the first `startAuction` to land takes the keeper share.

## Bidding

1. Listen for `AuctionStarted` events.
2. Read `currentPrice(loanId)`. The price falls linearly from `oracle × 1.03` to the floor over roughly 45 minutes.
3. Fetch a Chainlink Data Streams report for the collateral token.
4. Call `buy(loanId, collateralAmount, streamReport)`. The contract verifies the report on-chain and reverts if the stream price and the feed price differ by more than the tolerance. Partial buys are allowed.

When the market is closed, the floor is bounded at `oracle × 0.85`, and slices whose lenders set `noClosedMarketLiquidation` are excluded from the auction.

## Transaction ordering

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

## What a keeper cannot do

* Liquidate a healthy loan. `startAuction` reverts unless the on-chain conditions hold.
* Set the price. The curve and the floor are contract parameters.
* Act during the sequencer grace period that follows an outage.
* Take collateral 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.usefarlight.com/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.