Using the app
The keeper
There is no keeper bot. Every interval the Hedera Schedule Service calls the market's tick(), which charges funding, liquidates underwater positions and books the next tick. The market pays for each run from its own HBAR reserve.
What a tick does#
- Accepts the call only if
msg.senderis the market itself, which is what a scheduled run looks like on Hedera. - Records the gas price it ran at.
- Accrues funding.
- Reads
PriceGuard. At anOkprice it checks up to 50 positions and liquidates the underwater ones for no reward; otherwise it emitsSweepSkipped. - Tries to refuel from the pool if fewer than 12 runs are left.
- Books the next tick one interval later.
The step-by-step version is in How it works. On the testnet deploy the interval is 1,800 s and each tick is booked with 3,000,000 gas.
The /keeper page#

| Panel | What it shows |
|---|---|
| Heartbeat | Next check in (countdown), Booked for, Checks run, Last check, Booked schedule, Market contract, Can pay next run |
| Fee reserve | In the reserve, Runs it can start, Held up front per run (runCostEstimate()), Gas price, Refuels itself |
| Keep it running | Fund and Revive the keeper buttons. Anyone can use both. |
| Prices the keeper trusts | Chainlink and Supra ages against the limit, how far apart they are, and whether the market is Open or Close-only |
| What the network did | Keeper events from the mirror node, newest first. A teal dot marks a run executed by the Schedule Service with no signer. |
| Audit log on HCS | The same events as messages on topic 0.0.10839050, each linked to its transaction |
What a run costs#
Hedera holds a scheduled run's whole gas limit up front and only starts the run if the payer can cover it. Afterwards it charges only the gas the run used.
held up front = gasLimit × gasPrice = 3,000,000 × 82 tinybar = 2.46 ℏ
charged = gas used × gasPrice| Tick | Did | Gas used | Charged |
|---|---|---|---|
| 1(opens in a new tab) | Funding, swept 2 positions, booked tick 2 | 1,618,265 | 1.359 ℏ |
| 2(opens in a new tab) | Funding, sweep, booked tick 3 | 1,580,037 | 1.327 ℏ |
| 3(opens in a new tab) | Funding, sweep, booked tick 4 | 1,584,087 | 1.315 ℏ |
| 4(opens in a new tab) | Also liquidated a 50x short | 2,385,537 | 1.980 ℏ |
- Per day at a 30-minute interval: 48 runs × about 1.36 ℏ ≈ 65 ℏ.
- A failed start (reserve below the hold) still costs 0.018 ℏ, and the chain stops.
- The gas limit sets the hold, the work sets the charge. Lowering the gas limit shrinks the hold but not the charge, and it must stay above 1,600,000. Each extra position checked costs about 20–30k gas.
- Gas price moves. It was 82 tinybar/gas in a probe and 84 at the final deploy's first tick. Every tick records it; the market's owner can correct it with
setGasPricebefore the first tick or while the chain is stopped.
runsLeft and canPayNextRun#
| View | Returns |
|---|---|
runCostEstimate() | gasLimit × gasPrice, in tinybars: the hold for one run |
runsLeft() | Reserve ÷ runCostEstimate(). Counts each run at the full hold, so it never overstates. |
canPayNextRun() | False when the reserve can't cover the next hold: Hedera would refuse to start the run. |
The testnet reserve started at 36 ℏ: runsLeft() said 14, but at about 1.36 ℏ actually charged it lasts about 25 runs, roughly 12 hours.
Fund and revive#
| Call | Who, when | What it does |
|---|---|---|
fund() | Anyone, any time | Adds HBAR to the reserve. Sending HBAR to the market does the same. The reserve can only pay for scheduled runs; nobody can withdraw it. |
revive() | Anyone, only when nothing is booked or the booked tick is more than 2 × interval overdue (1 hour on the testnet deploy) | Books a new tick one interval from now. Otherwise it reverts ScheduledKeeper__NotOverdue. |
A failed run breaks the chain silently, because nothing books the next one. If the reserve was the cause, fund() first, then revive(); the /keeper page tells you to top up before reviving. From the command line, yarn custos:revive:testnet runs the revive.
The first tick of the live deploy was booked with revive() (0xa1b7d249…fa1b71(opens in a new tab), schedule 0.0.10833097(opens in a new tab)).
When the price is stale#
If PriceGuard reports Stale or Deviated, the tick still runs, accrues funding and books the next tick, but liquidates nothing and emits SweepSkipped(status). Refuels also need an Ok price. Ticks 12 to 16 on the live deploy skipped their sweep while Chainlink's testnet feed was hours old; tick 18 (0x963bf611…ec8303(opens in a new tab)) then liquidated the other demo position once prices recovered.
The HCS audit log#

Every keeper event (Ticked, Swept, SweepSkipped, Liquidated, Refueled) is also written to Consensus Service topic 0.0.10839050(opens in a new tab). Its first 38 messages cover ticks 1 to 18: message 7 is the tick-4 liquidation and message 36 the tick-18 one.
- Off the critical path. Contracts can't write to HCS, so an off-chain script reads the events from the mirror node and submits one JSON message per event. If it stops, the network keeps ticking; the log just falls behind.
- Checkable. Each message carries the event's consensus timestamp, log index, transaction hash, run number and fields.
- Idempotent. The script reads the last logged event from the topic and starts after it. Only the operator's key can submit.
yarn workspace @sh/foundry hcs-log # or: yarn custos:hcs-log:testnet
yarn workspace @sh/foundry hcs-log --create # once: make the topic, record it as hcsTopic
yarn workspace @sh/foundry hcs-log --dry-run # rebuild the log from the chain, no keysThe operator comes from HEDERA_OPERATOR_ID and HEDERA_OPERATOR_KEY in the environment. Creating the topic costs about $0.01 and each message about $0.0001.
Honest limits#
- Testnet refuels fail closed. SaucerSwap's testnet USDC pool is about 22x off the oracle, so the 3% band refuses the swap and not one micro-USDC leaves the pool. The testnet reserve is topped up with
fund(). - The keeper costs real HBAR, about 1.4 ℏ a run. When the reserve can't cover the next hold, the chain stops until someone funds and revives it.
- The reserve can't be withdrawn. Redeploying leaves the old reserve behind.
- Liquidations wait for the next tick. A slower interval means underwater positions wait longer. Anyone can liquidate in between for the 0.5% reward.