Getting started
Custos documentation
Custos is a margin engine the Hedera network keeps: an HBAR-USD perpetual market whose liquidations and funding are run by Hedera's Schedule Service, with no keeper bot and no server. It ships as a scaffold-hbar template you can scaffold with one command.
On most chains, anything that must happen on a timer (liquidations, funding, interest, expiries) is run by an automation network or a team's own bot. Hedera has its own answer: since HIP-1215, a contract can book a call to itself in the future, and the network runs it. Custos uses that for the highest-stakes job there is, liquidating positions with real money on the line, and solves its sharp edges in the open: capacity, the gas hold, broken chains, gas limits and testing.
What you get#
Three reusable parts, and a market built from them:
| Contract | Job | Reuse it for |
|---|---|---|
ScheduledKeeper | Runs a job every interval with no bot: each tick books the next one on the Schedule Service and pays for it. | Liquidations, interest, expiries, rebalancing, payouts |
PriceGuard | Chainlink is the price, Supra is the cross-check. Refuses stale or disagreeing prices, never reverts on a broken feed. | Anything that must not act on a bad price |
MarginAccount | Position book and risk math: PnL, funding, equity, maintenance margin, liquidation price. | Perps, margin, leveraged positions |
PerpMarket | The HBAR-USD market. The network liquidates and charges funding on every tick. | The demo; copy it for a new market |
LiquidityPool | USDC in, cUSDC-LP out: a native Hedera token the pool creates and mints. Every trader's counterparty. | Any vault whose shares should be a real Hedera token |
HbarDepositZap | LPs deposit with HBAR: SaucerSwap swaps it to USDC and the zap deposits it, in one transaction. | Any vault that should accept HBAR directly |
Hedera services in play#
- Schedule Service: the keeper. Every tick books the next one (HIP-1215).
- Token Service: USDC collateral, and the cUSDC-LP share token, created and minted by the pool contract.
- Consensus Service: an audit log of every keeper event on topic 0.0.10839050(opens in a new tab).
- Mirror node: the app's history, and the source the audit log is built from.
- Ecosystem: Chainlink and Supra prices; SaucerSwap for opening with HBAR, closing to HBAR, depositing HBAR, and the keeper's refuel; HashPack and Kabila wallets.