Getting started
Quickstart
Scaffold the template and run its test suite in a few minutes with no account. Then deploy your own market to Hedera testnet and watch the network keep it.
Before you start#
- Node.js 20.18.3 or later, and Git.
- Foundry(opens in a new tab) (
forgeandcast). The contracts build, test and deploy with it. - For the testnet steps, a Hedera testnet ECDSA account funded from the Hedera faucet(opens in a new tab). EVM signing needs an ECDSA key; an ED25519 account has none.
1. Scaffold and test locally#
No account and nothing spent. The tests emulate Hedera's Token Service and mock the Schedule Service.
Create your project
bashnpm create scaffold-hbar@latest -- --template victorjayeoba/scaffold-hbar-custosThe CLI asks for a project name and installs everything.
Compile and test the contracts
bashcd <your-project> yarn foundry:compile yarn foundry:testThis runs every unit, fuzz and invariant test, including the solvency invariants (no bad debt, the pool always covers the largest possible gains, the keeper reserve always covers the next run).
2. Deploy your own market to testnet#
Create or import a deployer account
bashyarn foundry:account:generate # or: yarn foundry:account:importFund it from the faucet. The deploy sends HBAR, as the table below shows.
Deploy and link the contracts
bashyarn custos:deploy:testnetDeploys
PriceGuard,LiquidityPoolandPerpMarket, links them, creates the cUSDC-LP share token on the Token Service and funds the keeper. It writespackages/foundry/deployments/296.jsonand regeneratespackages/nextjs/contracts/deployedContracts.ts, so the app points at your market.Book the first tick
bashyarn custos:start:testnetAssociates the pool and market with USDC and books the keeper's first tick. From here on the network runs it: every tick books the next.
Seed it (optional)
bashyarn custos:demo:testnetSwaps HBAR to USDC on SaucerSwap, deposits it in the pool, and opens a 50x long with 1 HBAR.
| What the scripts send | Default | Set with |
|---|---|---|
| The keeper's HBAR reserve | 40 ℏ | KEEPER_FUND |
| Creating the share token (about 12 ℏ is used, the rest comes back) | 30 ℏ | SHARE_TOKEN_FEE |
| Demo: HBAR swapped to pool USDC | 120 ℏ | DEMO_POOL_HBAR |
| Demo: HBAR per trade | 1 ℏ | DEMO_TRADE_HBAR |
3. Run the app#
yarn next:devOpen localhost:3000/keeper. The first network run arrives one interval (30 minutes by default) after custos:start:testnet. Connect HashPack, Kabila, MetaMask or any WalletConnect wallet; see Trade for what each page does.

Next steps#
- How it works: the contracts and a liquidation end to end.
- Add a market: ETH-USD as configuration.
- Troubleshooting: every error and its fix.