Hyperliquid API Guide: REST, WebSocket, Rate Limits and Examples

How do you use the Hyperliquid REST API?

Both main REST routes accept POST requests with JSON. The info endpoint is read-only. The request body's type field selects the query, such as allMids, l2Book, openOrders, userFills or clearinghouseState. Public user data is queried by address; there is no login token to read it because the underlying account activity is public.

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type":"allMids"}'

The response is a JSON object whose keys are market identifiers and whose values are prices encoded as strings. Keep numeric values as decimal strings until your application deliberately converts them. Binary floating-point arithmetic can introduce rounding differences that matter when you later construct an order.

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type":"l2Book","coin":"BTC"}'

The l2Book response contains bid and ask levels with price, size and order count. A single REST snapshot is useful for inspection, but it is not a complete live-order-book strategy. An automated application must account for the snapshot time and then keep its state current from a WebSocket feed or refresh it deliberately.

What is the difference between /info and /exchange?

• /info answers read-only questions. It returns market metadata, prices, books, funding history and account state.
• /exchange changes state. It accepts signed actions such as placing or cancelling an order, updating leverage, transferring assets or approving an API wallet.
• A user address belongs in account-data queries. An API wallet signs actions but should not be substituted for the user's address when requesting the user's positions or fills.

When should you use the Hyperliquid WebSocket API?

Use WebSocket when data should arrive as it changes. Available subscriptions include all mid prices, trades, candles, level-two books, best bid and offer, active-asset context, open orders, order updates, user fills and funding updates. REST is usually simpler for an occasional snapshot; WebSocket is better for a live screen or event-driven process.

const ws = new WebSocket("wss://api.hyperliquid.xyz/ws");

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({
    method: "subscribe",
    subscription: { type: "trades", coin: "BTC" }
  }));
});

ws.addEventListener("message", (event) => {
  const message = JSON.parse(event.data);
  console.log(message);
});

A successful subscription first returns a subscriptionResponse acknowledgment and then messages on the requested channel. Some time-series user feeds begin with a snapshot marked isSnapshot: true before streaming new events. Code should distinguish that initial state from later updates rather than counting the snapshot as fresh activity.

How should a client handle reconnects and heartbeats?

Hyperliquid's documentation tells automated clients to expect periodic server-side disconnects and reconnect cleanly. Resubscribe after reconnect and rebuild state from the new snapshot or the matching info request. Do not assume the last locally received message is still current.

The server closes a connection if it has not sent a message to that client for 60 seconds. For quiet subscriptions, send {"method":"ping"}; the server answers on the pong channel. A reconnect loop should use backoff and jitter instead of opening many connections at once, which can hit the new-connection limit.

What is a Hyperliquid API wallet?

An API wallet, also called an agent wallet, is a separate signing key approved by a master account. It can sign trading actions on behalf of the master account or its subaccounts without exposing the master wallet's private key to the trading process. It does not hold the account's funds and is not the address to use when querying that account's positions.

Why are signing and nonces difficult?

Hyperliquid has more than one signing scheme, field order matters for msgpack payloads, trailing zeroes can change the signed value, and address casing can cause mismatches. The official documentation therefore recommends using an existing SDK instead of writing signing code from scratch. A locally recovered signer does not prove the server will reconstruct the same payload.

Nonces are tracked per signer, including an API wallet signing for multiple accounts. They must be unique and fall within the protocol's accepted time window. If two processes share one signing key, they can produce collisions even when they trade different subaccounts. Coordinate an atomic nonce source or, more simply, use a separate API wallet per process.

How do you start with the Hyperliquid Python SDK?

Hyperliquid maintains an official Python SDK. Install it in a virtual environment, start with its read-only Info class, and inspect the repository examples before sending any signed action. The following call does not require a private key and returns current mids.

from hyperliquid.info import Info
from hyperliquid.utils import constants

info = Info(constants.MAINNET_API_URL, skip_ws=True)
print(info.all_mids())

For signed testnet examples, follow the SDK's current setup and basic_order files rather than copying an old snippet from a blog. The SDK example separates account_address from secret_key: when an API wallet signs, account_address is still the master account's public address. Review the order response before assuming an order rested or filled, and cancel any test order that remains open.

What are the current Hyperliquid API rate limits?

As checked against the official documentation on October 23, 2026, REST requests share an IP-based allowance of 1,200 weighted units per minute. This is not the same as 1,200 calls: an exchange request usually has low weight, selected info queries have weight 2, most other info queries have weight 20, and some history or candle requests add weight based on the number of returned items.

Trading actions also face address-based limits. An address begins with a 10,000-request buffer and earns further capacity from cumulative trading volume at one request per 1 USDC traded. Once limited, it can send one request every ten seconds. This address rule applies to actions, not info requests; cancels receive additional capacity so open risk can still be reduced.

• Cache slow-changing metadata instead of requesting it for every order.
• Use WebSocket subscriptions for live data rather than polling the same REST snapshot many times.
• Batch compatible orders or cancels, while still handling both per-item errors and a single error for the whole batch.
• Back off after a limit response; immediate blind retries add load and can extend the failure.
• Measure request weights, not only request counts, because different info queries cost different amounts.

How do asset IDs, tick sizes and precision work?

A displayed market name is not always the integer asset value used in a signed action. Standard perpetuals use their index in the meta universe. Spot markets use 10000 plus the spot market index. Builder-deployed perpetuals use a separate formula based on their perp DEX and metadata index. Because mainnet and testnet metadata can differ, resolve IDs from the current response rather than hard-coding a remembered number.

Order size must respect the asset's szDecimals value from metadata. Prices allow up to five significant figures and are also constrained by the asset's decimal rules; integer prices are permitted. Remove trailing zeroes when constructing values for signing. The SDK handles much of this, but the application must still round intentionally and verify that the resulting order has the expected notional value.

What common Hyperliquid API errors mean

What should you check before using the API in production?

• The code uses the intended network, account address, subaccount and current asset metadata.
• Secrets never enter client-side bundles, repositories, screenshots, analytics or application logs.
• Every order response is parsed as accepted, resting, filled or rejected instead of treated as a generic success.
• The process can cancel open orders and stop safely if market data is stale or the WebSocket disconnects.
• Retries are idempotent where possible and do not duplicate signed transfers or orders.
• REST weights, WebSocket counts and address capacity are measured and alerted before limits are exhausted.
• Test coverage includes partial fills, no liquidity, invalid precision, insufficient margin, rate limits and process restarts.
• A human can revoke the API wallet and inspect positions without depending on the automated process.

The bottom line

Use REST for deliberate snapshots, WebSocket for changing state and the exchange endpoint only through carefully controlled signing code. The fastest path is not to implement every detail yourself: begin with official read-only examples, adopt the maintained Python SDK for signed actions, test failure cases on testnet and promote only a small, observable process to mainnet.

Good API integration is mostly state management and risk control. Correctly identifying the user, tracking snapshots and updates, respecting precision, preserving unique nonces and surviving disconnects matter as much as constructing the first successful order.