Hyperliquid Wiki Protocol & Ecosystem Knowledge Base
🔍
💻 Developers & SDKs

WebSocket Real-Time API Reference

Low-latency event streaming interface for real-time market data, Level-2 order books, user order updates, and liquidation feeds.

⏱️ 10 min read 📅 Updated: September 2026 ⚡ Protocol: WSS JSON-RPC

1. WebSocket Endpoint & Heartbeat

The Hyperliquid WebSocket server pushes real-time market state with sub-50ms network propagation. Clients connect via standard TLS WebSocket:

// Mainnet WebSocket URI
wss://api.hyperliquid.xyz/ws

// Testnet WebSocket URI
wss://api.hyperliquid-testnet.xyz/ws

To maintain active connections, clients must transmit a JSON heartbeat ping every 30 to 50 seconds:

// Heartbeat Ping
{"method": "ping"}

// Server Response
{"channel": "pong"}

2. Public Market Data Subscriptions

Subscribe to public market feeds without authentication (Python SDK examples):

A. Level-2 Order Book Stream (`l2Book`)

Streams the top bids and asks for a designated asset with aggregated depth levels:

// Subscribe Request
{
  "method": "subscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "ETH"
  }
}

// Message Payload
{
  "channel": "l2Book",
  "data": {
    "coin": "ETH",
    "time": 1773345600120,
    "levels": [
      [{"px": "2650.50", "sz": "14.2", "n": 3}, {"px": "2650.00", "sz": "48.1", "n": 7}],
      [{"px": "2650.60", "sz": "8.5", "n": 2}, {"px": "2651.00", "sz": "32.0", "n": 5}]
    ]
  }
}

B. Real-Time Public Trades (`trades`)

{
  "method": "subscribe",
  "subscription": {
    "type": "trades",
    "coin": "BTC"
  }
}

C. All Mid Prices Stream (`allMids`)

{
  "method": "subscribe",
  "subscription": {
    "type": "allMids"
  }
}

3. User-Specific Private Feeds

Private channels stream real-time updates for a specific Ethereum wallet address:

Subscription Type Parameters Description
userFills user: "0x..." Instant trade execution fills and fee deductions.
orderUpdates user: "0x..." Order lifecycle transitions (Placed, Canceled, Rejected, Filled).
userFundings user: "0x..." Hourly funding payment credits and debits.
userNonFundingLedgerUpdates user: "0x..." Deposits, withdrawals, and internal sub-account transfers.

🔗 Official External References & Primary Sources

To verify the technical architecture, mathematical parameters, and protocol specifications described in this chapter, consult the official documentation: