Hyperliquid Developer API Guide Key Features and Integration Steps

To integrate Hyperliquid’s API, start by generating your API key in the account settings. Use the /auth/key endpoint with a POST request, and store the key securely–it won’t be displayed again. Hyperliquid’s REST API supports order placement, portfolio queries, and historical trade data with millisecond latency.

The WebSocket API streams real-time market data, including order book updates and liquidation events. Subscribe to channels like ticker or fills for live updates. For rate-limited endpoints, the API returns HTTP 429; implement exponential backoff to handle throttling gracefully.

Hyperliquid’s API differs from competitors by offering perpetual swaps with up to 50x leverage directly via code. Test integrations against the staging environment (api-staging.hyperliquid.xyz) before switching to production. Errors include structured JSON responses with code and message fields for debugging.

Setting Up API Authentication and Keys

Generate your API keys directly from the Hyperliquid developer dashboard under ‘API Settings’. Each key pair consists of a public access ID and a private secret key–store the secret securely, as it won’t be displayed again. For enhanced security, restrict key permissions to specific IP addresses and set expiration dates for temporary integrations.

Include the API key in every request header as X-API-KEY: [your_key]. For sensitive endpoints, Hyperliquid requires additional request signing: create a SHA-256 HMAC signature using your secret key, then pass it via the X-SIGNATURE header. Tools like Postman simplify testing by automating header injection.

Key Rotation & Best Practices

Rotate keys quarterly or immediately if exposure is suspected.
Never embed keys in client-side code or public repositories.
Use environment variables or secret management tools like Vault.

Connecting to Hyperliquid WebSocket Streams

Establish a WebSocket connection to wss://api.hyperliquid.xyz/ws for real-time market data. The endpoint supports JSON-formatted messages with subscription requests for order books, trades, or user-specific updates.

Send a subscription message immediately after connecting. For example, to stream BTC/USD orderbook updates:

Field	Value
method	subscribe
subscription	{“type”:”orderbook”,”coin”:”BTC”}

Handle connection drops by implementing exponential backoff. Reconnect attempts should start at 1-second intervals, doubling after each failure until reaching a 30-second maximum.

Process incoming messages with a non-blocking event loop. Each message contains a channel field identifying the data type. Parse updates like this:

{
"channel": "orderbook",
"data": {
"coin": "BTC",
"time": 1712345678901,
"bids": [[42000.5, 1.2], [41999.0, 0.8]],
"asks": [[42001.0, 0.5]]
}
}

Filter unnecessary data client-side to reduce processing load. If only tracking top-of-book prices, ignore order book levels beyond the first bid/ask entry.

Maintain connection stability by sending WebSocket pings every 30 seconds. Hyperliquid terminates idle connections after 60 seconds without activity.

For private streams like account balances, include an Authorization header with your API key during WebSocket initialization. Use the same signature generation method as REST API requests.

Monitor connection quality through timestamp deltas. Calculate the difference between local system time and message timestamps to detect latency issues exceeding 500ms.

Placing Orders via REST API Endpoints

Send a POST request to /api/v1/orders with the required parameters: symbol, side (buy/sell), type (limit/market), quantity, and price (if limit order). Use the X-API-KEY header for authentication.

For market orders, omit the price field–Hyperliquid automatically executes at the best available price. Always specify quantity in base asset units (e.g., BTC for BTC/USDC pairs).

Include an optional clientOrderId to track orders with your custom identifier. The API responds with orderId and status (open, filled, canceled).

Modify or cancel orders by sending a DELETE request to /api/v1/orders with the orderId or clientOrderId. Batch cancellations support up to 50 IDs per request.

Check rate limits: 100 requests per minute for order placement, 200 for reads. Exceeding limits triggers a 429 error–implement exponential backoff for retries.

For conditional orders, add triggerPrice and reduceOnly flags. Stop-loss and take-profit triggers execute as market orders when reached.

Test orders in sandbox mode by targeting https://testnet.api.hyperliquid.xyz. Validate responses for success: true before switching to production.

Handling Rate Limits and Throttling

Set up exponential backoff for failed API requests: start with a 1-second delay, then double it for each retry until you hit the cap (usually 5 attempts). Hyperliquid’s API enforces a 200-requests-per-minute limit–track your calls with a counter or use timestamp logs to stay compliant.

When throttled (HTTP 429), parse the Retry-After header for the exact wait time. If the header is missing, default to 15 seconds before retrying. For critical operations like order placement, queue requests instead of dropping them during rate limit spikes.

Use client-side caching for static data (e.g., market pairs) to reduce unnecessary calls.
Prioritize endpoints: trade execution > market data > historical queries.
Batch non-time-sensitive requests (e.g., fetching multiple account balances) into a single call.

Test limits in the staging environment first. Trigger a 429 response intentionally to verify your retry logic works. Hyperliquid’s API docs list endpoint-specific limits–liquidity checks allow 30 calls/minute, while trade submissions cap at 10.

For applications with high-frequency needs, like algorithmic trading, distribute requests across multiple IPs or API keys if permissible. Avoid client-side timers–they drift. Instead, sync with Hyperliquid’s server clock via the /time endpoint to align rate-limit windows.

Parsing Market Data Responses

Always validate the response structure before processing. Hyperliquid’s market data typically returns JSON with nested arrays for order books and trade history–check for mandatory fields like price, size, and timestamp to avoid null reference errors.

For order book snapshots, flatten the bids/asks arrays if you need a simplified view. Use Array.map() in JavaScript or list comprehensions in Python to extract price levels quickly. Example:

const bids = response.data.bids.map(entry => [entry.price, entry.volume]);

Handling WebSocket Streams

WebSocket updates arrive as delta patches. Merge them with your local order book copy by matching sequence IDs–overwrite existing prices or remove them if the size is zero. Missed a message? Fetch a fresh snapshot via REST.

Store timestamps in UTC and convert only for display. Hyperliquid uses microseconds in some endpoints (e.g., 1638451200000000). Divide by 1e6 before rendering human-readable time.

Optimize performance by caching repetitive data like instrument symbols. Parse once during initialization, then reference by ID (BTC/USDC → 1). This cuts JSON parsing time by ~30% in high-frequency scenarios.

Implementing Error Handling and Retries

Use HTTP status codes to detect API errors–codes like 429 (rate limit) or 503 (service unavailable) signal when to retry. Log the full error response, including headers, to diagnose issues faster.

For transient failures, implement exponential backoff. Start with a 1-second delay, then double it on each retry (e.g., 1s, 2s, 4s) up to a maximum of 5 attempts. This prevents overwhelming the server during outages.

Set a short timeout (3-5 seconds) for API calls. If the response takes longer, terminate the request and trigger a retry. Slow connections often resolve with a second attempt.

Distinguish between retriable and non-retriable errors. Network timeouts or HTTP 5xx errors usually justify a retry, but 4xx client errors (like 400 Bad Request) require code fixes instead.

Track retry metrics–count failures per endpoint and measure average retry duration. Tools like Prometheus or Datadog help spot recurring issues before they affect users.

For critical operations, add a dead-letter queue (DLQ). When retries fail, store the request payload in the DLQ for manual review or automated reprocessing later.

Test error handling by simulating failures. Mock API responses with tools like Postman or WireMock to verify retries work without hitting production systems.

Managing User Positions and Balances

Track open positions in real-time by subscribing to the /positions endpoint, which returns instrument details, entry price, and liquidation thresholds. For example, a typical response includes {"symbol": "ETHUSD", "size": 1.5, "entryPrice": 1850, "liqPrice": 1720}. Use this data to auto-close positions if the market moves against users beyond predefined limits.

Balances update asynchronously during volatile markets. The table below shows recommended polling intervals:

Scenario	Polling Frequency
High leverage (10x+)	Every 500ms
Spot trading	Every 2s
Portfolio checks	Every 30s

Implement client-side balance caching with versioning to handle race conditions. When withdrawing, compare local balance v2 with the API’s v3 response–reject transactions if versions mismatch to prevent overdrafts. For margin accounts, always cross-verify collateral ratios before order placement using /risk endpoints.

Subscribing to Real-Time Order Updates

Enable WebSocket connections to receive live order updates from Hyperliquid API. Use the /ws endpoint and authenticate your session with an API key to ensure secure data transmission.

Construct your subscription request by specifying the order events you want to monitor. You can choose from order_created, order_updated, and order_filled events. Include the market pair or trading symbol in your payload to filter updates relevant to your trades.

Handle incoming messages efficiently by parsing JSON responses. Each update includes fields like order_id, status, price, and quantity. Store this data in your application to maintain a real-time view of your order book.

For uninterrupted updates, implement error handling and automatic reconnection logic. Monitor WebSocket state changes and retry connections with exponential backoff if disconnections occur.

Working with Historical Trade Data

Retrieve historical trades via the /historical-trades endpoint by specifying a symbol, start time, and optional limit (default: 1000 entries). For example, GET /historical-trades?symbol=BTCUSDT&start=1672531200000&limit=500 fetches 500 BTC-USDT trades since January 1, 2023.

Process large datasets efficiently by paginating with the endTime parameter. After each request, use the last trade’s timestamp as the new start value to avoid overlaps or gaps. This avoids rate limits while ensuring completeness.

Filtering and Aggregation

Client-side filtering improves performance. Instead of multiple API calls, fetch a wider range once and filter locally by price, volume, or side (buy/sell). For OHLCV data, aggregate raw trades into candles using open-source libraries like Pandas.

Store historical data in a compressed format (e.g., Parquet) to reduce disk usage. Hyperliquid’s timestamps are in milliseconds–convert to your local timezone only during display, keeping raw data consistent for analysis.

Error Handling

Check for HTTP 429 (rate limit) responses and implement exponential backoff. Invalid timestamps return HTTP 400; validate inputs before querying. Missing data? Verify the symbol’s listing date–pre-launch requests return empty.

For real-time syncs, combine historical and WebSocket data. First, backfill via API, then listen to live trades. Use the last historical trade’s ID to deduplicate overlapping WebSocket entries.

Testing API Calls in Sandbox Environment

Before making live API requests, use Hyperliquid’s sandbox endpoint (https://testnet.hyperliquid.xyz) to validate your integration. The testnet mimics mainnet behavior but operates with fake funds, letting you experiment without risk. Check the response codes–successful calls return 200, while errors like invalid authentication trigger 401–and log unexpected results for debugging.

Simulate real-world scenarios by testing edge cases:

Send orders with extreme price values to verify rejection logic.
Trigger rate limits by exceeding 10 requests per second.
Disconnect mid-call to confirm your error handling works.

Compare sandbox responses with the mainnet API documentation to spot inconsistencies. If responses differ, adjust your code before switching environments. For faster iteration, automate tests with Postman or scripts–Hyperliquid’s sandbox resets every 24 hours, so you’ll always start fresh.

Optimizing Request Payloads for Performance

Minimize payload size by stripping unnecessary metadata and compressing data before sending. Use gzip or deflate for JSON responses, and prefer WebSocket over HTTP for high-frequency updates–this reduces header overhead. Batch multiple operations into a single request when possible, especially for order placements or cancellations. For example, Hyperliquid’s API supports bulk updates with a single payload, cutting latency by up to 40%.

Structure payloads with flat key-value pairs instead of nested objects to simplify parsing. Replace verbose field names like transactionTimestamp with shorter alternatives (ts), and use arrays for repetitive data. Monitor payload efficiency with tools like Chrome DevTools’ Network tab, focusing on reducing time-to-first-byte. If responses exceed 50KB, consider pagination or splitting into multiple requests–Hyperliquid’s WebSocket streams handle this gracefully by allowing subscription filters.

Q&A:

What programming languages are supported by the Hyperliquid API?

The Hyperliquid API is compatible with any language that can send HTTP requests, including Python, JavaScript, Java, and Go. Official SDKs are available for Python and JavaScript, while other languages can interact directly with the REST and WebSocket endpoints.

How do I authenticate API requests on Hyperliquid?

Authentication requires an API key generated in your Hyperliquid account settings. Include this key in the request header under “X-API-KEY”. For sensitive operations, IP whitelisting and signature-based verification are recommended.

Can I test the API without risking real funds?

Yes. Hyperliquid provides a testnet environment with mock funds. Use the testnet endpoint (api-testnet.hyperliquid.xyz) and a testnet API key to experiment without affecting your live account.

What rate limits apply to the API?

Public endpoints allow up to 100 requests per minute. Private endpoints (e.g., trading) have a 30-request-per-minute limit. Exceeding limits triggers temporary bans. Optimize by batching requests or using WebSocket streams for real-time data.

Reviews

Benjamin

“Nice breakdown of the Hyperliquid API—clean and to the point. Liked how you kept it practical without drowning in jargon. The examples make it easy to test things out, though I’d toss in a few more edge cases for error handling. Docs are solid, but a quick note on rate limits would save some headaches. Solid work overall.” (287 символов)

Lily

OMG, this is exactly what I needed! Finally, a clear breakdown without all the techy jargon that makes my head spin. The step-by-step examples are *chef’s kiss*—no more guessing how to connect things! And the error handling tips? Lifesaver. My little automation project just got 10x easier. Whoever wrote this gets me. No fluff, just straight-up useful stuff. Now I can actually focus on building instead of googling for hours. Bless you for keeping it real! 🙌

LunarEcho

*”Oh, the Hyperliquid API—because manually trading crypto wasn’t already masochistic enough. Now you can automate your losses in real time! Documentation’s decent, but good luck debugging when their websockets ghost you. Still, if you enjoy pain with a side of leverage, knock yourself out.”* (183 символов)

### Male Names and Surnames:

Ah, the sweet symphony of code and coffee—where dreams of seamless API integration either soar or crash into a pile of cryptic error messages. Hyperliquid’s dev tools? More like a backstage pass to the blockchain circus, minus the clowns (unless you count my debugging skills). Want to turn “Hello, World” into “Hello, Liquid”? This guide’s your cheat sheet. Just don’t blame me when you’re three hours deep, muttering JSON incantations like a sleep-deprived wizard. Pro tip: keep snacks nearby. The only thing worse than a failed API call is hunger.

StarlightDreamer

“Wow, this is so cool! Finally, a way to make trading smoother without all the confusing tech jargon. The API feels like magic—just connect, and everything works so easily. No headaches, no endless setup, just pure simplicity. And the best part? It’s built for real people, not just coders. Love how it lets you focus on what matters instead of fighting with complicated tools. More of this, please! Tech should be fun, not frustrating. Whoever made this gets it. 💖” (716 chars)

Alice

“Just tried the Hyperliquid API and it’s way smoother than I expected. Docs are clear, didn’t need tech support once. Love how fast trades execute—no lag, no weird errors. The wallet integration saved me hours of manual work. Only gripe? Wish there were more examples for advanced orders. But honestly, it’s solid. If you’re into crypto trading, this is worth checking out. No fluff, just works.” (336 chars)