Custos docs

Using the app

Trade

The /trade page opens a long or short on HBAR-USD with 1x to 50x leverage, paid in USDC or in HBAR through SaucerSwap. It shows your liquidation price while the position is open, and closes it to USDC or HBAR.

The trade page: the HBAR-USD mark price, the open form with direction, pay-with and leverage, and the open positions table
/trade on the live testnet deployment

Before you open#

The header shows the HBAR-USD mark price (Chainlink HBAR/USD through PriceGuard, the exact price the contract trades at), the Supra check (HBAR/USDT), the price ages, funding and open interest, and a status:

  • Open: both feeds are fresh and close enough. You can open, close and add collateral.
  • Open, but a price is getting old: still open, with a countdown to close-only.
  • Close-only: a price is out of date, or the two prices disagree. See Close-only mode.

USDC on Hedera is a Token Service token (testnet: 0.0.5449(opens in a new tab)). Your account must be associated with it before the market can pay you. The form shows the steps it needs: Associate USDC, Approve (USDC only), then Open or Swap and open. If your account associates automatically, the first step is already done.

Open a position#

  1. Pick a direction

    Long profits if HBAR rises; Short profits if it falls. Each account holds one position at a time.

  2. Pick what you pay with

    USDC calls open(isLong, collateral, leverage). HBAR via SaucerSwap calls openWithHbar(isLong, leverage, minCollateral): the market swaps your HBAR to USDC on SaucerSwap and opens in the same transaction. Pick the Slippage you accept (0.5%, 1% or 2%); if the swap would return less, nothing happens.

  3. Set the amount and leverage

    Collateral times leverage is the position's notional. The presets are 2x, 5x, 10x, 25x and 50x, and you can type an exact value from 1 to 50. The 0.1% opening fee is taken from your collateral and goes to the pool.

  4. Read the preview

    Before you sign, the form shows the Entry price, Liquidation price, Funding after you open and the Room under the cap. The preview works without a wallet.

RuleValueError if broken
Leverage1x to 50xPerpMarket__InvalidLeverage
Minimum collateral1 USDC on the testnet deploy (after the swap, for HBAR)PerpMarket__BelowMinCollateral
Open fee0.1% of notional, from the collateral—
Open interest capAll open positions together use at most 50% of the pool's USDCPerpMarket__OpenInterestCap
One position per accountClose first to open anotherPerpMarket__PositionExists
PriceOpens need an Ok pricePriceGuard__NotOk

On chain: a 50x long opened with 1 ℏ (0x62868b09…3986e7(opens in a new tab)) and a 50x short opened with 1.2 USDC (0xfac6b7ec…b7bdba(opens in a new tab)).

Your liquidation price#

A position is liquidated when its equity (collateral + PnL − funding owed, with the gain capped at the entry notional) falls below its maintenance margin, 1% of notional. The liquidation price is where that happens:

liquidation price
buffer    = collateral − funding owed − 1% of notional
liq price = entry price − buffer / size        (size < 0 for a short)

10 USDC at 10x long:  notional 100, fee 0.10, collateral 9.90, margin 1.00
                      buffer 8.90 → liquidated about 8.9% below entry
1 USDC at 50x long:   notional 50, fee 0.05, collateral 0.95, margin 0.50
                      buffer 0.45 → liquidated about 0.9% below entry
  • Funding moves it. Funding you owe shrinks the buffer and pulls the liquidation price toward the mark; funding owed to you pushes it away.
  • Add collateral moves it away. addCollateral(amount) works any time, even in close-only mode.
  • Who liquidates. The network checks every position at each tick (every 30 minutes on the testnet deploy) and liquidates for no reward. Anyone may liquidate earlier with liquidate(trader) at an Ok price, for 0.5% of notional.
  • What you lose. All remaining collateral goes to the pool, including any equity left above zero.

Your position card shows Margin left before liquidation as a bar. The Open positions on this market table lists every position with its Liquidates at and Distance.

Funding#

Funding is 0.1% of notional per hour, scaled by the long/short skew over the pool's USDC. When longs outweigh shorts, longs pay and shorts earn, and the reverse. The net goes to the pool. It accrues every second and is settled when you close: the position card shows it as You owe this; it's taken when you close or Owed to you.

Close a position#

A position must stay open at least 300 seconds; until then the button reads Close allowed in …. You receive your equity minus the 0.1% closing fee. Profit above your collateral is paid by the pool.

ReceiveCallsWhat happens
USDCclose()The payout lands in your account in USDC.
HBAR via SaucerSwapcloseToHbar(minHbarOut)The market swaps the USDC payout to HBAR on SaucerSwap in the same transaction. The app accepts up to 1% slippage.

On chain: a close to USDC (0xbaa65216…c61df6(opens in a new tab)) and a close to HBAR (0x1e427e54…d91c36(opens in a new tab)). A close to USDC pays you in USDC, so your account must be associated with it first (the app offers Associate USDC). A close to HBAR needs no association: the USDC settles to the market, which swaps it and sends you HBAR.

Close-only mode#

When PriceGuard reports Stale or Deviated, the market is close-only: new positions can't open, manual liquidations are refused, and the network skips its sweep. You can still close and add collateral. The close price is chosen by closePrice(trader):

  1. At an Ok price: Chainlink.
  2. Otherwise: the worse price for you among the feeds that are still fresh. A long gets the lower one, a short the higher one. If only one feed is fresh, that one.
  3. If no feed is fresh: no close. The button reads Waiting for a price feed to answer and the contract reverts PerpMarket__NoPrice.

When something fails#

Every revert has a named error. Troubleshooting lists each one with its fix, and Testnet proof has a HashScan link for every trading flow.