architecture

name	architecture
description	HyperCore vs HyperEVM — what lives where, how they interact, the complete system model. Essential reading before building anything on Hyperliquid. Use when planning architecture, understanding state, or deciding where logic belongs.

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']}")