Hyperliquid API WebSocket Setup Guide — Real-Time Data for 2026 Traders

Why Use Hyperliquid's WebSocket API?

Hyperliquid provides one of the fastest WebSocket APIs in decentralized trading. Sub-second block times mean that WebSocket data streams reflect the actual on-chain state with minimal latency — unlike some CEXs where WebSocket data can lead or lag the matching engine. Whether you are building a trading bot, a real-time dashboard, or an alerting system, the WebSocket API is the foundation.

This guide covers everything from basic connection setup to authenticated streams for private position data. If you are new to Hyperliquid, use code HOLYGRAIL at app.hyperliquid.xyz/join/HOLYGRAIL to save 4% on trading fees while you build.

Public WebSocket Endpoints

Hyperliquid's public WebSocket streams do not require authentication. You can connect to them directly from any WebSocket client. The main public endpoints are:

• Mainnet WebSocket: wss://api.hyperliquid.xyz/ws — the primary endpoint for all production trading data.
• Testnet WebSocket: wss://api.hyperliquid-testnet.xyz/ws — for development and testing without real funds.

Both endpoints support the same message formats. Always develop and test on testnet before deploying to mainnet.

Subscribing to Market Data Streams

Once connected, you subscribe to specific data streams by sending a JSON subscription message. Here is how to subscribe to the most commonly used streams:

Order Book Updates

To receive real-time order book snapshots and incremental updates for BTC-PERP:

subscription: 
  type: "l2Book"
  coin: "BTC"

The response includes a full snapshot on subscription, followed by incremental updates as orders are placed, filled, or canceled. Each update contains price levels and sizes, making it straightforward to maintain a local copy of the order book.

Recent Trades

To stream all trades for a given market:

subscription: 
  type: "trades"
  coin: "ETH"

Each trade message includes the price, size, side (buy or sell), and timestamp in milliseconds. This stream is useful for volume-weighted average price calculations and trade signal generation.

Candle Data

For OHLCV candles at various intervals:

subscription: 
  type: "candle"
  coin: "SOL"
  interval: "1m"

Supported intervals include 1m, 5m, 15m, 1h, 4h, and 1d. Candle streams are more bandwidth-efficient than tick-level trade streams if you only need higher-timeframe data.

Authenticated WebSocket Streams

For private data — your open orders, positions, and account updates — you need an authenticated WebSocket connection. Hyperliquid uses a signature-based authentication scheme that proves you control the wallet without exposing your private key to the WebSocket connection itself.

The authentication flow works as follows:

1. Generate a timestamp within 60 seconds of the current time.
2. Create a signature by signing the message with your wallet's private key. The signable payload includes the action type and timestamp.
3. Send an authenticated subscription message containing your wallet address, the timestamp, and the signature.

Once authenticated, you can subscribe to these private streams:

• Order updates: Real-time notifications when your orders are placed, partially filled, fully filled, or canceled.
• Position updates: Current position sizes, entry prices, unrealized PnL, and liquidation prices across all markets.
• Account updates: Margin usage, free collateral, and total account value changes.

Connection Management Best Practices

WebSocket connections are not permanent. Network interruptions, server restarts, and rate limits can all cause disconnections. A robust implementation should handle these gracefully:

• Auto-reconnect with exponential backoff. If the connection drops, retry after 1 second, then 2, 4, 8, up to a maximum of 60 seconds. This avoids hammering the server while ensuring timely reconnection.
• Re-subscribe on reconnect. After reconnecting, your subscriptions do not persist. Always re-send subscription messages after establishing a new connection.
• Maintain a local order book snapshot. Rather than re-requesting a full snapshot on every reconnect, maintain a local copy and apply incremental updates. This reduces load on the API and improves your bot's responsiveness.
• Heartbeat monitoring. Send a ping message every 30 seconds and expect a pong response. If you miss two consecutive pongs, assume the connection is stale and initiate a reconnect.

Rate Limits and Throttling

Hyperliquid enforces rate limits on WebSocket connections just as it does on REST endpoints. The limits are generous for individual traders, but automated systems should respect them:

• Maximum subscriptions per connection: 50 active streams.
• Maximum connections per IP: 10.
• Message burst limit: roughly 100 messages per second before throttling kicks in.

If you exceed these limits, Hyperliquid will close your connection with a rate limit error code. Your reconnection logic should include a delay before retrying in this case.

Testing Your WebSocket Setup

Before connecting real capital, test your WebSocket implementation on testnet. Here are the steps:

1. Connect to wss://api.hyperliquid-testnet.xyz/ws
2. Subscribe to the L2 book for BTC to verify snapshot and update messages arrive correctly.
3. Place a test order through the REST API (or the testnet web interface) and confirm the order update appears in your authenticated stream.
4. Simulate a disconnection by killing your WebSocket client and verify the reconnection logic works.
5. Monitor memory and CPU usage over 24 hours to ensure no resource leaks.

Once everything works on testnet, switch the endpoint URL to mainnet and you are ready to go.

Common Pitfalls to Avoid

• Subscribing to too many streams. Each subscription creates a persistent data flow. Subscribing to the order book for 100+ coins will consume significant bandwidth and CPU. Filter to only the markets you actually trade.
• Ignoring message sequencing. WebSocket messages can arrive out of order. Hyperliquid includes sequence numbers in order book updates — use them to detect and handle gaps.
• Hardcoding the WebSocket URL. Endpoints can change. Use a configuration file or environment variable so you can update without redeploying your code.
• Not handling stale data. If your WebSocket goes silent for more than a few seconds, your local state may be stale. Use the REST API as a fallback to refresh data when WebSocket lags.