> 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/guides/keepers-and-bidders.md).

# Keepers, liquidators and bidders

What the reference keeper does, how to trigger and bid in a collateral auction, and the lines the contracts draw around both.

Gimbal has no privileged operator for auctions. Opening one, buying in one, accepting a delegated rollover and sending a borrower an alert are all done by independent operators running open-source software, and every reward they earn is paid on-chain by the contracts.

## Three jobs, three rewards

| Who         | Does what                                                                                                            | Is paid                                                             |
| ----------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Keeper      | Calls `startAuction` on loans that qualify, sends alerts, and submits rollover acceptances for lenders who delegated | About 1 point of the 3 percent liquidation penalty, for the trigger |
| Liquidator  | Buys collateral in the Dutch auction                                                                                 | Whatever fair value exceeds the auction price                       |
| Arbitrageur | Takes collateral in the auction, then hedges or sells it elsewhere                                                   | The same spread                                                     |

Anyone can trigger. Ending up with collateral, bought or received in kind, needs the `LIQUIDATOR` attestation.

## Running the reference keeper

Gimbal ships a reference keeper written in TypeScript, with one private key and no state beyond it. It reads the public indexer and sends its own transactions. Its loop:

1. Subscribe to the indexer's stream of loans.
2. For every active loan, work out the health factor from `PriceSentinel.quote()` for the current session.
3. Under 1.10, push the borrower's registered alerts.
4. Under 1.00, or once the loan is Defaulted, and only while the quote reports `sequencerGrace` as false, send `startAuction(loanId)`.
5. Where a lender delegated rollover acceptance, follow the open rollover auctions and file their pre-signed acceptance once the climbing rate meets the limit they set.

Run as many copies as you want. Whichever `startAuction` lands first is recorded as the keeper and collects the share.

## Bidding

1. Watch for `AuctionStarted`.
2. Call `currentPrice(loanId)`. The price begins at 1.03 times the oracle price and falls in a straight line to the floor across roughly 45 minutes. In the regular session the floor is 0.70 times oracle. If the window passes with the target unmet, the floor holds until someone buys or restarts the schedule from a fresh quote.
3. Obtain a Data Streams report from Chainlink for the token being sold.
4. Send `buy(loanId, collateralAmount, streamReport)`. On-chain the report is verified, and the call reverts when the stream and the feed disagree by more than the tolerance. You may take part of the collateral; the sale closes once proceeds reach the target or the escrow is empty.

Closed session: the floor is bounded at 0.85 times oracle, and slices flagged `noClosedMarketLiquidation` are carved out of the sale into a loan of their own before the auction opens.

## Who lands first

The Robinhood Chain sequencer takes transactions first come, first served. Should Timeboost be switched on in future, express-lane access could decide whose `startAuction` or `buy` is first in. That case will get a review of the auction design, with any change published. More in [When the sequencer stops](/risk/sequencer.md).

## Limits on a keeper

* No liquidating a healthy loan: unless the on-chain conditions are met, `startAuction` reverts.
* No choosing the price: curve and floor are `PolicyBoard` parameters.
* No action in the grace period after a sequencer outage.
* No receiving collateral without the eligibility attestation.
* No opening or buying while the guardian's liquidations pause is on.


---

# 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/guides/keepers-and-bidders.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.