Skip to content
AevumFi
Launch App

Protocol modules

Keeper

Liquidations, orders, batch settlement, ladder re-centring and launch-fee routing.

The keeper is the protocol's automation. Each pass it:

  1. Liquidates every position whose equity is below maintenance at fresh prices, and earns the liquidation fee.
  2. Executes limit and stop orders whose trigger the fresh price has reached, and earns their execution fee.
  3. Settles dark-pool batches whose reveal window has closed.
  4. Pushes prices while there is open interest, so the Omni-Vault's share price never goes stale and deposits and withdrawals stay open.
  5. Re-centres ladder vaults that made the keeper their operator, once each vault's own rules allow it (cooldown, drift, EMA guard) and its owner's daily gas allowance covers the transaction. It is reimbursed from the vault's gas reserve.
  6. Routes launch fees. It harvests creator fees once they are worth about a dollar, pays agent streams out every few hours, retries deferred conversions once they would go through, sweeps an NFT floor when a backstop can afford it, and runs buyback cycles when bids fill.

Every one of these calls is permissionless except re-centring, which only a vault's chosen operator may do — anyone can run a keeper, and traders can settle their own dark-pool batches, push prices, harvest launch fees or run routes from the Terminal. The keeper examines every open position, order, ladder vault and launch, simulates each transaction first and only sends the ones that would succeed — up to 25 per pass, liquidations first.

Running it#

The keeper is a route in the app, GET /api/keeper, which requires Authorization: Bearer $CRON_SECRET. It needs:

VariablePurpose
KEEPER_PRIVATE_KEYAccount that sends keeper transactions; hold a little ETH on it for gas.
ORACLE_SIGNER_PRIVATE_KEYSigns the price batches the keeper submits.
CRON_SECRETShared secret for the route.
KEEPER_RPC_URLOptional dedicated RPC (recommended on mainnet).

The deployment runs it every minute through a Vercel Cron job (vercel.json); Vercel sends the secret automatically. For a tighter cadence, run the bundled loop anywhere as well — it calls the route every 15 seconds:

KEEPER_URL=https://aevum.fi CRON_SECRET=… node scripts/keeper.mjs

Liquidations and order execution wait for whichever runs next, so a tighter loop is safer. Running both is safe: if two passes race for the same action, the later transaction reverts (or fails on the account's nonce) and changes nothing — at most it costs a little gas.