Docs menu

Operate

Keepers

Call a contract function on a schedule or when a contract emits an event, through a managed signer, without running an app for it.

Explain it

A keeper does a blockchain job on a schedule or when something happens on chain, with no app to run: harvest a vault every hour, rebase when a price updates, credit a user when they deposit.

How to do it: in project settings, open Keepers, choose the contract and function to call, when to call it, and which of the project's managed wallets signs it.

The wallet's own limits (which contracts, how much per day) still apply to everything a keeper sends.

A keeper is an on-chain job with no app behind it: harvest a vault every hour, rebase when an oracle updates, credit a user when they deposit. It calls one contract function through one of the project's managed signers, on a cron schedule or when a contract emits an event, optionally only when a view function says it's needed.

The signer's policy still applies to every transaction a keeper sends: chains, contracts, functions, value per transaction and per day, and rate. Make the signer's policy as narrow as the job. See On-chain tools for signers.

Create one

In project settings, Keepers, choose Add a keeper. With the API:

API
POST /v1/projects/:id/keepers
{"name": "harvest", "signerId": "sgn_…", "chainId": 8453, "to": "0xVault…",
 "fn": "function harvest()", "schedule": "0 * * * *",
 "condition": {"fn": "function shouldHarvest() view returns (bool)"}}
FieldMeaning
fnThe function, as a human-readable signature
argsIts arguments; can use {{now}} (unix seconds), {{block}}, and for event keepers {{event.<arg>}}, {{event.txHash}}, {{event.blockNumber}}
valueWei to send with it (default 0)
scheduleCron, in UTC
eventOr: {"address", "abi"} to run when that contract emits that event
conditionOptional view call; the keeper only sends when it returns true (or a non-zero number)

CLI checks the function, the arguments and the schedule when you create it, so a typo fails straight away rather than at 3am.

Run on an event

JSON
{"name": "credit", "signerId": "sgn_…", "chainId": 8453, "to": "0xRewards…",
 "fn": "function credit(address user, uint256 amount)", "args": ["{{event.user}}", "{{event.amount}}"],
 "event": {"address": "0xVault…", "abi": "event Deposit(address indexed user, uint256 amount)"}}

Each new event runs the keeper once, at most five times per check (about every 30 seconds). If more arrive at once, the rest are logged as skipped, so a burst of events never turns into a burst of transactions.

Watch it work

Every run is logged: sent (with the transaction hash), skipped (the condition said no, with what it returned) or failed (with why, for example the signer's policy refusing it). Open Runs on a keeper, or GET /v1/keepers/:id. Run now (POST /v1/keepers/:id/run) runs it once immediately; Pause stops it without deleting it.

Gas

Transactions are paid from the signer's own address, so keep it funded with the chain's gas token. The signer's daily value limit caps what any keeper can send with its calls.