concepts

name	concepts
description	Essential mental models for building on Hyperliquid. HyperCore vs HyperEVM, asset IDs, nonce mechanics, margin types, incentive design. Use when designing a system or when you need to understand how Hyperliquid actually works.

Hyperliquid Concepts

What You Probably Got Wrong

"Nothing is automatic on EVM." This is still true on HyperEVM. Smart contracts don't run themselves. Every HyperEVM function needs a caller. But HyperCore is different — it HAS automatic processes: funding rate settlements, liquidations, order matching. The protocol runs these autonomously.

"Nonces increment by 1." On HyperCore, NO. HyperCore nonces are a rolling-set scheme — not sequential. Read the nonce section carefully before building any trading system.

"HYPE is like ETH." On HyperEVM, mostly yes. But HYPE is also the staking/governance token for the whole L1, not just gas. The total HYPE supply matters for protocol economics in ways ETH's doesn't.

---

HyperCore vs HyperEVM: The Mental Model

Think of Hyperliquid as two machines sharing the same clock:

HyperCore = The Exchange Machine

• Native perp/spot orderbook running at protocol speed
• Manages positions, margins, liquidations, funding
• You interact via HTTP API (POST /info, POST /exchange)
• No contracts. No gas. Built into consensus.
• Think: a centralized exchange's matching engine, but consensus-secured

HyperEVM = The Smart Contract Machine

• Standard EVM: Solidity, OpenZeppelin, viem, Foundry
• Custom logic, composability, token contracts
• You interact via EVM RPC (eth_call, eth_sendTransaction)
• Needs gas (in HYPE). Has contracts.
• Think: a fast, cheap Ethereum L2

The shared clock = HyperBFT

• Both machines settle in the same consensus round
• Atomic finality across both layers
• Bridge between them is trustless (same validators)

---

Nothing Is Automatic (HyperEVM)

Same rule as Ethereum. Smart contracts are state machines. Between caller interactions, they do nothing.

For every HyperEVM function:
  Who calls it? → Someone must pay HYPE gas
  Why would they? → What's their incentive?
  Is the incentive sufficient? → Does it cover gas + profit?

HyperCore is different. These ACTUALLY happen automatically:

• Funding rate settlement: Every 8 hours (and can be more frequent), funding payments happen automatically via the protocol
• Liquidations: When health factor drops below threshold, bots compete to liquidate (they earn a bonus)
• Order matching: Whenever a matching bid/ask exists, the protocol matches them

Design implication: If you need automatic behavior on HyperEVM, you still need an incentivized caller. If you want automatic trading behavior, it belongs in HyperCore (via a bot using the API), not in a contract.

---

Asset IDs

Understanding asset IDs is the #1 source of confusion for HyperCore API users.

Perp assets:

• ID = index in meta.universe array
• ETH perp is typically index 1 (BTC is 0), but verify dynamically
• NEVER hardcode asset indices. They can change when new assets are added.

Spot assets:

• ID = 10000 + spot token index
• First HIP-1 token = spot index 0 → asset ID 10000
• Verify via {"type": "spotMeta"}

HIP-3 builder DEX assets:

• ID = 100000 + (perp_dex_index × 10000) + token_index
• Rarely needed unless building a HIP-3 exchange

# CORRECT: Always fetch asset IDs dynamically
def get_asset_id(info, symbol, is_perp=True):
    if is_perp:
        meta = info.meta()
        for i, asset in enumerate(meta['universe']):
            if asset['name'] == symbol:
                return i
        raise ValueError(f"Perp asset {symbol} not found")
    else:
        spot_meta = info.spot_meta()
        for i, token in enumerate(spot_meta['tokens']):
            if token['name'] == symbol:
                return 10000 + i
        raise ValueError(f"Spot asset {symbol} not found")

---

Nonces on HyperCore

This is critically different from Ethereum. Read carefully.

HyperCore Nonce Rules

• Each signer has a rolling window of the 20 highest nonces seen
• Any new nonce must be strictly greater than the lowest nonce in the window
• Once the window is full (20 entries), new entries evict the lowest

Why this design?

• Allows parallel order submission (multiple nonces in flight simultaneously)
• Allows out-of-order arrival (nonce 5 can arrive after nonce 7)
• Prevents stuck nonces (you don't need sequential inclusion)

Practical Nonce Management

# ✅ CORRECT: Use millisecond timestamps
import time
nonce = int(time.time() * 1000)  # Always increasing, works for concurrent requests

# ✅ CORRECT: Use the official SDK (handles nonces internally)
from hyperliquid.exchange import Exchange
exchange = Exchange(wallet, api_url)  # SDK manages nonces

# ❌ WRONG: Don't try to track sequential nonces manually
nonce = last_nonce + 1  # Fails with concurrent requests

# ❌ WRONG: Don't reuse old nonces
nonce = 1234  # Will fail if this is in the current window

Nonce conflict = order rejection. Use millisecond timestamps or let the SDK handle it.

Nonce Window and Concurrency

If you need to submit 5 orders in rapid succession:

import time

# Stagger by 1ms each to guarantee unique nonces
orders = []
for i in range(5):
    nonce = int(time.time() * 1000) + i
    orders.append(build_order(nonce=nonce, ...))

# Submit in parallel or sequence

---

Margin Types on HyperCore

HyperCore has two margin modes for perp positions:

Cross Margin (Default)

• All positions share a single USDC margin pool
• If one position loses, the shared pool covers it
• More capital-efficient (don't need margin per position)
• Risk: a big loss in one position can liquidate ALL positions

Isolated Margin

• Each position has its own dedicated margin
• Losses in one position don't affect others
• Less capital-efficient (need to allocate margin per position)
• Risk: limited to the allocated margin for that position

# Switch a position to isolated margin
result = exchange.update_isolated_margin(
    coin="ETH",
    is_buy=True,
    ntli=100.0  # Isolated margin amount in USDC
)

---

Liquidations on HyperCore

Understanding liquidations is critical for designing systems around HyperCore:

How liquidations work:

1. Position health = (account equity / maintenance margin requirement)
2. When health < 1: the position is eligible for liquidation
3. Anyone (typically bots) can call liquidate
4. Liquidator receives a bonus (% of position value)
5. Remaining assets go back to the liquidated user

Health factor calculation:

Account Value = USDC Balance + Unrealized PnL
Maintenance Margin = Sum of (position_size × price × maintenance_rate)

Health = Account Value / Maintenance Margin

Liquidation trigger: Health < 1 (or specified threshold per market).

For vault builders: Your vault can become a liquidation bot — earn fees by monitoring positions and liquidating unhealthy ones.

---

Funding Rates

Perpetual futures use funding rates to keep perp prices in line with spot:

• Positive funding: Longs pay shorts (perp price > spot → shorts pay longs)
• Negative funding: Shorts pay longs (perp price < spot → longs pay shorts)
• Settlement: Funding accrues continuously but settles periodically (every 8 hours standard)
• Rate: Calculated based on the spread between perp mark price and index price

# Get current funding rates
ctx = requests.post('https://api.hyperliquid.xyz/info',
                    json={'type': 'metaAndAssetCtxs'}).json()

for i, (asset, ctx) in enumerate(zip(ctx[0]['universe'], ctx[1])):
    if ctx.get('funding'):
        print(f"{asset['name']}: funding={ctx['funding']} premium={ctx.get('premium', 'N/A')}")

---

Price Types in HyperCore

HyperCore uses several price concepts:

• Mark price: Used for margin calculations. Derived from median of oracle prices.
• Oracle price: External price feed, used for funding rate calculation.
• Mid price: (Best bid + Best ask) / 2 from the CLOB.
• Last trade price: Price of the most recent fill.

For calculations involving margin and health: Use mark price. For placing limit orders: Use mid price as reference. For spot price: Use the CLOB mid price.

---

Decimals: A Gotcha Summary

Asset	HyperCore API	HyperEVM
HYPE	Float string (e.g., "1.5")	18 decimals (1.5 HYPE = 1.5e18 wei)
USDC	Float string (e.g., "100.0")	6 decimals (100 USDC = 100e6)
Perp size	Float string	N/A
Perp notional	USDC float	N/A
HIP-1 tokens	Per token config	N/A unless bridged

USDC has 6 decimals on HyperEVM. This is the #1 decimal bug. Don't assume 18.

---

The EIP-712 Signing Mental Model

Every HyperCore exchange action requires an EIP-712 signature:

1. Build action payload (specific to the action type)
2. Construct EIP-712 message:
   - Domain: { name: "Exchange", version: "1", chainId: 1337 }
   - Struct: the action data
3. Hash: keccak256(abi.encodePacked("\x19\x01", domainSeparator, structHash))
4. Sign: ECDSA sign with private key
5. Extract: r, s, v components
6. Submit: POST /exchange with { action, nonce, signature: {r, s, v} }

chainId in EIP-712 is always 1337 for HyperCore — not 999 (HyperEVM mainnet) or 998 (testnet). This is a deliberate design choice that makes HyperCore signing portable.

Use the SDK — it handles all this correctly.