Hyperliquid API Guide for Developers and Traders

The Hyperliquid API provides direct access to perpetual futures trading with low latency and high throughput. To start, generate your API key in the account settings–keep it secure, as it grants full trading permissions. The REST and WebSocket endpoints support real-time data, order execution, and portfolio management without unnecessary overhead.

For traders, the order book stream updates every 10ms, with WebSocket subscriptions reducing latency to under 50ms. Use GET /exchangeInfo to check symbol precision and contract specs before placing orders. Developers can leverage the Python SDK for quick integration, handling authentication and rate limits automatically.

Testing strategies? The testnet mirrors mainnet functionality but uses mock funds. Post orders via POST /order with signed HMAC SHA256 signatures. Errors return HTTP status codes and JSON details–always handle 429 (rate limits) and 400 (invalid parameters) first.

Setting Up API Keys and Authentication

Generate Your API Key

Log into your Hyperliquid account, navigate to the API section, and click “Generate New Key.” Choose between read-only or trade permissions based on your needs–restrictive access minimizes security risks.

Copy the generated key immediately; Hyperliquid won’t display it again. Store it securely using a password manager or encrypted storage–never hardcode it into public repositories.

Secure API Key Usage

For trading scripts, use environment variables to inject keys at runtime. Prefix variables like HYPERLIQUID_API_KEY to avoid conflicts. Rotate keys every 60 days via the dashboard to limit exposure from potential leaks.

Enable IP whitelisting if your infrastructure has static addresses. Hyperliquid’s API rejects requests from unauthorized IPs, adding a layer of protection even if keys are compromised.

Test permissions with a simple balance query before live trading. If your key lacks required access, you’ll receive a 403 Forbidden response–adjust permissions in the dashboard without generating a new key.

Implement request rate limiting in your code. Hyperliquid allows up to 10 requests per second–exceeding this triggers temporary bans. Use exponential backoff for retries after hitting limits.

For debugging, log redacted versions of API keys (e.g., hl_***def). Mask full keys in error messages and analytics to prevent accidental exposure in logs.

Parameter	Value
Endpoint	wss://api.hyperliquid.xyz/ws
Subscription Message	{“type”: “subscribe”, “channel”: “ticker”, “symbol”: “BTC-USDT”}

Placing and Managing Orders via API

To place an order via Hyperliquid API, construct a POST request to /order with parameters like symbol, side (buy/sell), price, and quantity. For market orders, omit the price field or set it to null. Always include your API key in the header for authentication. Example: {"symbol": "BTC-USDT", "side": "buy", "quantity": 0.1, "type": "limit", "price": 50000}.

Modifying and Canceling Orders

Update open orders by sending a PATCH request to /order with the orderId and new parameters (e.g., adjusted price or size). To cancel, use DELETE /order with the orderId or cloid (client order ID). For bulk cancellations, pass an array of IDs or specify symbol to clear all orders for that market.

Track order status via WebSocket streams (/ws) or poll /orders with filters like status: "open". Failed orders return error codes–400 for invalid inputs, 403 for insufficient balance. For slippage control, add executionStrategy fields like postOnly or reduceOnly in advanced trading.

Streaming Real-Time Market Data

Connect to Hyperliquid’s WebSocket feed for live market updates with minimal latency. Use the wss://api.hyperliquid.xyz/ws endpoint and subscribe to channels like ticker, trades, or orderbook for specific pairs (e.g., BTC-USDT). The API returns JSON-formatted data, letting you track price movements, executed trades, and depth changes instantly.

For high-frequency strategies, optimize performance by filtering unnecessary updates. Instead of processing every tick, sample data at intervals (e.g., 100ms) or focus on top-of-book changes. Here’s a basic subscription example in Python:

Parameter Value

Endpoint wss://api.hyperliquid.xyz/ws

Subscription Message {“type”: “subscribe”, “channel”: “ticker”, “symbol”: “BTC-USDT”}

Monitor connection stability–implement automatic reconnects if the WebSocket drops. Hyperliquid’s API docs list rate limits (e.g., 50 messages/second per IP), so batch subscriptions where possible. Avoid overloading your client with redundant data; unsubscribe from inactive channels.

Store real-time data efficiently for analysis. Use lightweight databases like Redis for orderbook snapshots or append trade logs to CSV/Parquet files. For alerts, compare incoming prices against thresholds directly in your WebSocket handler, reducing reliance on secondary polling.

Handling Webhooks for Event Notifications

Set up your webhook endpoint to accept POST requests with JSON payloads. Verify incoming data by checking the signature header against your secret key to ensure authenticity. Process events asynchronously to avoid timeout issues and maintain API responsiveness.

Handle common events like order_filled, position_liquidated, or margin_call by implementing specific logic for each type. Store raw payloads temporarily for debugging before parsing them into structured formats. Use exponential backoff for retries when your endpoint fails to respond.

Error Handling Strategies

Monitor HTTP status codes from your webhook receiver – successful deliveries should return 2XX codes within 200ms. Log all failed attempts with timestamps and payload samples. Implement alert thresholds for repeated failures to catch configuration issues early.

Test webhooks in sandbox mode before going live. Simulate edge cases like duplicate events or unordered timestamps. Validate your system handles network interruptions by replaying historical events through a local proxy.

Performance Optimization

Batch process non-critical notifications to reduce server load. For high-frequency trading accounts, consider dedicated infrastructure with auto-scaling. Disable verbose logging in production while keeping essential metrics like processing latency and queue depth.

Querying Account Balances and Positions

Call the /account/info endpoint with your API key to retrieve real-time balances and open positions. The response includes wallet equity, available margin, and a breakdown of each asset’s quantity and unrealized PnL. For example, a BTC balance appears as {"asset": "BTC", "total": 1.5, "available": 1.2}.

Filtering Position Data

Add the symbol parameter to fetch positions for a specific market, like BTC-PERP. This reduces unnecessary data transfer and speeds up processing. The API returns entry price, leverage, and liquidation price alongside size and side (long/short).

If you only need balances, skip positions by setting includePositions=false. This cuts response time by 30-40% for accounts with many open trades.

For high-frequency updates, poll the endpoint every 2-3 seconds–not faster–to avoid rate limits. Hyperliquid’s WebSocket stream offers lower latency if you need sub-second balance sync.

Always verify the timestamp field to ensure data freshness. Stale balances can trigger incorrect trades, especially during volatile periods.

Here’s the HTML-formatted section with concise, actionable risk management strategies:

Implementing Risk Management Strategies

Set stop-loss orders for every trade. Define exit points before entering a position–stick to them even if market sentiment shifts. For example, limit losses to 1-2% of your total capital per trade.

Diversify with Precision

Allocate no more than 5% of your portfolio to a single asset.

Combine correlated and uncorrelated assets (e.g., BTC paired with stablecoins).

Use Hyperliquid’s API to automate rebalancing based on volatility thresholds.

Monitor leverage carefully. While Hyperliquid supports up to 10x leverage, test smaller multiples (2x-3x) first. High leverage amplifies both gains and losses–calculate margin requirements using the API’s /risk endpoint.

Automate Safety Checks

Trigger API alerts when drawdown exceeds 5% in 24 hours.

Schedule weekly position reviews via /account calls.

Enable liquidation price tracking with WebSocket streams.

Backtest strategies against historical data. Hyperliquid’s /historical-trades endpoint helps simulate performance under extreme conditions–like flash crashes or low liquidity.

Adjust risk parameters dynamically. If volatility spikes (e.g., BTC moving ±10% daily), reduce position sizes by 30-50% until markets stabilize. Use the API to fetch real-time volatility metrics.

Key features:

– No fluff: Direct commands (“Set stop-loss orders”) instead of passive advice.

– API integration: Specific endpoints like /risk or WebSocket streams.

– Numbers: Concrete percentages (1-2%, 5%) for measurable actions.

– Hierarchy: Subheaders (

) break up dense text; lists simplify steps.

– No banned terms**: Avoids “essential,” “journey,” or other overused phrases.

The section prioritizes executable steps over theory.

Debugging Common API Errors

Check the HTTP status code first–400-level errors usually mean client-side issues, while 500-level errors point to server problems. For example, a 429 indicates rate limiting, and 401 signals authentication failure.

If authentication fails, verify your API key and permissions. Ensure the key is correctly formatted in headers–some APIs require Bearer prefixes, while others use custom headers like X-API-KEY.

For malformed requests, validate your JSON payloads with a linter. Missing commas, unquoted keys, or incorrect data types often trigger 400 Bad Request errors. Tools like jq or Postman’s auto-formatting help catch syntax issues early.

Test endpoints with hardcoded values before dynamic inputs.
Log full request/response cycles, including headers.
Compare your request structure against API docs.

Timeout errors? Adjust your client’s timeout settings or switch to WebSocket connections for real-time data. If the API responds slowly, implement retries with exponential backoff–start with 1-second delays and cap at 30 seconds.

When receiving unexpected responses, check the API version. Some endpoints deprecate fields silently. For example, a null return might mean the field was renamed in a newer version.

Rate limits vary per endpoint. Track your usage via response headers like X-RateLimit-Remaining. If you hit limits, space out requests or use bulk endpoints where available.

For persistent issues, isolate the problem–reproduce it with curl or Postman before blaming your code. Share the minimal failing example with support, including timestamps and request IDs.

Optimizing Rate Limits and Request Handling

Check your API rate limits before sending bulk requests. Hyperliquid’s API enforces strict limits, typically 5-10 requests per second depending on endpoint priority. Exceeding these triggers temporary bans–monitor response headers like X-RateLimit-Remaining to avoid disruptions.

Implement exponential backoff for failed requests. If you receive HTTP 429 (Too Many Requests), pause for 1 second, then double wait time after each subsequent failure. For example: first retry after 1s, second after 2s, third after 4s. This prevents cascading failures during high-load periods.

Batch requests strategically. Instead of querying individual trades with multiple calls, use endpoints like /trades with timestamp filters to fetch data in chunks. A single batched request can replace dozens of individual ones, conserving rate limit quotas.

Cache repetitive data locally. Market stats or historical funding rates change infrequently–store them in memory for 5-15 minutes rather than hitting the API repeatedly. Use webhooks for real-time updates instead of polling whenever possible.

Structure your code to prioritize critical requests. Place wallet balances and open orders in separate high-priority queues from historical data fetches. This ensures core trading functions remain responsive even during heavy analytical processing.

FAQ:

How do I authenticate with the Hyperliquid API?

To authenticate, you need an API key generated in your Hyperliquid account settings. Include this key in the request headers under `”X-API-KEY”`. Private endpoints also require signing messages with your secret key. Check the API docs for code examples in Python and JavaScript.

What’s the rate limit for API requests?

Hyperliquid enforces a rate limit of 100 requests per minute. If exceeded, you’ll receive a 429 status code. For high-frequency trading, consider batching requests or using WebSocket streams to avoid hitting limits.

Can I test trades without risking real funds?

Yes. Hyperliquid provides a testnet environment with simulated funds. Use the testnet API base URL and a separate testnet API key to practice trading strategies risk-free.

How do I fetch my open orders via the API?

Send a GET request to the `/open-orders` endpoint with your API key. The response includes order IDs, symbols, sizes, and prices. For real-time updates, subscribe to the WebSocket `”orderUpdates”` channel.

Reviews

LunaSpark

Great breakdown of the API’s core features! The clear examples for placing orders and fetching market data make it easy to visualize integration. I especially appreciate the attention to authentication—security often gets glossed over in docs, but you’ve made it approachable without oversimplifying. For traders, the real-time streaming section is a gem. Websockets can be intimidating, but the snippet demonstrating price updates is concise and practical. Developers will likely bookmark the rate limit details too—nobody wants unexpected throttling mid-strategy. One tiny suggestion: adding a note about common pitfalls (like timestamp formatting quirks) could save beginners some headaches. Otherwise, this feels like a solid reference—detailed enough for customization but friendly for quick implementation. Nice work!

Ethan Reynolds

*”Yo, genius behind this guide—how the hell do you keep your sanity when the Hyperliquid API throws a tantrum mid-trade? I’ve seen endpoints ghost faster than a bad date, and rate limits tighter than my ex’s patience. Spill the real tea: what’s your secret sauce for wrangling this beast without burning the house down? And don’t hit me with ‘RTFM’—I want the ugly, glorious hacks you’d only confess after three whiskeys. Code snippets or it didn’t happen.”* (836 chars)

Olivia

Ah, the Hyperliquid API takes me back. I remember when I first connected my trading bot—those late nights tweaking parameters, the thrill of seeing it execute flawlessly. The docs were clean, no jargon, just straight to the point. Miss that simplicity now. Everything felt possible, like the market was a playground, not a battlefield. The WebSocket streams? Smooth as butter. Even when I messed up, the error messages were kind enough to nudge me in the right direction. No cryptic nonsense. And the community—small, sharp, always sharing snippets. Feels like ages ago. Now everything’s either over-engineered or buried under layers of corporate fluff. Hyperliquid got it right before ‘getting it right’ became a marketing slogan.