Build with Custos
Add a market
The engine doesn't care what asset it prices. A market is a PriceGuard config plus its own pool and market contract, so adding ETH-USD is one entry in markets.json, a test run, a live feed check and a deploy. No Solidity changes.
What a market is#
Each entry in packages/foundry/markets.json is what PriceGuard needs for one asset:
| Key | Meaning |
|---|---|
chainlink | The Chainlink aggregator for ASSET/USD on Hedera (the price) |
supra | Supra's push-oracle contract (the cross-check) |
supraPair | Supra's pair index for the asset |
maxStaleness | Seconds before a feed counts as Stale; at most 86,400 (1 day) |
maxDeviationBps | Largest Chainlink/Supra gap allowed; at most 2,000 bps |
refPrice8 | A typical price with 8 decimals, used by the tests |
The shipped entry is HBAR-USD: Chainlink HBAR/USD, Supra pair 75, 43,200 s staleness, 500 bps. Leave it as it is; the app reads that market.
The recipe: ETH-USD#
Add the entry to markets.json
Next to
"HBAR-USD"inpackages/foundry/markets.json:packages/foundry/markets.json"ETH-USD": { "chainlink": "0xb9d461e0b962aF219866aDfA7DD19C52bB9871b9", "supra": "0x6Cd59830AAD978446e6cc7f6cc173aF7656Fb917", "supraPair": 19, "maxStaleness": 86400, "maxDeviationBps": 500, "refPrice8": 270000000000 }Chainlink ETH/USD on Hedera testnet (8 decimals); the same Supra contract HBAR-USD uses, pair 19 (ETH/USDT).
refPrice8is $2,700.Check the config offline
bashyarn workspace @sh/foundry check-markets ETH-USDChecks every entry against the limits
PriceGuardenforces and fails if ETH-USD is missing. No network, no keys.Run the tests
bashyarn foundry:testtest/Markets.t.solreadsmarkets.jsonand runs every market through a full cycle at itsrefPrice8: the guard accepts the config, a long and a short open, the network liquidates the long on a 15% drop, the short closes at a profit, and the pool's books balance. A new entry is covered with no new test.Check the live feeds on testnet
bashyarn custos:check-market:testnet --market ETH-USDDeploys only a
PriceGuardwith the ETH-USD config (a little HBAR), reads both feeds, prints the prices and status, and exits 1 if either feed doesn't answer. It signs with a keystore orDEPLOYER_PRIVATE_KEYfrom your shell. On 2026-10-03 it read Chainlink 2,657.85 and Supra 2,702.77 (PriceGuard 0x1eD9de81…51949D(opens in a new tab)).Deploy it
bashyarn custos:deploy:testnet --market ETH-USD yarn custos:start:testnet --market ETH-USDDeploys a PriceGuard, pool and market for ETH-USD, then books its keeper's first tick.
custos:demo:testnettakes the same flag. The addresses go topackages/foundry/deployments/296-eth-usd.json;deployedContracts.tsis left alone, so the app keeps showing HBAR-USD.
Choosing the staleness window#
maxStaleness must be longer than the slowest feed's gap between updates, or the market reads Stale: close-only, sweeps skipped, pool deposits paused. Push oracles update on deviation or on a heartbeat, and on testnet they push rarely.
- Supra's testnet ETH/USDT was seen 8 hours old, so testnet ETH-USD needs the guard's maximum, 86,400 s.
- On mainnet, where feeds update far more often, use about 3,600 s.
- The 500 bps deviation check against Supra still catches a wrong price inside a long window. Supra quotes USDT, so leave room for a small gap from Chainlink's USD price.
- Supra pairs 0 and 1 haven't updated on testnet in months; don't use them.
An agent did this on its first attempt#
The repo's .harness/ recipe asks a coding agent to add ETH-USD by following AGENTS.md, then grades the result from static checks up to a live feed check on testnet. A recorded run passed on attempt 1 of 3, changing 4 files and no contracts. See Hedera Harness.