Running a Keeper
This page covers the practical details of running a keeper bot on Zenex. For an overview of what keepers are and why they matter, see the Keepers overview.
Requirements
Running a keeper requires a few things. You need a Stellar account funded with XLM to cover transaction fees on the Stellar network. Transaction costs on Stellar are low, typically fractions of a cent per transaction, so the XLM requirement is modest. You need a server or machine that can run continuously with reliable internet connectivity, since keepers need to react to price changes quickly. You also need access to Pyth Lazer price feeds to get the same oracle data that the protocol uses for execution.
Revenue Model
Keepers earn revenue through the caller rate, which is a percentage of the trading fees generated by each action they successfully execute. When a keeper fills a limit order, the opening fees include a base fee and a price impact fee. A portion of those fees, determined by the caller rate parameter, is paid directly to the keeper's Stellar account. The same applies to stop-loss executions, take-profit executions, and liquidations.
The caller rate is a global protocol parameter, visible on-chain. The exact percentage is designed to make keeper operation profitable while keeping the majority of fees flowing to the vault and treasury.
Your revenue as a keeper depends on how many actions you successfully execute. A faster, more reliable keeper that monitors all markets and responds to price changes within seconds will capture more opportunities than one that checks intermittently. Speed matters because the execution market is competitive.
Competition
Keeper execution is fully competitive. There is no assignment system, no rotation, and no guaranteed allocation. When a limit order becomes fillable or a position becomes liquidatable, every active keeper can see it and attempt to execute it. Multiple keepers may submit transactions simultaneously, but only the first valid transaction to land on the ledger will succeed. The others are simply rejected without penalty (though they do consume a small amount of XLM in transaction fees).
This competitive dynamic benefits the protocol and its users. It ensures low execution latency, because keepers are incentivized to be as fast as possible. It also provides redundancy, because even if one keeper goes offline, others will continue executing actions.
Getting Started
The zenex-keeper reference implementation, written in Rust, demonstrates the full keeper loop: price monitoring, condition detection, batch construction, and transaction submission. To run it, you will need a Mercury subscription for indexing on-chain state and a Pyth Lazer API key for real-time price feeds.
The Zenex SDK (TypeScript) also provides helpers for interacting with the trading contract, including reading position state, constructing execute transactions, and submitting them to the network. The Integration Guide in the technical documentation covers the contract interfaces in detail. Start with a single market to understand the flow before scaling to monitor all available pairs.