Concepts

The complete, verified derivations are in the Protocol reference. This page is the working summary.

Units#

USD values are 18-decimal integers ("wad"). Use usdToWad, wadToNumber and formatUnits. Never use floats for money you intend to sign.
HyperEVM USDC has 6 decimals, HyperCore USDC has 8. wadToUsdc converts.
Prices are integers divided by a per-instrument priceScale (BTC 10, ETH 100). priceFromRaw and priceToRaw convert.
Open interest and caps are base-asset quantities (wad BTC or ETH), not dollars. Price them at the mark with openInterestUsd.

Markets and limits#

Instruments: BTC (id 0) and ETH (id 1). Leverage is a whole number up to the market maximum (1000x at launch).
Minimum margin is 10 USD and minimum notional (margin times leverage) is 10,000 USD. Maximum position is 10M USD notional.
OpenPosition.size is the margin, not the notional.
Prices settle on the Hyperliquid BBO mid, read through priceHistory at 125 ms, 1 s or 1 min resolution.

Bust (liquidation) price#

For a long, bust = ceil(entry * (L - 1) / L) * (1 + buffer). For a short, bust = ceil(entry * (L + 1) / L * (1 - buffer)). The buffer is about 4.76 bps. At 500x a long is liquidated about 0.15% below entry. liquidationPriceRaw reproduces the protocol integer exactly.

How a close settles#

Loss: you lose the raw loss, with nothing on top. Crossing the bust price forfeits the full margin.
Win: the raw gain first loses an integer deadband (entry / 50,000), then an asymmetric impact haircut that grows with the size of the move and the position, then a 2% win fee.
estimateClose returns each stage, plus keptFraction, the share of the raw gain you keep.

PAPER#

PAPER is minted on realized losses (the loss basis is 98% of the loss) at a rate that is flat at 100 per 1 USD while tracked LP is under 2M USD, then decays with the tail-progress high-water mark. paperMintRate and estimatePaperMinted implement the curve. Staked PAPER earns protocol fees; pendingStakingRewardRaw computes pending rewards with 1e27 precision.

Intents, session keys and nonces#

Every action is an EIP-712 intent posted to the relayer. The exchange domain name is the literal string String, which is correct and verified against a mainnet signature.
A session key is registered once by the wallet and can sign opens, closes and cancels. It cannot withdraw, stake, unstake or claim.
Intent ids are keccak256(keccak256("papertrade:intent-id:v2") ++ digest ++ signer).
Nonces only need to be unique per (user, lane). PAPER actions use their own lane. Deadlines are at most one hour out.
Intent POSTs are retried only on HTTP 429 or 503 and never after a network error, so a trade is never sent twice.

Raw Markdown: /docs/concepts.md