user_fills or user_fills_by_time API responses, you are likely dealing with the HIP-3 transition. Specifically, the dex parameter—which is crucial for filtering fills across different decentralized exchange venues within the Hyperliquid ecosystem—has been reported as missing or malfunctioning in several API calls.
This issue has caused significant friction for algorithmic traders who rely on accurate fill data to reconcile their portfolios, calculate realized PnL, and manage risk across multiple chains or venues. GitHub issue #287 highlights this exact problem, with developers noting that the user_fills endpoint no longer reliably returns the dex parameter as expected under the new HIP-3 specification.
In this guide, we will break down what HIP-3 is, why the dex parameter is missing in your API responses, and most importantly, how to fix your code and work around the current limitations. Whether you are using the Python SDK, querying the REST API directly, or interacting with the WebSocket, this guide will help you get your data pipeline back on track.
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 Missing Fills Reconciliation). The most-repeated reader question across that Hyperliquid archive is exactly HIP-3 API parameter issues, which is why I'm publishing this standardized guide instead of answering one-off.
What is HIP-3 and Why Does It Matter?
Hyperliquid Improvement Proposals (HIPs) are the formal process by which the Hyperliquid ecosystem introduces changes, upgrades, and new features. HIP-3 specifically addresses the standardization of how fill data is reported across the Hyperliquid API.
Historically, Hyperliquid operated as a single, monolithic order book. However, as the ecosystem expanded—incorporating various perpetual contracts, spot assets, and cross-chain integrations—the need to distinguish which specific decentralized exchange (DEX) venue executed a trade became critical. The dex parameter was introduced to allow developers to filter their fill history by the specific venue where the trade occurred.
For algorithmic traders, knowing the dex venue is essential. Different venues have different fee schedules, and tracking fills by dex helps isolate slippage per venue. If you're matching on-chain transactions with off-chain API data, you need that precise venue identification.
When HIP-3 rolled out, the intention was to make this data more robust. However, the transition period has been rocky, leading to the missing dex parameter bug that many developers are currently facing.
The Core Issue: Missing dex Parameter in user_fills
The problem manifests primarily in two endpoints: user_fills and user_fills_by_time. When you query these endpoints, the response payload should include a dex field for each fill object, indicating the decentralized exchange venue where the trade was executed.
Under HIP-3, this field is expected to be populated. However, users report that:
- The
dexfield is completely absent from the JSON response. - The
dexfield is present but returnsnullor an empty string. - Filtering requests by
dexparameter return no results, even when fills on that venue are known to exist.
dex parameter will cause your script to throw a KeyError or miscalculate your overall portfolio performance.
How to Fix Your Code: Immediate Workarounds
Since the HIP-3 transition is still settling, waiting for a full backend fix might not be an option for live trading systems. Here are the most effective workarounds to fix your code immediately.
1. Defaulting the dex Parameter
If your bot is currently crashing because it expects a dex key, the quickest fix is to implement a fallback mechanism. Instead of directly accessing fill['dex'], use a default value.
# Instead of this:
venue = fill['dex']
# Use this:
venue = fill.get('dex', 'hyperliquid_main')
By using .get(), you prevent the bot from crashing. You can assign a default venue (like 'hyperliquid_main') to ensure your PnL calculations continue to run. While this isn't perfectly accurate if fills are actually happening across multiple venues, it keeps your system operational.
2. Inferring the Venue from Asset Metadata
If you are trading on multiple venues and need accurate venue data, you can infer the dex parameter from the asset itself. Hyperliquid's API returns the coin or asset field for every fill. If you know which assets are traded on which venues, you can create a mapping dictionary.
venue_mapping = {
'BTC': 'hyperliquid_main',
'ETH': 'hyperliquid_main',
'SOL': 'hyperliquid_main',
'SPX': 'hyperliquid_equity',
'AAPL': 'hyperliquid_equity'
}
def get_venue_from_fill(fill):
coin = fill.get('coin', '')
return venue_mapping.get(coin, 'unknown_venue')
# Usage
venue = get_venue_from_fill(fill)
This approach requires you to maintain the venue_mapping dictionary as new assets are added, but it is highly reliable and doesn't depend on the buggy dex parameter.
Like what you're reading? Try it yourself — this link supports ChartedTrader at no cost to you.
Start Trading on Hyperliquid →3. Switching to WebSocket for Real-Time Data
If you are using the REST API (user_fills or user_fills_by_time) and encountering missing data, consider switching to the WebSocket API for real-time fill notifications. The WebSocket stream often bypasses the REST API's serialization layer, which is where the HIP-3 dex parameter bug seems to be most prevalent.
When you subscribe to the user_fills channel via WebSocket, the fill objects are pushed to you in real-time. In many cases, the dex parameter is correctly populated in the WebSocket payload, even when it's missing in the REST response.
import json
import websocket
def on_message(ws, message):
data = json.loads(message)
if 'data' in data:
fill = data['data']
venue = fill.get('dex')
if venue:
print(f"Fill on venue: {venue}")
else:
print("Dex parameter still missing in WebSocket!")
ws = websocket.WebSocketApp("wss://api.hyperliquid.xyz/ws")
ws.on_message = on_message
ws.run_forever()
Understanding the HIP-3 Transition Timeline
HIP-3 isn't exactly a bug; it's a transitional state. The Hyperliquid team is actively migrating the backend infrastructure to support multi-venue fill tracking.
During this migration, the REST API endpoints are being updated to accommodate new data structures. The dex parameter is being introduced to replace legacy venue identifiers. Because the database schema is changing, there are periods where the dex field is not yet populated for older fills, or where the REST API serialization fails to include the new field.
The Hyperliquid team has acknowledged this issue on GitHub and in community channels. They are working on a patch to consistently populate the dex parameter for new fills, backfill historical data, and synchronize the REST and WebSocket APIs.
Until this patch is fully deployed and stable, developers should expect intermittent issues with the dex parameter.
Best Practices for Hyperliquid API Development
Dealing with API transitions like HIP-3 is a common reality for crypto developers. To future-proof your trading bots and minimize downtime, consider adopting the following best practices:
1. Implement Robust Error Handling
Never assume an API response will always contain the fields you expect. Use defensive programming techniques. In Python, use .get() with default values. In JavaScript, use optional chaining (fill?.dex). This ensures that a missing parameter doesn't crash your entire trading loop.
2. Log and Monitor API Responses
Set up logging for your API responses. If the dex parameter starts returning null or disappears entirely, you want to know immediately. Use a monitoring tool (like Prometheus, Grafana, or even a simple Slack bot) to alert you when API response structures change unexpectedly.
3. Use Local Caching for Metadata
As mentioned in the workarounds, maintaining a local mapping of assets to venues is highly recommended. This way, if the API fails to provide the dex parameter, your bot can still function using locally cached metadata. Update this cache periodically by polling the Hyperliquid API for asset information.
4. Stay Updated on HIPs
Hyperliquid Improvement Proposals are published on the official Hyperliquid forum and GitHub. Subscribe to these channels to get early warnings about API changes. HIP-3 was announced well in advance, but the transition period has been longer than expected. Being aware of upcoming HIPs allows you to update your code proactively rather than reactively.
Frequently Asked Questions
What is the dex parameter in Hyperliquid API?
The dex parameter identifies the specific decentralized exchange venue where a trade was executed. Under HIP-3, this parameter is used to distinguish between different venues within the Hyperliquid ecosystem, allowing for more granular tracking of fills.
Why is the dex parameter missing in my user_fills response?
The missing dex parameter is a known issue related to the HIP-3 transition. The Hyperliquid team is currently updating the backend infrastructure and REST API serialization to properly populate this field. In the meantime, the parameter may be missing, null, or empty in some responses.
How can I fix my bot if it relies on the dex parameter?
You can fix your bot by implementing a fallback mechanism. Use .get('dex', 'default_venue') in Python to prevent crashes. Alternatively, infer the venue from the asset metadata using a local mapping dictionary, or switch to the WebSocket API, which may have more reliable dex data.
Will historical fills be updated with the dex parameter?
Yes, the Hyperliquid team plans to backfill historical fills with the correct dex data as part of the HIP-3 transition. However, this process is ongoing, and you may still encounter missing data for older fills until the migration is fully complete.
Is HIP-3 affecting other API endpoints?
HIP-3 primarily affects fill-related endpoints likeuser_fills and user_fills_by_time. Other endpoints, such as order placement and market data, are generally unaffected. However, as the transition progresses, related endpoints may also experience minor changes.
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. API changes and bugs can lead to unexpected trading behavior, slippage, or missed fills. Always test your bots in a sandbox environment before deploying them with real capital.
Conclusion
The missing dex parameter in Hyperliquid's user_fills and user_fills_by_time endpoints is a frustrating but temporary issue tied to the HIP-3 transition. By understanding the root cause and implementing the workarounds outlined in this guide—such as defaulting the parameter, inferring the venue from asset metadata, or switching to WebSocket—you can keep your trading bots running smoothly.
As the Hyperliquid ecosystem continues to evolve, staying adaptable and proactive with API changes is crucial. Keep an eye on the official Hyperliquid channels for updates on HIP-3, and don't hesitate to use the workarounds provided here to maintain your trading edge.
If you're looking to start trading on Hyperliquid, you can sign up through our affiliate link to get a 4% fee discount on your trades.
Start Trading on Hyperliquid