Keeper Deployment
The keeper is an off-chain bot that processes deposits, executes rebalances, runs DCA schedules, and collects fees.
What the Keeper Does
| Operation | Trigger |
|---|---|
| Process deposits | Escrow has funds |
| Execute DCA | Schedule next_execution reached |
| Trigger rebalance | Cadence elapsed + drift detected |
| Collect fees | Fees accrued since last collection |
| Refund unsupported mints | Unwhitelisted token deposited |
| Swap-assisted deposits | Whitelisted non-USDC deposit |
Running
# Development
bun run --cwd packages/keeper dev
# Production
bun run --cwd packages/keeper start
Configuration
All configuration is via environment variables:
Required
| Variable | Description |
|---|---|
RPC_URLS or SOLANA_RPC_URL | Solana RPC endpoint(s), comma-separated |
KEEPER_KEYPAIR | Path to keeper keypair JSON (default: ./keeper-keypair.json) |
Polling and Retry
| Variable | Default | Description |
|---|---|---|
KEEPER_INTERVAL_MS | 15000 | Main loop interval |
KEEPER_MAX_RETRIES | 3 | Max retries per transaction |
KEEPER_RETRY_BASE_DELAY_MS | 400 | Base delay between retries |
Transaction Fees
| Variable | Default | Description |
|---|---|---|
KEEPER_PRIORITY_FEE_MICROLAMPORTS | auto | Fixed priority fee override |
KEEPER_PRIORITY_FEE_PERCENTILE | 0.75 | Priority fee percentile (when auto) |
KEEPER_COMPUTE_UNIT_MARGIN_BPS | 1500 | CU margin over simulation (15%) |
Route Provider
The keeper needs swap routes for cross-mint rebalancing:
| Variable | Default | Description |
|---|---|---|
KEEPER_ROUTE_PROVIDER_MODE | file | file, http, or hybrid |
KEEPER_REBALANCE_ROUTES_FILE | — | Path to routes JSON file |
KEEPER_REBALANCE_ROUTES_URL | — | URL for route generation service |
KEEPER_ROUTE_GENERATOR_URL | — | On-demand route generator URL |
KEEPER_ROUTES_REFRESH_MS | 30000 | Route cache refresh interval |
KEEPER_ROUTE_REQUEST_TIMEOUT_MS | 2500 | Route request timeout |
KEEPER_ROUTE_FAILURE_THRESHOLD | 3 | Failures before circuit-breaker opens |
KEEPER_ROUTE_FAILURE_COOLDOWN_MS | 30000 | Circuit-breaker cooldown |
Mint Whitelist
| Variable | Description |
|---|---|
KEEPER_WHITELIST_MINTS | Comma-separated mints for swap-deposit processing |
KEEPER_SWAP_ROUTES_FILE | Route config for whitelisted non-USDC deposits |
Telemetry
| Variable | Default | Description |
|---|---|---|
KEEPER_TELEMETRY_WEBHOOK_URL | — | Webhook endpoint for telemetry events |
KEEPER_TELEMETRY_TIMEOUT_MS | 2500 | Webhook timeout |
KEEPER_TELEMETRY_AUTH_HEADER | — | Auth header name |
KEEPER_TELEMETRY_AUTH_TOKEN | — | Auth token value |
Alerting
| Variable | Default | Description |
|---|---|---|
KEEPER_ALERT_FAILURE_RATE_THRESHOLD | 0.25 | Failure rate to trigger alert |
KEEPER_ALERT_MIN_ATTEMPTS | 5 | Min attempts before alerting |
KEEPER_ALERT_COOLDOWN_MS | 300000 | Alert cooldown (5 min) |
RPC Pool
The keeper uses RpcPool for multi-endpoint failover. Provide multiple URLs comma-separated:
RPC_URLS=https://rpc1.example.com,https://rpc2.example.com,https://rpc3.example.com
The pool randomly selects endpoints and retries on alternates when one fails.
Production Checklist
- Use a dedicated keypair with sufficient SOL for transaction fees
- Fund the keeper's USDC token account (for receiving keeper incentives)
- Set up multiple RPC endpoints for reliability
- Configure telemetry webhook for monitoring
- Set appropriate alerting thresholds
- Run as a persistent process (systemd, Docker, Fly.io)