Keeper configuration

What the protocol’s keeper needs, the environment variables it reads with their defaults, logging, and common failure modes.

The keeper’s source and binary are not published. This page documents how the protocol’s keeper is configured: what it needs, the environment variables it reads and their defaults, its logs, and how it fails. Integrators do not need any of it; mint, redeem and trades go straight to the programs.

What it needs

• Two funded keypairs. The keeper wallet must be market.keeper_authority on every market it operates, and pays for price pushes and settlements. The CLP authority signs book shapes and inventory moves and pays rent for new pool accounts. On devnet it is also each market’s admin authority, which fee posting needs.
• RPC endpoints. Market discovery uses getAccountInfo. The commit settler uses a filtered getProgramAccounts and websocket subscriptions, which some paid RPC tiers disable, so at least one endpoint must allow them.
• The mint-redeem program ID. Without DEVNET_MINT_REDEEM_PROGRAM_ID or MINT_REDEEM_PROGRAM_ID, market discovery fails and the keeper runs QQQ only, with a warning.
• Storage for the transaction journal. Every transaction that moves funds is journaled first, in Cloudflare R2 or under a persistent DATA_DIR. Without a working journal the keeper disables those transactions; price pushes still go out.

The protocol deploys the keeper as a Docker image built with Rust 1.88. The image sets RUST_LOG=info and UPDATE_INTERVAL_MS=5000 and exposes port 8484. The process exits with a non-zero code as soon as any of its loops ends, so it runs under a supervisor that restarts it on failure.

Environment variables

The keeper loads .env from its working directory, or the file named by KEEPER_ENV_FILE (which must come from the process environment). Per-network settings, such as the RPC URL, collateral mint and program IDs, are read with a DEVNET_ or MAINNET_ prefix first, then without it.

Networks and keys

Variable	Default	Meaning
DEVNET_RPC_URL, MAINNET_RPC_URL	unset	Comma-separated endpoints, first one primary. Set either or both; one process serves each. The official cluster URL is appended as the last fallback.
RPC_URL	https://api.devnet.solana.com	Single-network mode, used only when neither of the above is set.
KEEPER_KEYPAIR_JSON, KEEPER_KEYPAIR	unset, ~/.config/solana/id.json	Keeper wallet as a JSON byte array (preferred) or a file path. If no key loads, the keeper runs read-only.
CLP_AUTHORITY_KEYPAIR_JSON, CLP_AUTHORITY_KEYPAIR	unset, key/clp-authority.json	CLP authority, the same way. If no key loads, CLP-authority instructions are signed by the keeper wallet and fail unless it is the CLP authority.
USDC_MINT	mainnet USDC on devnet; required on mainnet	Collateral mint. On devnet set it to cUSDC, B1c5xBYkp7AAemYhcu4VuH4CU4sPJDDuG2iuv6ts38uE.
MINT_REDEEM_PROGRAM_ID	unset	Needed for market discovery. Transactions fall back to the devnet ID on devnet.
ORACLE_PROGRAM_ID, CLP_PROGRAM_ID	devnet IDs on devnet	Required on mainnet; the keeper will not start there without them.
ACTIVE_MARKETS	unset	Comma-separated symbols to pin. When unset, the keeper reads the Market account of each of the 14 symbols it supports and keeps those with is_active = true.

On devnet, an unset USDC_MINT falls back to mainnet USDC. Every token-account derivation is then wrong, vault balances read as 0, and loops skip markets without an error. Always set DEVNET_USDC_MINT or USDC_MINT to cUSDC on devnet.

Price source

Variable	Default	Meaning
UPDATE_INTERVAL_MS	15000 (5000 in the image)	Price-push interval.
PYTH_API_KEY	unset	Pyth Pro key. Without it Pyth requests fail, and the keeper can price markets only from its fallback public quote source, which is switched on by CNBC_FALLBACK_ENABLED (off by default). With neither source answering, it withholds every push.
CNBC_FALLBACK_ENABLED	false	Allows the fallback public quote source. Without it, the keeper uses Pyth only.
HERMES_URL	https://hermes.pyth.network	Hermes base URL, for addressing a different host directly.
HERMES_STALE_SECS	120	Withhold a market’s push when the source’s own publish time is older than this, whichever source it came from.
HL_CROSS_CHECK_ENABLED	true	Compare each fresh print with Hyperliquid and withhold the push when they disagree. An unreachable Hyperliquid lets the print through; Hyperliquid never sets a price.
CROSS_CHECK_BAND_BPS	30 FX, 60 metals, 100 stocks	Largest allowed disagreement. One value overrides all three.

A print more than 10% from the last accepted price is held, and an operator releases it by writing an R2 object, as described in CNBC price holds. The updater also pushes nothing for a market after its scheduled close plus 15 minutes.

When the fallback source prices a market, the confidence band comes from a GJR-GARCH volatility model; with Pyth, the keeper uses the wider of Pyth’s band and the model’s. Mainnet will price from Pyth (Pyth Pro).

Book manager and parameter posting

Variable	Default	Meaning
CLMM_POOLS_ENABLED	true	The book-manager loop. Refills, rebalancing and all parameter posting run inside it, including γ, so false stops all of them.
CLMM_POOL_INTERVAL_SECS	30	Loop cadence, minimum 15.
CLMM_REPOSITION_BPS, CLMM_REPOSITION_BPS_<SYM>	20	Largest reposition gate; the keeper cuts it per side to the first funded bin.
CLMM_VOL_SPREAD_ENABLED	true	Volatility-scaled spreads. false posts a plain geometric shape from the first bin, with no spread floor, skew or inventory shift.
CLMM_SKEW_ENABLED	true	Protective trend skew.
CLMM_INVENTORY_SKEW_ENABLED	true	Inventory centre-shift, tuned by CLMM_INVENTORY_GAIN (1.0) and CLMM_INVENTORY_CAP_FRAC (0.5).
CLMM_SHAPE_KEEP_BPS	7000	Per-bin decay of the live shape (0.7 per bin).
CLMM_REFILL_ENABLED	true	Ask refill, bid refill, trim and bid cap.
CLMM_SKEW_GAIN	1.0	Gain on the protective drift skew: the side a continuing trend would pick is widened by this multiple of the trend’s z-score, and the other side is never tightened.
CLMM_REFILL_DUST_USD	500	Smallest bid refill, in dollars, worth a transaction.
CLMM_BID_TARGET_USD	unset	Overrides the bid cUSDC each side stages while the market is open. Unset, each side stages the depth its next free-float book will post (r55’s rule, $500 a side until the keeper has measured flow). The pool vault’s cUSDC above the target is swept to the CLP vault, and a vault below it is refilled from there.
CLMM_TRIM_RATIO	1.5	Largest ask value as a multiple of the bid target.
CLMM_FEE_SCALE_ENABLED	true	Posts clamp(fee_mult × half-spread, 10, 100) bps as the mint and redeem fee when it moves by 5 bps or more. fee_mult is 1.0.
CLMM_COMMIT_SPREAD_ENABLED	true	Posts clamp(half-spread, 10, 500) bps as the committed-order spread when it moves by 2 bps or more.
CLMM_BUFFER_POST_ENABLED	true	Posts each market’s overcollateralization target (see Solvency) when it differs from the value on chain.
CLMM_BUFFER_TARGETS_BPS	unset	Overrides the posted buffer for listed markets, as SYM:bps pairs (NVDA:1000,TSLA:1200), clamped to 100 to 5,000 bps. It wins over the daily target the keeper reads from R2 (cr-targets/latest.json, written by the daily Monte Carlo job), which wins over the fixed fallback table; a market missing from that table posts 100 bps.
CLMM_REBALANCE_ENABLED	true	Cross-market collateral rebalance.
GAMMA_DECAY_COEF	1.0	γ calibration. Must be in (0, 1]; any other value aborts boot.
CLMM_GAMMA_DECAY_ENABLED	removed	Setting it to any value aborts boot. γ decay has no switch.

Off-hours book

Variable	Default	Meaning
CLMM_FREEFLOAT_DMIN_USD	500	Smallest depth, in dollars, a free-float book posts per side. The depth is max(this, min(demand quantile, risk cap)), with no static ceiling. The old CLMM_FREEFLOAT_CAP_USD and CLMM_FREEFLOAT_CAP_USD_JUMP caps are ignored.
CLMM_FREEFLOAT_FLOW_USD_<SYM>	0	Uninformed flow per closed period across all four sides of market <SYM>, in dollars. At 0 every side posts the minimum.
FF_GUARD_ENABLED	true	Free-float guard, which pulls stale-side bins when other venues show a move.
FF_GUARD_MIN_MOVE_BPS	10	Venue moves smaller than this count as noise.
FF_GUARD_RESTORE_SECS	600	How long venues must allow it before pulled bins return.

Committed orders

Variable	Default	Meaning
COMMIT_SETTLE_ENABLED	true	The settlement cranker. It simulates each settle, draws any cash a fill needs beyond the CLP vault from the treasury in the same transaction where it fits, and refunds expired orders about 5 s after expiry.
COMMIT_SETTLE_INTERVAL_SECS	20	Idle cadence, minimum 5. It drops to 5 s while orders are pending.

Liquidity reallocator

Variable	Default	Meaning
EXPOSURE_CAPS_MODE	dryrun	off, dryrun (logs the caps it would post) or live. Every 30 minutes the primary keeper writes the nightly cr-targets job’s exposure_caps_atoms to each market’s Clp.oi_cap with update_oi_cap: any decrease at once, an increase only above 1%. It holds the on-chain cap when the file is missing or over 48 h old, when a market has no entry, or when a target is under $1, and it never posts 0. Any other value means dryrun. See Solvency → Exposure cap.
LIQUIDITY_REALLOCATOR_MODE	live	off, dryrun (logs the moves) or live. Keeps each market’s CLP vault between its working need and twice that need, topping up from the treasury and returning the rest, and runs the treasury backstop (backstop_market).
LIQUIDITY_REALLOCATOR_INTERVAL_SECS	30	Cadence, minimum 30. The working need counts every consumer run that fits in one tick, so a longer tick widens the band.
TREASURY_BACKSTOP_MAX_TARGET_BPS	13000	Highest collateral ratio the treasury backstop fills a market to, in bps of claims, clamped to 10,000 to 15,000. Below it, a market is filled to its posted target.
TREASURY_BACKSTOP_SKIP	MSTR	Comma-separated markets the backstop fills only to 101%.
WIND_DOWN_MARKETS	MSTR	Comma-separated markets being wound down: no working cash or backstop, books emptied and swept back to the CLP, the 1% minimum buffer posted, and while the price is fresh the CLP’s pairs redeemed (all but one) and the surplus collateral returned to the treasury. Empty disables it.

Treasury withdrawal rate

Variable	Default	Meaning
TREASURY_RATE_MODE	live	off, dryrun (logs the plan) or live. Every 900 s it keeps the treasury’s withdrawal limits where the whole balance can leave in TREASURY_EXIT_SECS, signing set_treasury_limits as the CLP authority. A raise waits out the policy’s 24 h delay and is applied with apply_treasury_limits once due; a cut applies at once. It acts only when the limits are more than 10% off, never while the allowance is refilling, and never over a pending change it didn’t make.
TREASURY_EXIT_SECS	86400	How long a full exit takes, clamped to 1 h to 30 days. The burst leaves at once and the rest at the rate, so the rate is the balance ÷ (exit + burst seconds).
TREASURY_BURST_SECS	3600	The burst, in seconds of the rate.

Imbalance control

Variable	Default	Meaning
IMBALANCE_CONTROL_MODE	live	off, dryrun (logs the plan) or live. The daily collateral targets assume it runs live, and plan without it for any market whose imbalance leaves twice the band. Every 900 s, for each active market with a price under 240 s old, it redeems the CLP’s surplus of the heavier leg with vault_redeem_single until the book’s long and short values are back in balance.
IMBALANCE_BAND	0.05	How far the imbalance β = (L − S)/(L + S) may drift from its target before it acts.
IMBALANCE_TARGETS	empty	Per-market targets for β, as SYM=β,…. Unlisted markets target 0.
IMBALANCE_MAX_USD	50000	Most it redeems in one market in one tick.
IMBALANCE_KEEP_BPS	unset	Overrides the CLP’s stock share per leg (bps of the market’s claims, at most 500). Unset, it follows the daily job’s value, or 50 if the file is missing or over 48 hours old.
IMBALANCE_MIN_USD	100	Smallest redemption or trim it sends.

Short rebate

Variable	Default	Meaning
REBATE_MODE	crank	off, crank or live. crank sends refresh_rebate for each market every REBATE_INTERVAL_SECS (960 s by default) and nothing else. live also funds each market’s rebate pot with fund_rebate, signed as the CLP authority and paid from the treasury through admin_withdraw. It tops the pot up to about a day of need when it holds less than half a day, and never beyond the collateral yield the market has harvested since the rebate opened. See Short rebate.

Redemption settler

Variable	Default	Meaning
REDEMPTION_SETTLE_ENABLED	false	Pays queued request_redemption requests, oldest first: settle_redemption from the vault’s cash, then with a recall from the lending venues in the same transaction, then with a treasury advance (advance_to_market), and it repays an advance from the market’s next recall. See Redeem.
REDEMPTION_SETTLE_INTERVAL_SECS	60	Idle cadence, minimum 10. It drops to 10 s while work is pending.
REDEMPTION_ADVANCE_ENABLED	true	Allows treasury advances. The market’s on-chain max_advance_bps still decides how much.
REDEMPTION_SPLIT_RECALL	false	Sends the recall and the settle as separate transactions. An escape hatch; off, they are one atomic transaction.
REDEMPTION_ESTIMATE_PAD_BPS	100	Margin added to the settler’s estimate of what a part will pay.

Devnet treasury trim

Variable	Default	Meaning
DEVNET_TREASURY_TARGET_USD	unset	Devnet only. When set, the keeper withdraws what the treasury policy’s allowance allows every 5 minutes, never past this balance, and burns it in the same transaction. Unset or 0 is off. It never runs on mainnet.

Health and alerts

Variable	Default	Meaning
SOL_HEALTH_INTERVAL_SECS	300	Balance check cadence, minimum 15.
SOL_HEALTH_KEEPER_LOW_LAMPORTS, SOL_HEALTH_KEEPER_CRITICAL_LAMPORTS	0.5 SOL, 0.15 SOL	Keeper wallet. Below the low line the dashboard marks it low. Below the critical line the keeper tops it up, then alerts if it is still below.
SOL_HEALTH_CLP_AUTHORITY_LOW_LAMPORTS, SOL_HEALTH_CLP_AUTHORITY_CRITICAL_LAMPORTS	1 SOL, 0.2 SOL	The same lines for the CLP authority.
SOL_REFILL_BUFFER_LAMPORTS	1 SOL	Top-ups aim this far above the low line.
SOL_AUTO_AIRDROP_ENABLED	true	Devnet top-up by airdrop.
SOL_REFILL_SLIPPAGE_BPS	100	Slippage tolerance for the USDC-to-SOL swap.
SOL_REFILL_SWAP_ENABLED	true	Mainnet top-up: swaps the keeper wallet’s own USDC to SOL through Jupiter, at most $250 per swap (SOL_REFILL_MAX_USDC).
DISCORD_BOT_TOKEN and DISCORD_NOTIF_CHANNEL_ID, or DISCORD_SOL_HEALTH_WEBHOOK_URL	unset	Alert by bot (tried first) or by webhook. With neither set, alerting is off and the keeper logs that at startup.
SOL_HEALTH_ALERT_COOLDOWN_SECS	3600	At most one alert per wallet in this window.

Storage, dashboard and logs

Variable	Default	Meaning
R2_ACCOUNT_ID, R2_BUCKET, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY	unset	Journal in R2. Setting any one selects R2 and requires all four.
DATA_API_KEY	unset	Required for the keeper’s data endpoints (/api/data/**), which are refused without it. Callers send it as the x-api-key header, and the frontend’s KEEPER_DATA_API_KEY must match. /healthz, /health and /ping stay open.
DATA_DIR	/data	Root for the journal and the γ and off-hours checkpoints when R2 is unset. It must persist across restarts and support OS file locks, and only one process can hold it.
PORT, then DASHBOARD_PORT	8484	The single dashboard port.
KEEPER_PEERS	unset	Dashboard URLs of other keeper instances (see below).
RUST_LOG	info	Log filter (see Logging).
KEEPER_LOG_FILE	unset	Write logs to this file instead of stderr.

Collateral yield

The allocator’s limits come from the stress assumptions below and the treasury balance, which it reads on chain, rather than from fixed percentages. See Keeper → Yield allocator.

Variable	Default	Meaning
YIELD_ALLOCATOR_ENABLED	true	Yield planning, on every cluster. The devnet emulator uses its mainnet snapshots, so turning it off also stops emulated yield.
YIELD_ALLOCATOR_INTERVAL_SECS	300	Planning cadence, at least 60 s.
YIELD_STRESS_REDEEM_FRAC_PER_DAY	0.5	Share of a market’s collateral a stressed run can redeem in a day.
YIELD_LIQUID_SHARE	0.03	Measured liquid share. It is the fallback: while the nightly cr-targets file is under 48 h old, the allocator uses that job’s liquid share instead (1% to 10%; a rise applies at once, a fall is limited).
YIELD_RECALL_HORIZON_HOURS	0.1	Time to get lent collateral back (6 minutes). Together with the stress rate above it gives only a small share, so the liquid share binds.
YIELD_MIN_LIQUID_USD	0	Liquid floor per market, in dollars. There is no fixed floor.
YIELD_VENUE_LOSS_BUDGET	0.5	Share of all markets’ collateral above 100% that counts as first-loss capital, on top of the treasury.
YIELD_VENUE_FAILURES_COVERED	1	Venue failures to cover, 1 to 4. Each venue’s total position across all markets is capped at first-loss capital divided by this number, on top of its share below.
YIELD_VENUE_LOSS_SHARE_TIER1	0.5	Largest share of first-loss capital one venue may hold if it has no lender losses on record: Kamino and Jupiter Lend.
YIELD_VENUE_LOSS_SHARE_TIER2	0.25	The same for every other venue: Save. MarginFi is disabled in the plan.
YIELD_EXIT_LIQUIDITY_SHARE	0.5	Largest share of a venue’s withdrawable liquidity the protocol may hold.
YIELD_SPOT_WEIGHT	0.25	Weight of today’s rate against the 30-day mean.
YIELD_MIN_MARGINAL_APR	0.01	Hurdle: no more is lent once the marginal rate falls below it.
DEVNET_YIELD_EMULATION	true (devnet only)	Emulated harvests at the rate the mainnet plan would earn.
DEVNET_YIELD_INTERVAL_SECS	3600	Emulator cadence.

Off by default

Variable	Default	Meaning
COLLATERAL_YIELD_ENABLED	false	Lending collateral. It acts only on mainnet USDC, and the market also needs yield_enabled and a non-zero yield_ceiling_bps.

Primary and standby

Several instances can run with the same keys. Set KEEPER_PEERS on each to the dashboard URLs of the others. Every 30 s each instance probes /api/status/<network> on its peers, and the one with the oldest start time is primary. Standby instances still push prices, which is harmless to repeat, but skip the loops that move funds, such as the book manager and the commit settler. When the primary stops answering, the oldest remaining instance takes over at the next probe.

Each market has one keeper_authority; the market admin can rotate it with update_keeper_authority to split markets between operators. Bots without either key can run alongside: cancel_swap and claim are permissionless, and anyone can trade the books. settle_swap needs clp.authority or market.keeper_authority.

Logging

The binary crate is named keeper, so log targets are its module paths: keeper::oracle, keeper::clmm_pool, keeper::commit_settler, keeper::sol_health, keeper::tx, keeper::rpc. A filter for continuum_keeper matches nothing and silences the keeper.

RUST_LOG=info,keeper::clmm_pool=debug,keeper::commit_settler=debug

keeper::clmm_pool=debug logs every reposition, refill and posting decision, and keeper::commit_settler=debug logs committed-order discovery and settlement. keeper::rpc=warn keeps only RPC failures.

A healthy devnet start logs lines like these (timestamps omitted):

INFO keeper: Starting Continuum Keeper Bot
INFO keeper: Env validated: γ decay UNCONDITIONAL, GAMMA_DECAY_COEF=1.0 (unset default)
INFO keeper::config: [discovery] QQQ → ACTIVE (F12ostJBgYCzsdouwz5GG1qeBCwbmhNGucPBNCZCfPG5)
INFO keeper: Networks configured: devnet
INFO keeper: Dashboard port resolved to 8484 (from default(8484))

The dashboard serves /healthz, /api/status/<network>, /api/sol-health/<network> and /api/pool-state/<network>.

Common issues

The keeper refuses to start

Remove CLMM_GAMMA_DECAY_ENABLED if it is set, and check that GAMMA_DECAY_COEF is a number in (0, 1]. On mainnet, also set the collateral mint and the oracle, mint-redeem and CLP program IDs; there is no fallback to devnet values.

It runs only QQQ, skips markets, or fails with UnauthorizedKeeper

1. Set DEVNET_MINT_REDEEM_PROGRAM_ID or MINT_REDEEM_PROGRAM_ID. Without it, discovery fails and the keeper falls back to QQQ.
2. Set the collateral mint to cUSDC on devnet (see the warning above).
3. Check that market.keeper_authority is the keeper wallet’s public key. The admin may have rotated it with update_keeper_authority.
4. On insufficient-lamports errors, check both wallets. Rent for new pool accounts comes from the CLP authority.

”Financial transactions paused” or UNCONFIRMED_TX_MAY_STILL_LAND

An earlier send ended with an unknown outcome, so the keeper stopped every transaction that moves funds. It re-checks the journaled transaction every 30 s. Once the log shows “Reconciled financial transaction … restart keeper to rebuild plans and resume”, restart it. If the journal is reported unavailable or already owned, configure R2 or a persistent DATA_DIR, and make sure no other process holds the same journal.

RPC rate limits

List several endpoints. After 3 consecutive retriable failures (HTTP 429, 503 or a transport error) an endpoint is skipped for 30 s, then probed again.

A book sits far from NAV

If the underlying market is closed, this is free float by design, and the first fresh price re-centres the book. If the market is open, check CLMM_POOLS_ENABLED and the keeper::clmm_pool logs, then the CLP vault balance if the book’s depth is exhausted. A stale price while the market is open means the source is down or Hyperliquid is vetoing it; check the keeper::oracle logs.

Leftover L or S in the keeper wallet

The keeper no longer sweeps it at boot. Redeem matched amounts with redeem_paired, or a single leg with keeper_redeem_single, signed by the keeper wallet.

See also

Keeper overview

What the keeper runs and which keys it holds.

Peg maintenance

Why the venues stay near NAV and what bounds drift.

Book management

Reposition loop, free float, refill, trim and bid cap.