Keeper Bot
Overview#
The keeper bot is an automated referee that monitors expired signals, evaluates price outcomes against Hyperliquid market data, and resolves them on-chain. It is the only entity authorized to call resolveSignal() on the smart contract.
Architecture#
The keeper is a Python 3.12+ async application with three components:
- Monitor: Polls the contract for expired, unresolved signals by tracking
SignalCreatedevents - Validator: Fetches hidden params from the backend API and price data from Hyperliquid, then evaluates outcomes
- Settler: Submits
resolveSignal()transactions to HyperEVM with the commitment reveal
Evaluation Logic#
The keeper uses a close-based evaluation model. For each expired signal:
1. Fetch entry_price (market price at signal creation)
2. Fetch resolution_price (closing price at expiry)
3. Evaluate:
IF direction == LONG AND resolution_price > entry_price → HIT
IF direction == SHORT AND resolution_price < entry_price → HIT
Otherwise → MISSThe close-based model checks whether the closing price at expiry moved in the predicted direction relative to the entry price. This is distinct from a “touch” model that would check if the target was reached at any point during the window.
Data Sources#
| Source | Data | Auth |
|---|---|---|
| Smart Contract | Asset, duration, createdAt, expiryTime (public) | None (on-chain read) |
| Backend API | targetPrice, direction, salt (hidden params) | API key |
| Hyperliquid API | candleSnapshot (1-minute candles) | None (public) |
Configuration#
Required:
RPC_URL WebSocket endpoint for HyperEVM
KEEPER_KEY Private key for transaction signing
MARKETPLACE Contract address
CHAIN_ID 998 (testnet) or 999 (mainnet)
BACKEND_URL API base URL
KEEPER_API_KEY Internal API authentication
Optional:
POLL_INTERVAL 30 seconds (default)
GRACE_PERIOD 5 minutes after expiry before resolving
GAS_LIMIT Max gas per resolution transactionError Handling#
| Condition | Behavior |
|---|---|
| Backend unavailable | Retry 3x with exponential backoff |
| Hyperliquid API 429 | Back off 60 seconds |
| Invalid reveal (hash mismatch) | Critical alert, skip signal |
| Gas price exceeded | Skip, retry next poll cycle |
| Transaction reverted (already resolved) | Log and skip |
An invalid_reveal_count > 0 in health metrics indicates a commitment hash bug. This should never happen in production and warrants immediate investigation.
Health Monitoring#
The keeper exposes a GET /health endpoint with:
- Keeper wallet balance (ETH for gas)
- Active and pending signal counts
- Backend API reachability
- Hyperliquid API reachability
- Invalid reveal count (should always be 0)
- Last resolution timestamp
Configure Discord or Slack webhook alerts for critical conditions (low balance, API unreachable, invalid reveals).
Multi-Instance#
No distributed lock is needed. The contract's resolved flag is the lock. If multiple keeper instances race to resolve the same signal, one will succeed and the others will revert with a harmless “already resolved” error. This makes it safe to run redundant keepers for high availability.