Hyperliquid API Websocket Guide for Developers (2026)

About this guide: I'm Lawrence, the writer behind supa.is. Between February and May 2026 I've published 150+ articles on supa.is across crypto and brokerage tooling — including 40+ Hyperliquid-specific guides (recent examples: Hyperliquid API Rate Limits & User Limits 2026, Hyperliquid Websocket Reconnect Fix 2026, Hyperliquid Python SDK Tutorial: Build a Bot (2026)). The most-repeated reader question across that Hyperliquid archive is exactly how to properly connect to the Hyperliquid API via Websockets, which is why I'm publishing this standardized guide instead of answering one-off.

Risk Warning: Crypto trading involves substantial risk of loss. Never invest more than you can afford to lose. This is not financial advice.

If you are building a trading bot, a real-time dashboard, or an algorithmic strategy on Hyperliquid, relying on REST API polling is a recipe for latency, rate-limit bans, and missed fills. Websockets provide a persistent, bi-directional connection that pushes data to your client the millisecond it happens.

The catch is that Hyperliquid's Websocket architecture is strict—especially around authentication and subscription order. Get it wrong and you'll face silent disconnections or auth failures. This guide walks you through connecting, subscribing, and keeping that connection alive in 2026.

Why Websockets Over REST for Hyperliquid

The Hyperliquid REST API is excellent for one-off queries: getting your current balance, placing a single order, or fetching historical OHLCV data. But for a live trading system, REST has three fatal flaws:

1. Latency: Polling every 100ms means your data is at least 100ms old. In a fast market, that's an eternity.
2. Rate Limits: Hyperliquid enforces strict rate limits on REST endpoints. If you poll too aggressively to compensate for latency, your API key gets throttled. You can read more about the exact limits in our Hyperliquid API Rate Limits & User Limits 2026 guide.
3. Inefficiency: You are sending empty requests just to check if anything changed.

The Hyperliquid Websocket Architecture

Before writing a single line of code, you need to understand how Hyperliquid structures its Websocket API. Unlike some centralized exchanges that separate public data (order book) and private data (your account) into entirely different endpoints, Hyperliquid uses a unified Websocket endpoint.

The official documentation for the Hyperliquid API Websocket can be found here.

The connection flow follows a strict sequence:

1. Connect: Open a Websocket connection to the Hyperliquid endpoint.
2. Subscribe: Send a JSON payload requesting specific data channels (e.g., l2Book, trades, user).
3. Authenticate (Optional but required for private data): Send a signed authentication payload.
4. Receive: The server begins streaming JSON messages to your client.

The Unified Endpoint

You will connect to a single base URL. For the mainnet, this is typically wss://api.hyperliquid.xyz/ws. Testnet uses a different URL, which is vital for development.

When you first connect, the server does not send you any data. You are essentially sitting in a dark room. You must explicitly ask for what you want to see by sending subscription requests.

Step 1: Establishing the Connection

The first step is straightforward. You initiate a standard Websocket connection using your programming language of choice.

Using Python's websocket library, it's a two-liner:

import websocket

ws = websocket.WebSocket()
ws.connect("wss://api.hyperliquid.xyz/ws")

JavaScript is similarly straightforward:

const ws = new WebSocket("wss://api.hyperliquid.xyz/ws");

Once the connection state is OPEN, you are ready to send messages.

Step 2: Subscribing to Data Channels

To start receiving data, you must send a JSON payload to the server. The payload follows this structure:

{
  "method": "subscribe",
  "subscription": {
    "type": "<channel_type>",
    "coin": "<coin_name_or_all>"
  }
}

Let's break down the most important channels you will use.

1. The l2Book Channel (Order Book)

If you are doing market making or need to track liquidity, the l2Book channel is essential. It provides the levels of the order book.

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

The server will push snapshots of the order book for BTC. If the order book changes, it will push an incremental update.

2. The trades Channel (Live Trades)

To see every fill happening on the exchange in real-time, subscribe to the trades channel. This is useful for tracking market momentum or triggering your bot based on large whale trades.

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

3. The user Channel (Private Data)

This is where most developers get stuck. If you want to see your own open orders, account balance, or fills, you need the user channel.

{
  "method": "subscribe",
  "subscription": {
    "type": "user",
    "coin": "all"
  }
}

Setting the coin to "all" means you will receive updates for every asset you hold or have open orders for.

Step 3: Authenticating the Connection

To access the user channel or to place orders via Websocket, you must authenticate. Hyperliquid uses a standard HMAC-SHA256 signing mechanism.

You will need your API Key and API Secret. If you haven't set these up yet, you can do so by signing up on Hyperliquid and navigating to the API settings in your dashboard.

You'll need to sign a string containing your API key, a nonce (an incrementing integer), and the action you're attempting. The flow looks like this:

1. Generate a Nonce: A high-precision incrementing integer.
2. Create the Message: Combine your API key, the nonce, and the string "subscribe".
3. Sign the Message: Use your API Secret to create an HMAC-SHA256 signature of the message.
4. Send the Payload: Send the JSON payload over the Websocket.

{
  "method": "auth",
  "params": {
    "nonce": 1722334455667,
    "signature": "<your_hmac_sha256_signature>",
    "apiKey": "<your_api_key>"
  }
}

Once the server accepts your signature, it will respond with a confirmation, and you can then proceed to subscribe to the user channel.

Step 4: Placing Orders via Websocket

Placing orders over Websocket is faster than REST since you skip the HTTP handshake overhead for every order. The payload is sent as a standard Websocket message:

{
  "method": "order",
  "params": {
    "order": {
      "coin": "BTC",
      "side": "A",
      "limitPx": 60000.0,
      "sz": 0.1,
      "orderType": "Limit",
      "timeInForce": "GTC"
    },
    "vaultAddress": "<your_vault_address>",
    "nonce": 1722334455668
  }
}

Note that you must include the vaultAddress. Hyperliquid operates on a vault system, and your API key is tied to a specific vault.

Common Pitfalls and Troubleshooting

Building on the Hyperliquid API can be frustrating if you don't anticipate the common failure modes. Here are the most frequent issues developers face.

1. The "Silent Drop"

You will notice that your Websocket connection suddenly stops receiving data, but your code doesn't throw an error. This is a "silent drop." Hyperliquid's infrastructure occasionally drops connections without sending a standard Websocket close frame.

2. Subscription Overload

Hyperliquid allows you to subscribe to multiple channels. But if you subscribe to l2Book for every single coin on the platform, your local machine will choke on the incoming JSON payloads. The data volume can easily exceed the processing capacity of a standard VPS.

3. Nonce Reuse

When authenticating or placing orders, you must use a unique, incrementing nonce. If you reuse a nonce, the server will reject the request. This is a security feature to prevent replay attacks.

4. Missing Fills

If you are tracking your PnL and suddenly notice a fill is missing from your local state, it's usually because your Websocket connection dropped right at the moment the fill happened.

Best Practices for Production Bots

If you are moving from a testnet script to a live production bot on Hyperliquid, you need to harden your Websocket implementation.

* Use a Dedicated VPS: Don't run your trading bot on your local laptop. Network latency from your ISP can cause your Websocket connection to time out. A VPS located in a data center close to Hyperliquid's servers (often in the US or Singapore) will drastically reduce latency.

Conclusion

The Hyperliquid API Websocket is a powerful tool for developers. It provides the low-latency data stream necessary for algorithmic trading and real-time market analysis. By understanding the architecture—connecting, subscribing, authenticating, and handling the data—you can build robust systems that interact seamlessly with the Hyperliquid engine.

Remember, the Websocket is only as good as your connection management. Implement solid reconnection logic, keep your subscriptions lean, and always verify your local state against the REST API.

If you are just getting started with Hyperliquid and haven't set up your account yet, you can Sign up on Hyperliquid to get access to the API and start building.

FAQ

Can I place orders directly over the Hyperliquid Websocket?

What happens if my Websocket connection drops?

Do I need to authenticate to see public data like the order book?

How often does the l2Book channel update?

Is the Websocket API available on Hyperliquid Testnet?

Continue with Hyperliquid

Browse the Hyperliquid guide hub for the complete user journey.