Skip to content
DFUHL Docs
LearnStart here4 pages
How these docs workFoundationHow the site is organised by what you came to do, how every page runs from first principles to engineering detail, and where every fact comes from.Hyperliquid in five minutesFoundationHyperliquid is a set of financial primitives and protocols that combine into one financial system. Build a financial system from nothing, and each Hyperliquid protocol takes its place in it.The house of finance, layer by layerFoundationHyperliquid drawn as a house: one consensus, two engines joined by two bridges, an accounts layer, six financial pillars, a distribution layer that pays others to build, and Hyperliquid itself on top.Traditional finance, pillar by pillarFoundationEvery part of Hyperliquid has a traditional finance counterpart, and each analogy breaks in a specific place that shows what is actually new.
LearnFirst principles5 pages
Why Hyperliquid runs on its own chainFoundationHyperliquid built its own chain so that order books, margin and matching run fully on chain, in one consensus order, fast enough to trade on and with no off-chain book.One chain, two execution environmentsFoundationHyperCore holds the markets as native state and the HyperEVM runs contracts; one HyperBFT consensus orders both, joined by precompiles and CoreWriter.What an on-chain order book actually meansFoundationEvery order, cancel and fill is a transaction ordered by consensus and executed by every node, so the book is public chain state, not a private database.Ordering, finality and fairnessPractitionerHyperBFT gives every honest node one ordered list of committed rounds, a committed block is final, and each block runs cancels before GTC and IOC orders.HYPE: what the token doesFoundationHYPE pays HyperEVM gas, secures consensus, discounts fees, bonds deployers, backs borrowing, and is what the Assistance Fund converts fees into and burns.
LearnConsensus and validators4 pages
HyperBFTPractitionerHyperBFT is Hyperliquid's HotStuff-derived proof-of-stake consensus: stake-weighted validators commit rounds that every honest node executes in the same order.Validators and delegationPractitionerValidators run HyperBFT, ranked by stake; delegators choose them, pay commission, earn nothing while one is jailed and face no automatic slashing yet.Staking HYPE, rewards and the unstaking queueFoundationStaked HYPE is delegated to validators for compounding rewards and fee discounts; getting it back to spot takes a 7-day queue on mainnet.Running a nodeExpertA non-validating node follows consensus and writes every committed transaction, fill, order status, book change and HyperEVM block to local disk.
LearnHyperCore8 pages
HyperCore overviewFoundationHyperCore is where Hyperliquid's order books, margin, clearing and settlement run as native protocol state, applied by every validator in one order.The clearinghouse: one margin enginePractitionerHyperCore's clearinghouse holds balances and positions and checks margin on every trade; in standard mode each perp dex has its own balance and cross margin.The order book and matchingPractitionerEach HyperCore asset has one on-chain book matched in price-time priority, with cancels and post-only orders sequenced ahead of orders that take liquidity.Oracles, mark prices and robust price indicesPractitionerValidators publish perp oracle prices every 3 seconds; the mark price used for margin and liquidation is a median that no single book or venue can move.Quote assets: USDC, USDH, aligned and permissionlessPractitionerAny token can become a HyperCore quote asset if its issuer stakes 200k HYPE against a peg and liquidity standard; aligned issuers also share reserve yield.Vaults: HLP, protocol vaults, user vaultsFoundationA vault pools depositors' USDC into one HyperCore account run by one strategy; HLP is the protocol vault that makes markets and performs liquidations.Multi-sig accountsPractitionerHyperCore can make any account a native k-of-n multi-sig with no smart contract, but CoreWriter stops working for it and its HyperEVM side keeps the old key.API servers and how state reaches youPractitionerAPI servers follow a node, keep a local copy of HyperCore state, answer reads from it, and reply to a transaction only once it executes in a committed block.
LearnResearch5 pages
What one HyperEVM transaction can and cannot doExpertOne HyperEVM transaction can read HyperCore and emit a perp order and an outcome operation, but it only enqueues them, so the legs are not atomic.Options on the borrow rateExpertA research track priced the HyperCore USDC borrow rate with HIP-4 scalar bands, listed them on somebody else's perp, and found owning the perp does not pay.Composable creditExpertA research track tokenised HyperCore lending positions as HyperEVM ERC20s, proved a contract can supply on testnet, and found the vault must be a queue, not a wrapper.Collateral underwritingExpertA research track found the protocol refuses a deployer stake posted by somebody else, and rebuilt underwriting as two-of-two co-custody of the deployer's own bond.Where the chain and the docs disagreeExpertEvery place where measured behaviour on Hyperliquid contradicts the official docs: what the docs say, what was measured, the sample and the covering page.
LearnFor the press4 pages
Start here: press and analystsFoundationFor people writing about Hyperliquid: what it is, how to measure and name it correctly, and the stories behind the numbers.Measuring Hyperliquid: volume, open interest, usersFoundationPublic Hyperliquid figures disagree mostly because each counts the same fills differently; a number means something only with its rows and units.Common misconceptionsFoundationTwelve common claims about Hyperliquid that the official docs or on-chain measurement contradict, each with what is true and where it is explained.Naming and style guideFoundationWrite HyperCore, HyperEVM, HyperBFT, CoreWriter and HIP-1 to HIP-4 exactly, never shorten HyperCore to one word, and do not cite a HIP-5, because none exists.
LearnWhat Hyperliquid is and how it works
Start here
First principles
Consensus and validators
HyperCore
Research
For the press
TradeMarkets, margin and risk
Start here
Trading fundamentals
Perpetuals
Spot
Outcome markets
Accounts and credit
Advanced trading
Incentives
BuildApps, bots and contracts
Start here
Build on HyperCore
Build on the HyperEVM
DeployLaunch and run markets
Start here
The HIPs
Deploy markets
ReferenceEvery number, action and term
Look up
Protocol tables

Oracles, mark prices and robust price indices

Practitioner

Validators publish perp oracle prices every 3 seconds; the mark price used for margin and liquidation is a median that no single book or venue can move.

Every perp has two reference prices, and neither is its last trade. The oracle price comes from spot venues and drives funding. The mark price mixes the book with outside prices and drives margin and liquidation. Both are medians, to minimise the risk of manipulation.

The mark is a median of three inputs

Section titled “The mark is a median of three inputs”

Say the inputs read 3,000, 3,012 and 2,998. The mark is the median, 3,000. If a wick on the book lifts input 2 to 3,050, the median of 3,000, 3,050 and 2,998 is still 3,000.

1. Oracle plus 150 s EMA of (Hyperliquid mid minus oracle) 2. Hyperliquid book median of best bid, best ask, last trade 3. External perp mids weighted median of 5 venues Median every ~3 s Mark price margin, liquidation If exactly two inputs exist, a 30 s EMA of input 2 joins the median.
No single venue, and not the Hyperliquid book alone, can set the mark price.

External perp mids are weighted Binance 3, OKX 2, Bybit 2, Gate IO 1, MEXC 1. The mark also sets TP/SL triggers and unrealised profit and loss, and updates with each oracle publication. The EMAs are time-weighted; for a new sample arriving t after the last update:

numerator   = numerator * exp(-t / 2.5 minutes) + sample * t
denominator = denominator * exp(-t / 2.5 minutes) + t
ema         = numerator / denominator

What this means for you. A book wick alone won’t liquidate you, but an external move the book has not followed can.

Oracle prices come from spot venues

Section titled “Oracle prices come from spot venues”

Every 3 seconds each validator takes a weighted median of spot mids per perp asset:

Source Weight
Binance 3
OKX 2
Bybit 2
Kraken 1
KuCoin 1
Gate IO 1
MEXC 1
Hyperliquid spot 1

Assets whose main spot liquidity is on Hyperliquid (HYPE, in the docs’ example) exclude external sources until those are liquid enough; assets liquid elsewhere (BTC) exclude Hyperliquid spot. Most oracles are in USDT against USDC collateral, unconverted (quanto). PURR and HYPE use USDC oracles, as their most liquid spot market is Hyperliquid’s.

HIP-3 deployers supply their own prices

Section titled “HIP-3 deployers supply their own prices”

On a HIP-3 dex the deployer, or an oracleUpdater it names, pushes setOracle: oracle prices, up to two lists of mark inputs, and external perp prices that guard against sudden mark deviations. The mark is the median of those mark inputs and the local book price, median(best bid, best ask, last trade), so it is partly deployer supplied.

Beyond the table’s limits, pushes are expected every 3 s even without change, and no mark update may take open interest to 10 times its cap. The 10 s stale fallback is to the local book price, and the docs say not to rely on it. They also warn that most price indices make poor perp oracles and that a deployer is slashable for every market on its dex (operating a perp dex).

The protocol clamps the deployer’s feed, but its quality is the deployer’s responsibility.

Other prices built on these

Section titled “Other prices built on these”
  • Recurring HIP-4 outcomes settle on the mark, interpolated linearly between the updates either side of settlement (settlement).
  • Portfolio margin prices borrowed assets at a median of spot, mark and oracle price.
  • Orders too far from the oracle fail as oracleRejected.

The numbers

Section titled “The numbers”
Parameter Value
Oracle publication every 3 seconds, by validators
Final oracle price stake-weighted median of validator submissions
Mark price inputs 3, plus a 30 s EMA when exactly 2 exist
EMA of mid minus oracle 150 s (decay constant 2.5 minutes)
HIP-3 setOracle spacing at least 2.5 s; expected every 3 s
HIP-3 mark move per update at most 1% from the previous mark
HIP-3 price clamp 10x the start-of-day value
HIP-3 stale mark fallback after 10 s without an update
HIP-3 cross margin review any externalPerpPx move over 50% from the start-of-day price
Borrow oracle price median(HL_spot_USDC_price, HL_perp_mark_price * USDT_USDC_oracle, HL_perp_oracle_price * USDT_USDC_oracle)

Reading and pushing prices from code

Section titled “Reading and pushing prices from code”

metaAndAssetCtxs and activeAssetCtx carry markPx, oraclePx, premium and impactPxs; read them; don’t rebuild the mark. Precompiles 0x806, 0x807 and 0x808 return mark, oracle and spot price as a uint64: divide perp prices by 10^(6 - szDecimals), spot by 10^(8 - baseSzDecimals).

For the HIP-3 push, sort every list by coin before signing. markPxs is a list of rounds of pairs, and externalPerpPxs must include every asset on the dex.

{
  "type": "perpDeploy",
  "setOracle": {
    "dex": "<dex>",
    "oraclePxs": [["<coin>", "101.5"]],
    "markPxs": [[["<coin>", "101.6"]]],
    "externalPerpPxs": [["<coin>", "101.4"]]
  }
}

Details that catch integrations out

Section titled “Details that catch integrations out”
  • The oracle’s venues (seven spot plus Hyperliquid spot) differ from the mark’s (five perp, no Kraken or KuCoin).
  • The binaryPrice template settles on an N-second TWAP, not one mark print.
  • A precompile mark read is from when the EVM block was built; a CoreWriter action on it executes later, at a newer price.

For what happens at the mark, see Leverage and liquidation. For differently built oracles, see Hyperps and index perpetuals.