Hyperliquid REST vs WebSocket: When to Use Each

Many developers building on the Hyperliquid API run into the same question early: should my strategy use REST or WebSocket? Source: Hyperliquid docs. Source: WalletConnect. Source: GitHub.

The two interfaces solve different problems. Pick the wrong one and you may waste bandwidth, hit rate limits, or react too slowly to fast markets. In a perps environment, that can mean worse fills and more slippage than expected.

This guide breaks down how REST and WebSocket work on Hyperliquid, where each one fits, what latency trade-offs to expect, and the common implementation traps to avoid.

REST API: request-response by design

REST, or Representational State Transfer, is the classic HTTP request-response model. Your client sends a request, the server returns a response, and the interaction ends.

Hyperliquid’s REST API is generally split into two endpoint categories:

• Info endpoint (/info): read-only queries such as market metadata, historical trades, order book snapshots, funding history, and account state. These requests do not require a signature.
• Exchange endpoint (/exchange): write operations such as placing orders, canceling orders, changing leverage, and adjusting margin. These requests require an EIP-712 structured signature, and the server verifies that the signature matches the account.

When REST makes sense

REST is best when you need a specific answer at a specific moment.

Common use cases include:

• Loading current positions when a strategy starts
• Checking account balances periodically
• Pulling a funding-rate history for a market
• Fetching historical trades or candles for backtesting
• Submitting orders and cancellations through the Exchange endpoint

Even if your strategy uses WebSocket for real-time data, actual trading instructions still go through REST. On Hyperliquid, order placement and cancellation are submitted to the Exchange endpoint with the required signature.

REST also works well for batch historical data. For example, if you are downloading trades or candle data for a backtest, paginated REST calls are usually straightforward and reliable.

REST limitations

REST is a pull model. The server does not tell you when something changes; your client has to ask.

That creates an obvious problem for real-time trading systems. If you poll the order book every 100 milliseconds, you may hit rate limits or waste bandwidth. If you poll once per second, you may be too slow during volatile markets.

For strategies that need to react to live order book changes, aggressive REST polling is usually both inefficient and fragile.

WebSocket: persistent connection and live updates

WebSocket is a full-duplex protocol. After a connection is established, the server can push updates to the client without the client repeatedly sending HTTP requests.

Hyperliquid’s WebSocket endpoint is:

wss://api.hyperliquid.xyz/ws

After connecting, the client sends subscription messages for the data it wants. The server then streams matching updates until the connection is closed or the client unsubscribes.

When WebSocket makes sense

WebSocket is the right choice when your strategy depends on live data.

Typical use cases include:

• Real-time order book monitoring: subscribing to l2Book lets a strategy track market depth changes as they happen.
• Live trade stream analysis: the trades channel can help monitor execution flow, market impact, and short-term sentiment.
• Account event tracking: userEvents can notify your system about fills, liquidations, and other account-level events without constant polling.
• Funding-rate monitoring: useful for basis or funding-aware strategies that need to react when funding data changes.

For perps traders, WebSocket is often what makes the strategy feel “live.” It reduces the need for repeated REST queries and gives the system a more current view of the market.

WebSocket caveats

WebSocket is powerful, but it requires more operational care than simple REST calls.

The first challenge is connection stability. Network interruptions, server restarts, or long idle periods can disconnect your client. A production system should implement:

• Heartbeats or ping/pong handling
• Automatic reconnect logic
• Re-subscription after reconnecting
• State recovery for data missed during downtime

The second challenge is message throughput. High-traffic feeds, especially liquid L2 order books, can produce a large number of messages. If your parser or strategy logic cannot keep up, messages will queue up and your “real-time” data becomes stale.

In practice, you should monitor queue depth, processing latency, and reconnect frequency—not just whether the socket is technically connected.

REST vs WebSocket comparison

Code example: REST order book snapshot

import requests

response = requests.post(
    "https://api.hyperliquid.xyz/info",
    json={"type": "l2Book", "coin": "ETH"}
)

book = response.json()
print(book)

This fetches the current ETH order book snapshot once. It will not keep updating automatically.

Code example: WebSocket order book subscription

import asyncio
import json
import websockets

async def stream_orderbook():
    uri = "wss://api.hyperliquid.xyz/ws"

    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "l2Book", "coin": "ETH"}
        }))

        async for message in ws:
            data = json.loads(message)
            # Handle each live order book update here
            print(data)

asyncio.run(stream_orderbook())

The difference is simple: REST gives you one snapshot; WebSocket keeps streaming updates until the connection ends.

Order signing and OneKey integration

Whether you use REST for orders or WebSocket for account monitoring, write operations require EIP-712 signatures. The signing key is the security boundary of the account.

OneKey helps isolate that signing risk. With OneKey hardware wallets, private keys are stored inside the device’s secure element, and signing happens on the device. Strategy code running on your computer does not receive the raw private key.

A practical workflow looks like this:

1. Your strategy builds the transaction or order request that needs signing.
2. The signing request is sent to OneKey through a wallet connection flow.
3. You review and confirm on the OneKey device.
4. The signature is returned to the strategy.
5. The strategy submits the signed request to Hyperliquid’s Exchange endpoint.

This model is better suited to low- and mid-frequency strategies because it includes a human confirmation step. Fully automated high-frequency systems need a different risk model, typically involving isolated hot wallets and strict position limits.

For most users who want Hyperliquid perps access without managing custom infrastructure, OneKey Perps is the more practical path. It gives you a wallet-native workflow for trading perps while keeping key management separate from exchange accounts. Download OneKey, set up your wallet, and try OneKey Perps with small size first so you can understand the flow and risks before increasing exposure.

Best practice: use REST and WebSocket together

In production, REST and WebSocket are usually complements, not substitutes.

A typical Hyperliquid trading architecture may look like this:

• Use WebSocket for live market data such as L2 order books, trades, and user events.
• Use REST for order placement, cancellation, leverage changes, and margin updates.
• On startup, use REST to fetch account state and open positions.
• After a WebSocket reconnect, use REST to refresh the current state.
• Periodically reconcile account state through REST to catch any missed WebSocket events.

This hybrid pattern takes advantage of each interface: REST for reliable point-in-time state and write operations, WebSocket for real-time streaming.

FAQ

Q1: If I only run a simple scheduled order strategy, do I need WebSocket?

Usually, no. If your strategy only places orders at scheduled times, REST is enough. You can query the current price and account state with REST, build the order, sign it, and submit it through the Exchange endpoint.

Adding WebSocket in this case may only increase maintenance complexity.

Q2: If WebSocket disconnects, how do I know what I missed?

This is a standard WebSocket problem. The common approach is to reconnect, then immediately fetch the full current state through REST—such as the latest order book snapshot and account positions—and treat that as the new baseline.

For trade history, you can query the missing time window after reconnecting if the data is available through the relevant REST endpoint.

Q3: What is the delay between REST order submission and fill confirmation?

A REST order response generally confirms that the order was accepted, not necessarily that it was filled. Fill updates can be received through WebSocket userEvents, or by polling account/order state again.

Actual timing depends on network conditions, market conditions, and Hyperliquid’s execution flow. It is often very fast in normal conditions, but delays can happen during extreme volatility.

Q4: How many WebSocket connections should I open?

Keep the number of connections as low as practical. Consolidate subscriptions for the same account into a small number of connections, and follow the latest limits in Hyperliquid’s official documentation.

If multiple internal strategies need the same data, consider using one external WebSocket connection and distributing updates internally through your own message bus.

Q5: Anything special when debugging WebSocket code in Jupyter Notebook?

Yes. Jupyter’s event loop can conflict with asyncio.run(). You may need to use nest_asyncio and call nest_asyncio.apply() at the start of the notebook, or run the WebSocket code in a standalone Python script instead.

Conclusion

REST and WebSocket are not competing choices. They are tools for different jobs.

A simple rule of thumb:

• Use REST when you need data “right now” or need to submit a signed write operation.
• Use WebSocket when you need live updates as the market changes.

For Hyperliquid strategies, the most robust setup is usually a hybrid one: WebSocket for real-time data, REST for execution and reconciliation.

If you want a more practical wallet-native route, try OneKey and use OneKey Perps to access Hyperliquid perps with safer key separation and a cleaner trading workflow. Start small, test the full order and risk-management process, and only scale after you understand how the system behaves.

Disclaimer

This article is for technical education only and is not investment, financial, legal, or tax advice. Automated trading systems can fail because of bugs, network issues, infrastructure outages, or incorrect assumptions. Perpetual futures and leveraged trading are high risk and can lead to significant losses. Trade only after assessing your own technical ability and risk tolerance.