cloudzombie/architecture

Hyperliquid Architecture

What You Probably Got Wrong

"Hyperliquid is an EVM chain." HyperEVM is ONE component of Hyperliquid. The other component — HyperCore — is a custom exchange engine that runs alongside the EVM. They share finality but are distinct execution environments.

"Everything is a contract." HyperCore has no contracts. Its logic (orderbook matching, liquidations, funding rate calculation) is built into the L1 protocol. You can't deploy to HyperCore — you integrate with it via API.

"The EVM and exchange are on separate chains." They share the same validator set and consensus round. An EVM transaction and a HyperCore order placed in the same block are final at the same time. This atomic finality is what makes Hyperliquid unique.

---

System Overview

┌─────────────────────────────────────────────────────────────┐
│                    HyperBFT Consensus                       │
│  (All validators agree on HyperCore + HyperEVM state)       │
│                                                             │
│  ┌──────────────────────┐   ┌──────────────────────────┐   │
│  │      HyperCore       │   │         HyperEVM         │   │
│  │                      │   │                          │   │
│  │  • Perp orderbook    │   │  • EVM contracts         │   │
│  │  • Spot orderbook    │◄──┤  • ERC-20 tokens         │   │
│  │  • Positions         │   │  • DeFi protocols        │   │
│  │  • Funding rates     │   │  • Chain ID 999          │   │
│  │  • HLP vault         │   │  • HYPE gas token        │   │
│  │  • HIP-1/2/3 tokens  │   │                          │   │
│  │  • Cross-margin      │   │                          │   │
│  └──────────────────────┘   └──────────────────────────┘   │
│                                                             │
│  Access:                     Access:                        │
│  POST /info                  Standard EVM RPC               │
│  POST /exchange              https://rpc.hyperliquid.xyz/   │
│  WSS /ws                     evm                            │
└─────────────────────────────────────────────────────────────┘

---

HyperCore

HyperCore is the native exchange engine. It is NOT EVM — it's a purpose-built exchange running at L1 consensus speed.

What Lives in HyperCore

Perpetual Futures:

• All open perp positions (long/short, size, entry price, margin)
• Funding rates and payments (every 8 hours, can be instantaneous)
• Cross-margin pool (USDC collateral shared across all perp positions)
• Isolated margin positions
• Liquidation engine

Spot Orderbook:

• HIP-1 native spot tokens
• Full CLOB (central limit orderbook) for each spot pair
• HIP-2 hyperliquidity — protocol-level AMM for spot tokens

Vaults:

• HLP (Hyperliquid Liquidity Provider) — the main protocol vault
• User-created vaults
• Vault deposits and withdrawals

Token Standards:

• HIP-1: native spot token definition
• HIP-2: automated hyperliquidity seeding
• HIP-3: permissioned spot DEX (builder-controlled listing)

User Accounts:

• Balances (USDC, HYPE, HIP-1 tokens)
• Positions
• Open orders

How to Read HyperCore State

All via POST /info to https://api.hyperliquid.xyz/info:

// Get perp market metadata
{ "type": "meta" }

// Get spot market metadata
{ "type": "spotMeta" }

// Get user state (all positions, balances)
{ "type": "clearinghouseState", "user": "0x..." }

// Get open orders
{ "type": "openOrders", "user": "0x..." }

// Get orderbook
{ "type": "l2Book", "coin": "ETH" }

// Get all perp markets ticker data
{ "type": "allMids" }

How to Write to HyperCore

All via POST /exchange to https://api.hyperliquid.xyz/exchange:

{
  "action": { "type": "order", ... },
  "nonce": 1234567890123,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 }
}

Every write requires an EIP-712 signature. No unsigned writes.

---

HyperEVM

HyperEVM is a standard EVM environment running alongside HyperCore.

What Lives in HyperEVM

• Smart contracts (Solidity, Vyper)
• ERC-20 tokens, ERC-721 NFTs
• HyperSwap V2 (deployed AMM DEX)
• Any contract you deploy
• HYPE as native currency (Chain ID 999)

Key Differences from Ethereum Mainnet

| Feature | Ethereum Mainnet | HyperEVM | |---------|-----------------|----------| | Chain ID | 1 | 999 (mainnet) / 998 (testnet) | | Native currency | ETH | HYPE | | Block time | ~12s | ~1-2s | | Priority fees | → validators | Burned | | Blob transactions | Yes (Cancun) | No (Cancun opcodes, no blobs) | | MEV | Significant | Minimal | | Testnet | Sepolia (11155111) | 998 |

Connecting to HyperEVM

// viem
import { defineChain } from 'viem';

export const hyperliquid = defineChain({
  id: 999,
  name: 'HyperEVM',
  nativeCurrency: { name: 'HYPE', symbol: 'HYPE', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://rpc.hyperliquid.xyz/evm'] },
  },
  blockExplorers: {
    default: { name: 'HyperEVM Explorer', url: 'https://explorer.hyperliquid.xyz' },
  },
});

export const hyperliquidTestnet = defineChain({
  id: 998,
  name: 'HyperEVM Testnet',
  nativeCurrency: { name: 'HYPE', symbol: 'HYPE', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://rpc.hyperliquid-testnet.xyz/evm'] },
  },
  blockExplorers: {
    default: { name: 'HyperEVM Testnet Explorer', url: 'https://explorer-testnet.hyperliquid.xyz' },
  },
});

---

The Bridge: 0x2222...2222

The system address 0x2222222222222222222222222222222222222222 is the HyperCore ↔ HyperEVM bridge.

Moving HYPE from HyperCore to HyperEVM:

• Method 1: On HyperEVM, send a transaction to 0x2222...2222 with HYPE value. This is counterintuitive — you're sending FROM HyperEVM TO the bridge address, and HYPE appears on HyperEVM.
• Wait, actually: sending HYPE to 0x2222...2222 on HyperEVM withdraws it TO HyperCore.

Let me clarify the bridge mechanics:

HyperEVM → HyperCore (withdraw from EVM):

• Send HYPE to 0x2222222222222222222222222222222222222222 on HyperEVM
• HYPE appears in your HyperCore spot balance

HyperCore → HyperEVM (deposit to EVM):

• Use the /exchange API with action type "spotSend" or use the "evmUserModify" action
• HYPE appears as HYPE token on HyperEVM

In practice:

• The Hyperliquid app UI handles bridging for users
• For programmatic bridging, use the SDK
• HYPE decimals: 18 on HyperEVM, float representation in HyperCore API

---

HyperCore State Reading from HyperEVM

HyperEVM contracts can read HyperCore state via a system precompile at address 0x0000000000000000000000000000000000000800 (verify current address in official docs — may change).

This enables HyperEVM contracts to:

• Read open positions
• Read orderbook state
• Trigger HyperCore actions based on onchain conditions

This is advanced functionality — most builders use the REST API instead of the precompile.

---

State Sync and Finality

Both HyperCore and HyperEVM reach finality in the same HyperBFT round. This means:

• A HyperCore order and a HyperEVM transaction in the same block are BOTH final at the same time
• There's no "cross-chain" risk between HyperCore and HyperEVM — they share consensus
• Bridge operations (via 0x2222...2222) have the same finality guarantee

No waiting for "safe" confirmations. 1 block = final. Plan your UX accordingly.

---

Decision Framework: Where Does Logic Go?

Does it involve trading, positions, or native token markets?
├─ YES → HyperCore API (/exchange)
│        Use SDK, EIP-712 signing
│
└─ NO  → Does it need custom contract logic?
         ├─ YES → HyperEVM (Solidity contract)
         │         Chain ID 999, HYPE gas
         │
         └─ NO  → Is it a read query?
                   ├─ HyperCore state → POST /info
                   └─ EVM state → standard eth_call via RPC

---

Asset IDs

Understanding asset IDs is critical for HyperCore API calls:

• Perp asset IDs: 0-indexed position in meta.universe array (e.g., ETH-perp might be asset 1)
• Spot asset IDs: 10000 + spot index (e.g., if PURR is spot index 0, its asset ID is 10000)
• HIP-3 builder assets: 100000 + (perp_dex_index * 10000) + index

Always fetch current asset IDs via POST /info with { "type": "meta" } — never hardcode them.

# Get current asset IDs
import requests

meta = requests.post('https://api.hyperliquid.xyz/info',
                     json={'type': 'meta'}).json()

# Perp assets
for i, asset in enumerate(meta['universe']):
    print(f"Perp {i}: {asset['name']}")

# Spot assets
spot_meta = requests.post('https://api.hyperliquid.xyz/info',
                           json={'type': 'spotMeta'}).json()
for i, token in enumerate(spot_meta['tokens']):
    print(f"Spot {i} (ID: {10000+i}): {token['name']}")