Hyperliquid API Guide for Developers and Algo Traders

Introduction

Hyperliquid's API is the gateway for developers and algorithmic traders to interact programmatically with the largest on-chain perpetual futures exchange. Whether you are building a market-making bot, a copy-trading platform, an analytics dashboard, or a custom trading terminal, the Hyperliquid API provides the data and execution capabilities you need.

Unlike many DeFi protocols that require interacting with smart contracts through complex transaction construction, Hyperliquid offers a clean REST and WebSocket API that feels more like a centralized exchange API — but with all the self-custody and transparency guarantees of an on-chain system. Every order you place through the API is settled on the Hyperliquid L1 blockchain with sub-second finality, and your funds never leave your wallet.

This guide covers everything you need to get started: the two-API architecture, authentication with EIP-712 signatures, key endpoints for market data and trading, real-time WebSocket feeds, rate limits, available SDKs, and practical advice for building your first trading bot.

API Overview: Two APIs, One Platform

Hyperliquid exposes two distinct APIs that serve different purposes. Understanding the separation is essential before you start building.

Info API — The public, read-only API for market data and account information. No authentication is required. Use this to fetch order books, recent trades, candle data, funding rates, open interest, user positions, and account state. The base URL is https://api.hyperliquid.xyz/info and all requests are POST requests with a JSON body specifying the query type.

Exchange API — The authenticated, write API for trading actions. Requires EIP-712 signature authentication. Use this to place orders, cancel orders, modify positions, update leverage, transfer margins between sub-accounts, and initiate withdrawals. The base URL is https://api.hyperliquid.xyz/exchange.

Both APIs use JSON over HTTPS. There are no separate REST endpoints for different resources as you might find on a traditional exchange — instead, you POST a typed request to a single endpoint. For example, to get the order book, you POST {"type": "l2Book", "coin": "BTC"} to the Info API. This design simplifies the API surface while supporting a wide range of queries.

Authentication: EIP-712 Signatures

The Exchange API uses EIP-712 typed data signatures for authentication — the same standard used by MetaMask and other Ethereum wallets for structured data signing. This means you prove ownership of your wallet by signing each request with your private key, without ever sending your private key to Hyperliquid's servers.

Each Exchange API request includes three components: the action (what you want to do), a nonce (current timestamp in milliseconds for replay protection), and the EIP-712 signature generated from the action and nonce using your wallet's private key. The signature scheme ensures that even if someone intercepts your API request, they cannot modify it or replay it after the nonce window expires.

API wallets vs main wallets: Hyperliquid supports a critical security feature — API-only wallets. You can authorize a separate wallet address to trade on behalf of your main account. This API wallet can place and cancel orders but cannot initiate withdrawals. If your API wallet key is compromised, the attacker can trade (and potentially lose money through bad trades) but cannot steal your funds. This is a best practice for any production bot — never use your main wallet's private key in an automated system.

Info API Endpoints

The Info API covers all the market data and account information you need for trading decisions. Key endpoint types include:

Market metadata: Request type meta returns all available markets with their specifications — symbol, maximum leverage, tick size, lot size, and current funding rate. This is the starting point for discovering which markets are available and their trading parameters.

Order book: Request type l2Book returns the current order book for a given market, with configurable depth. Returns arrays of price/size pairs for bids and asks. For real-time book updates, use the WebSocket API instead of polling.

Candle data: Request type candleSnapshot returns OHLCV candle data for a specified market and time interval (1m, 5m, 15m, 1h, 4h, 1d). Essential for technical analysis and backtesting.

Funding rates: Request type fundingHistory returns historical funding rates for a market. Combined with meta (which includes current predicted rates), this gives you a complete picture of funding dynamics. See our funding rates guide for strategies around funding.

User state: Request types clearinghouseState and openOrders return a user's current positions, margin balances, and pending orders. These do not require authentication (any address can be queried), which is useful for building analytics tools that track whale positions.

Exchange API Endpoints

The Exchange API handles all trading operations. Every request must be signed with your wallet's private key using the EIP-712 scheme described above.

Place order: The order action lets you place limit orders, market orders (as aggressive limit orders), and advanced order types including stop-loss, take-profit, and trailing-stop orders. You specify the market, side (buy/sell), size, price, order type, and optional reduce-only or time-in-force parameters. Batch ordering is supported — you can place up to 20 orders in a single API call.

Cancel order: The cancel action cancels one or more open orders by their order ID. You can also use cancelByClid to cancel by your client-assigned order ID, which is useful for tracking orders in your own system. Batch cancellation supports up to 20 cancels per request.

Modify order: Rather than canceling and replacing, you can use the modify action to update an existing order's price or size in a single atomic operation. This is more efficient and avoids the risk of the cancel succeeding but the new order failing.

Update leverage: The updateLeverage action changes the leverage setting for a specific market. This affects new positions and adjusts the margin requirement for existing positions.

Transfer and withdraw: Transfer USDC between sub-accounts or initiate withdrawals to Arbitrum. Withdrawals go through the Hyperliquid bridge and typically settle within a few minutes.

WebSocket API

For real-time data, the WebSocket API is essential. Polling REST endpoints introduces latency and wastes rate limit budget. The WebSocket connection provides push-based updates as soon as state changes on-chain.

Connect to wss://api.hyperliquid.xyz/ws and subscribe to channels by sending JSON subscription messages. Available channels include:

l2Book: Real-time order book updates for a specific market. Sends the full book snapshot on subscription, then incremental updates as orders are placed, filled, or canceled. Updates arrive within 50-100ms of on-chain state changes.

trades: Real-time trade feed showing every fill on a market — price, size, side, and timestamp. Useful for tape-reading strategies and real-time volume analysis.

userFills: Real-time notifications when your orders are filled. Subscribe with your wallet address to receive instant fill confirmations without polling. This is critical for bots that need to react immediately to position changes.

activeAssetCtx: Real-time updates to market context including mark price, funding rate, open interest, and 24-hour volume. Provides a live snapshot of market conditions without querying individual endpoints.

Implement reconnection logic in your WebSocket client — connections may drop due to server restarts, network issues, or idle timeouts. A robust bot should detect disconnections, reconnect automatically, resubscribe to all channels, and reconcile any state changes that occurred during the disconnection by querying the REST API.

Rate Limits

Hyperliquid enforces rate limits to prevent abuse and ensure fair access. Understanding these limits is critical for bot development — hitting rate limits can cause missed trades or temporary bans.

The Info API limit of 1,200 requests per minute (20 per second) is generous for most use cases, but can be consumed quickly if you are polling multiple markets. Use the WebSocket API for real-time data to conserve REST rate limits for on-demand queries.

The Exchange API limit of 100 requests per 10 seconds per wallet allows 10 orders per second on average. With batch ordering (up to 20 orders per request), you can effectively place up to 200 orders per 10 seconds — sufficient for most market-making strategies. If you need more throughput, consider using multiple API wallets authorized on the same account.

SDK Libraries

While you can interact with the Hyperliquid API using raw HTTP requests in any language, official and community SDKs simplify development significantly by handling authentication, request formatting, and response parsing.

Python SDK (hyperliquid-python-sdk): The official Python SDK is the most mature and widely used. It handles EIP-712 signature generation, provides typed request and response objects, and includes helper functions for common operations. Install with pip install hyperliquid-python-sdk. The SDK supports both synchronous and asynchronous usage and includes WebSocket client management.

TypeScript SDK: An official TypeScript/JavaScript SDK is available for Node.js and browser environments. It provides the same functionality as the Python SDK with TypeScript type definitions for all request and response types. Useful for building web-based trading interfaces or Node.js bots.

Community SDKs: Community-maintained libraries exist for Rust, Go, and C#. These vary in completeness and maintenance status — check the GitHub repository activity before depending on a community SDK for production use. For a curated list of developer tools, see our project directory.

Building a Trading Bot: From Zero to First Trade

Building a basic trading bot on Hyperliquid involves four steps: connecting to the API, fetching market data, placing an order, and monitoring fills. Here is the conceptual flow using the Python SDK:

Step 1 — Set up authentication: Create an API wallet on the Hyperliquid interface, export the private key, and initialize the SDK client with your API wallet address and private key. Store the private key in an environment variable, never in source code.

Step 2 — Fetch market data: Query the Info API for the current order book, recent trades, and funding rates. Parse the response to determine current market conditions — best bid, best ask, spread, and recent price action.

Step 3 — Place an order: Based on your strategy logic, construct an order with the appropriate market, side, size, price, and order type. Submit it through the Exchange API. The response includes an order ID (oid) for tracking.

Step 4 — Monitor and manage: Subscribe to the WebSocket userFills channel to receive real-time fill notifications. When your order fills, update your internal state and execute follow-up logic (place stop-loss, update position tracking, log the trade). Implement error handling for partial fills, rejected orders, and network failures.

Start on testnet. The Hyperliquid testnet provides identical API endpoints with fake funds, letting you validate your bot's behavior without risking real capital. Only move to mainnet after thorough testing. For more on automated trading, see our Best Hyperliquid Trading Bots guide.

Best Practices for Production Bots

Use API-only wallets: Never put your main wallet's private key in a bot. Create a dedicated API wallet that can trade but cannot withdraw. This limits the damage if your server is compromised.

Implement circuit breakers: Your bot should have automatic shutdown triggers: maximum loss per hour, maximum number of consecutive losing trades, unusual spread widening, and abnormal latency. A bot without circuit breakers can lose your entire account in minutes during adverse conditions.

Handle disconnections gracefully: Network failures, API outages, and WebSocket drops are inevitable. Your bot should detect disconnections immediately, reconnect with exponential backoff, reconcile state after reconnection (query current positions and open orders), and have a safe default behavior during disconnections (e.g., cancel all open orders).

Respect rate limits proactively: Do not wait for 429 errors — track your request count locally and throttle before hitting limits. Use WebSocket feeds instead of polling for real-time data. Batch orders when possible to reduce request count.

Log everything: Every order placed, fill received, error encountered, and decision made should be logged with timestamps. When something goes wrong (and it will), detailed logs are the only way to diagnose the issue and prevent recurrence.

Start small: Even after successful testnet validation, start with minimal position sizes on mainnet. Increase gradually as you build confidence in your bot's behavior under real market conditions.