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 30+ Hyperliquid-specific guides (recent examples: Hyperliquid Python SDK Tutorial, Hyperliquid API Key Setup, Hyperliquid Latency Optimization). The most-repeated reader question across that Hyperliquid archive is exactly how to handle websocket dropouts and missed fills, which is why I'm publishing this standardized guide instead of answering one-off.
If you have ever run an algorithmic trading bot on Hyperliquid, you have likely encountered the dreaded "missed fill." Your bot was running, the order was placed, but suddenly the websocket connection dropped, and when it reconnected, your fill data was missing or out of sync.
For algo traders, a missed fill is a silent killer. It doesn't just mean a lost trade; it means your bot's internal state diverges from the actual exchange state. If your bot thinks a position is open but it was actually closed, your risk management logic will fail catastrophically.
The Hyperliquid community has heavily debated this issue, particularly around session health checks and reconnect support (as highlighted in ongoing discussions within the Hyperliquid Python SDK GitHub repository). In 2026, with the maturation of the Hyperliquid API and the Python SDK, there are proven ways to handle these dropouts gracefully.
This guide breaks down exactly why websockets drop on Hyperliquid, how to implement robust session health checks, and the exact architecture you need to prevent missed fills during reconnects.
Why Hyperliquid Websockets Drop (And Why It's Not Just a Bug)
Before we can fix the reconnect issue, we have to understand why it happens. Many new algo traders assume that a websocket connection should be as stable as a REST API. This is a fundamental misunderstanding of real-time data streams.
Hyperliquid is a high-performance decentralized exchange. Its matching engine processes thousands of orders per second. To deliver this data to your machine, it uses websockets. Websockets are stateful, long-lived connections. Unlike a REST request, which is stateless and closes immediately after the response, a websocket remains open.
Because they remain open, they are vulnerable to network-level interruptions. Here are the primary reasons websockets drop on Hyperliquid:
- Network Instability: If your internet connection hiccups for even a fraction of a second, the TCP handshake breaks. The websocket drops.
- Server-Side Resets: Hyperliquid's infrastructure scales dynamically. During periods of extreme volatility (like a sudden crash in BTC), the server may reset websocket connections to rebalance load.
- Idle Timeout: If your bot is not sending or receiving data within a certain timeframe, the server may close the connection to free up resources.
- SDK Limitations: The official Python SDK has historically had gaps in its automatic reconnect logic. If the SDK crashes or fails to handle an exception, the connection is lost.
user_fills channel, and a fill occurred during the dropout, you will never receive that fill notification via websocket. You have missed a fill.
The Danger of Missed Fills in Algo Trading
Why is a missed fill so dangerous? Let's look at a practical scenario.
Imagine you are running a market-making bot on Hyperliquid. Your bot places a limit buy order for ETH-PERP. The order fills. The fill notification is sent via websocket, but your internet connection drops at that exact millisecond.
Your bot's internal state still thinks the order is open. It continues to place more limit buy orders, unaware that it has already bought ETH. When the connection restores, your bot is now over-leveraged. If the market turns against you, your margin is wiped out.
This is why the community has pushed for better session health checks and reconnect logic. You cannot rely on websockets alone for state management. You must have a reconciliation mechanism.
Step 1: Implementing Robust Session Health Checks
A session health check is a mechanism to verify that your websocket connection is alive and actively receiving data. If the connection is dead, your bot needs to know immediately so it can attempt a reconnect.
Many bots fail because they assume the websocket is alive as long as the connection object exists in memory. This is false. A "zombie" connection can exist where the socket is open, but data is no longer flowing.
To implement a health check, you need a heartbeat.
The Heartbeat Mechanism
In your Python script, initialize a variable to track the last time you received a valid message from Hyperliquid.
import time
last_message_time = time.time()
HEARTBEAT_TIMEOUT = 10 # seconds
Every time your websocket callback receives a message from Hyperliquid, update the timestamp:
def on_message(ws, message):
global last_message_time
last_message_time = time.time()
# process message
Like what you're reading? Try it yourself — this link supports ChartedTrader at no cost to you.
Sign up on Hyperliquid →In your main event loop, continuously check if the time since the last message exceeds the timeout:
while True:
if time.time() - last_message_time > HEARTBEAT_TIMEOUT:
print("Session health check failed. Reconnecting...")
handle_reconnect()
time.sleep(1)
This ensures that if Hyperliquid's server stops sending data (even if the TCP connection is technically open), your bot will detect the stagnation and trigger a reconnect.
Step 2: The Reconnect Logic
When a reconnect is triggered, you cannot simply open a new websocket and assume you are back in sync. The state of the world has changed. You need a structured reconnect protocol.
1. Close the Old Socket Gracefully
Before opening a new connection, ensure the old one is fully closed. Attempting to open a new socket while the old one is still lingering can cause port conflicts or memory leaks in the Python SDK.2. Re-establish the Subscription
Reconnect to the Hyperliquid websocket endpoint and resubscribe to all required channels (user_fills, user_fills_v2, l2_book, etc.).
3. The Critical Step: State Reconciliation
This is the most important step that 90% of algo traders get wrong. When you reconnect, you must immediately query the REST API to fetch your current account state and recent fills.Websockets are for *notifications*. REST APIs are for *truth*.
After reconnecting, issue a REST request to Hyperliquid's API to fetch your recent order history and fill history. Compare this data against your bot's internal state.
# Pseudo-code for reconciliation
def reconcile_state():
recent_fills = hyperliquid_api.get_recent_fills()
for fill in recent_fills:
if fill not in internal_fill_log:
process_missed_fill(fill)
By doing this, you catch any fills that occurred during the dropout. You are no longer relying on the websocket to tell you what happened; you are asking the exchange directly.
Step 3: Handling the Python SDK Limitations
The Hyperliquid Python SDK is a great tool, but it is not a silver bullet. As noted in the community discussions, the SDK's native reconnect logic has historically been fragile.
If you are using the official SDK, do not rely on its built-in auto_reconnect flag if it exists. Instead, wrap the SDK's websocket connection in your own try/except blocks and custom reconnect handlers.
When the SDK throws an exception (like a connection timeout), catch it, log it, and trigger your custom reconnect protocol (Health Check -> Close -> Re-subscribe -> Reconcile).
Furthermore, be mindful of rate limits. If your bot is aggressively reconnecting every second because of a flaky network, you might hit Hyperliquid's rate limits, which will cause your REST reconciliation requests to fail. Implement exponential backoff in your reconnect logic.
import time
def handle_reconnect(attempt=1):
delay = min(2 ** attempt, 60) # Exponential backoff, max 60 seconds
print(f"Reconnect attempt {attempt}. Waiting {delay} seconds...")
time.sleep(delay)
# Attempt to reconnect
Step 4: Architectural Best Practices for 2026
If you are building a serious algo trading infrastructure on Hyperliquid in 2026, your architecture must be resilient. Here are the best practices to implement:
Decouple the Data Stream from the Trading Logic
Your websocket listener should be a separate process or thread from your trading logic. If the websocket drops and crashes, it should not take down your entire trading engine.Use a Local Database for State
Never store your bot's state in memory. If your bot crashes, memory is wiped. Use a local database (like SQLite or Redis) to store your internal fill log and order state. When you reconnect and reconcile, you can query the database to see what you have already processed.Monitor the user_fills_v2 Channel
Hyperliquid has updated its websocket channels over time. Ensure you are subscribed to the user_fills_v2 channel, which provides more detailed and reliable fill data than the legacy channels.
Conclusion
Missed fills are the bane of algo trading on Hyperliquid. However, they are not an unsolvable problem. By implementing strict session health checks, building a robust reconnect protocol, and—most importantly—reconciling your state with the REST API after every dropout, you can eliminate the risk of missed fills.
The key takeaway is this: websockets are unreliable. REST is reliable. Always verify your state with the exchange, never assume the websocket is the source of truth.
If you are just getting started with Hyperliquid and want to set up your account with the best possible conditions, you can use our referral link to get a 4% fee discount on your first $25M in volume.
Sign up on HyperliquidFAQ
What should I do if my Hyperliquid websocket drops frequently?
Frequent drops are usually a network issue or a server-side scaling event. Implement exponential backoff in your reconnect logic to avoid hammering the server, and ensure your machine's network connection is stable. If the drops are localized to specific times, it might be related to Hyperliquid's server maintenance or high volatility periods.Can I rely solely on the Hyperliquid Python SDK to handle reconnects?
No. The SDK is a helpful wrapper, but its native reconnect logic is not foolproof. You should implement your own session health checks and custom reconnect handlers to ensure your bot can recover gracefully from dropouts without missing critical state updates.How do I know if a fill occurred while my connection was down?
You must query the Hyperliquid REST API for your recent fill history immediately after reconnecting. Compare the fills returned by the API to your local database. Any fills present in the API response but missing from your local database occurred during the dropout.Does the 4% Hyperliquid referral discount apply to my bot trading?
Yes. The 4% fee discount applies to all trading activity on your account, including algorithmic trading via the API. It applies to your first $25M in trading volume per account.Is it safe to use the user_fills_v2 channel for production bots?
Yes. The user_fills_v2 channel is the current standard for real-time fill notifications on Hyperliquid. It provides more granular data than the legacy channels and is recommended for all production-level algorithmic trading bots.
Risk Warning
Risk Warning: Crypto trading involves substantial risk of loss. Never invest more than you can afford to lose. This is not financial advice. Algorithmic trading carries additional risks, including technical failures, missed fills, and rapid liquidations. Always test your bots on paper or with minimal capital before deploying significant funds.