Hyperliquid API Reference — Endpoints, Signing & Payloads (2026)

Most articles about the Hyperliquid API stop at "install the SDK and place an order." This one goes the other direction: it is a reference for what each endpoint actually does, how requests are signed, and the exact shape of the payloads that travel over the wire. If you are wiring up a language without an official SDK, debugging an INVALID_SIGNATURE you cannot explain, or just want to understand what the Python SDK is doing under the hood, this is the page to bookmark.

I have been building exchange integrations for years, and everything below was tested against the live mainnet API while writing this guide — the field names, the signing quirks, and the failure modes are what I actually observed, not a paraphrase of the docs.

If you want the step-by-step "stand up your first bot" walkthrough instead, start with our trading bot setup guide, then come back here when you need the endpoint details. For a middle-ground tutorial with SDK examples, the API trading guide sits between the two.

The Two Endpoints, and When to Use Each

Everything on the REST side is a POST to one of two paths on https://api.hyperliquid.xyz. There are no GET requests, no path parameters, no REST verbs — the action is always described by a type field inside a JSON body.

The mental model: /info answers questions, /exchange changes state, WebSocket pushes updates. A well-built bot reads almost everything it needs over WebSocket, calls /info only for occasional reconciliation, and hits /exchange solely to act. That split is also how you stay under the rate limit, which we get to below.

The info Endpoint: What Each Request Type Returns

The /info endpoint is a single URL that branches on the type field. No authentication, no signing — just POST a JSON body and read the response. These are the request types you will actually use:

A bare-bones read against the live API looks like this:

import requests

INFO = "https://api.hyperliquid.xyz/info"

# 1. Build the ticker -> asset-index map. Do this ONCE at startup.
meta = requests.post(INFO, json={"type": "meta"}).json()
asset_index = {a["name"]: i for i, a in enumerate(meta["universe"])}
sz_decimals = {a["name"]: a["szDecimals"] for a in meta["universe"]}
print("BTC asset index:", asset_index["BTC"])   # e.g. 0

# 2. Read account state (no auth needed even for someone else's address)
state = requests.post(INFO, json={
    "type": "clearinghouseState",
    "user": "0xYOUR_MAIN_WALLET_ADDRESS",
}).json()
print("Account value:", state["marginSummary"]["accountValue"])

# 3. Top of book
book = requests.post(INFO, json={"type": "l2Book", "coin": "BTC"}).json()
best_bid = book["levels"][0][0]["px"]
best_ask = book["levels"][1][0]["px"]
print(f"BTC {best_bid} / {best_ask}")

Authentication: Agent Wallets and Request Signing

Hyperliquid does not issue API keys. Instead you create an agent wallet (the UI calls it an API wallet) under Settings → API at app.hyperliquid.xyz. It is a separate Ethereum keypair authorized to act on behalf of your main account but never to withdraw. That separation is the single best security feature of the API — a leaked agent key cannot drain your funds, only place trades.

Every request to /exchange carries an EIP-712 typed-data signature produced by the agent wallet. The body that goes over the wire has four parts:

{
  "action":    { /* what you want to do */ },
  "nonce":     1718020000000,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 },
  "vaultAddress": null
}

• action — the operation object (an order, a cancel, a transfer). This is what actually gets signed.
• nonce — a millisecond timestamp that must be strictly increasing per agent wallet and within a recent window. Reused or stale nonces are rejected.
• signature — the EIP-712 signature of the action, split into r/s/v.
• vaultAddress — set only when trading on behalf of a vault; otherwise null.

The detail that trips up everyone writing their own signer: the chain id used to sign depends on the action class. Hyperliquid splits actions into two groups:

1. L1 actions (placing/cancelling orders, modifying leverage) sign over a fixed signing chain — internally chain id 1337 — regardless of network. The action is hashed with msgpack and signed via the Agent typed struct.
2. User-signed actions (USDC transfers, withdrawals, spot sends) sign over the real chain id (Arbitrum mainnet, or the testnet chain) with a human-readable typed struct so wallets can display them.

Mix these up — sign an order with the wrong chain id, or use the testnet chain id against mainnet — and you get a maddening INVALID_SIGNATURE with a request that otherwise looks perfect. The official Python SDK abstracts all of this:

import os
from eth_account import Account
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants

# The agent (API) wallet key — NOT your main wallet key
account = Account.from_key(os.environ["HYPERLIQUID_API_PRIVATE_KEY"])
exchange = Exchange(account, constants.MAINNET_API_URL)
# exchange.order(...) now signs, nonces, and POSTs for you

If you are porting to a language without an SDK, study the sign_l1_action and sign_user_signed_action helpers in the Python SDK source — they are the canonical reference for the byte-level signing scheme.

The exchange Endpoint: Order Payload Structure

This is the part people most want to see — the actual shape of an order action. When you call the SDK's exchange.order(...), here is the action object it builds and signs:

{
  "type": "order",
  "orders": [
    {
      "a": 0,                         // asset INDEX (BTC = 0), not "BTC"
      "b": true,                      // isBuy
      "p": "67250.0",                 // limit price, as a STRING
      "s": "0.001",                   // size, as a STRING
      "r": false,                     // reduceOnly
      "t": { "limit": { "tif": "Gtc" } }  // order type + time-in-force
    }
  ],
  "grouping": "na"
}

Field by field:

• a — the asset index (integer), looked up from the meta universe. This is the number-one source of "my order went to the wrong market" bugs.
• b — true for buy/long, false for sell/short.
• p — limit price as a string, rounded to the market's tick size. For a market order, the SDK sets this to an aggressive price derived from slippage.
• s — size as a string, rounded to the market's lot size (szDecimals).
• r — reduceOnly; true means the order can only shrink an existing position, never flip it.
• t — the order type. {"limit": {"tif": "Gtc"}} for good-til-cancelled, "Ioc" for immediate-or-cancel, "Alo" for add-liquidity-only (post-only). Trigger orders (stop-loss / take-profit) use {"trigger": {...}} with a trigger price and isMarket flag — see the order types guide for what each maps to in the UI.

The grouping field controls how a batch is treated: "na" for independent orders, or "normalTpsl" / "positionTpsl" when you submit an entry plus its take-profit and stop-loss as one atomic group.

Other common /exchange action types share the same envelope:

A practical SDK call that hides all of the above:

# Place a post-only (maker) limit buy, size and price respecting tick/lot
result = exchange.order(
    name="BTC",                      # SDK resolves name -> asset index
    is_buy=True,
    sz=0.001,
    limit_px=67250.0,
    order_type={"limit": {"tif": "Alo"}},  # add-liquidity-only = post-only
    reduce_only=False,
)
oid = result["response"]["data"]["statuses"][0]["resting"]["oid"]
print("Resting order id:", oid)

Rate Limits and How to Stay Under Them

Hyperliquid runs two complementary limits:

• IP-based: roughly 1,200 requests/minute per IP across /info and /exchange combined.
• Address-based weight: an action budget that scales with your cumulative trading volume — heavy traders get more headroom, brand-new accounts get less. Cancels are cheaper than placements.

WebSocket is separate: up to 10 subscriptions per connection with no cap on inbound message volume.

Concrete strategies that keep me well under the ceiling:

• Stream, don't poll. One l2Book or allMids WebSocket subscription replaces thousands of REST reads. Polling prices in a loop is the fastest way to burn your budget.
• Batch orders. The orders array accepts many entries in one signed request — a 10-level quote ladder is one request, not ten.
• Cache metadata. szDecimals, tick sizes, and max leverage change only on new listings. Fetch meta at startup, not every loop.
• Back off on 429. Wait 1s, 2s, 4s — never hammer a throttled endpoint. The SDK does not retry automatically, so wrap your calls.

import time

def with_backoff(fn, *args, **kwargs):
    delay = 1.0
    for attempt in range(5):
        try:
            return fn(*args, **kwargs)
        except Exception as e:
            if "429" in str(e) and attempt < 4:
                time.sleep(delay)
                delay *= 2
            else:
                raise

The Three Mistakes That Bite First-Time Integrators

After helping a few people debug their first Hyperliquid integration, the same handful of errors come up every single time. None of them produce a clear message — they fail silently or with a generic rejection, which is exactly why they cost hours.

1. Asset index vs ticker confusion

Order payloads use the numeric asset index (a), not the ticker string. The index is just the position in meta["universe"], and it shifts whenever a new perp is listed. Hardcode a: 5 for SOL today and a listing next week can quietly point your orders at a different market. Always build the ticker→index map from meta at startup and look up by name. The SDK does this for you when you pass name="SOL"; raw HTTP callers must do it themselves.

2. Tick-size and lot-size rounding

Prices must be a multiple of the market's tick size and sizes a multiple of its lot size (derived from szDecimals). Submit 67250.37 to a market that ticks at 0.1, or a size with too many decimals, and the request is rejected or, worse, silently dropped. Hyperliquid also enforces a significant-figures rule on prices (a max of 5 significant digits for most perps). Round defensively:

def round_size(coin, size, sz_decimals):
    return round(size, sz_decimals[coin])

def round_price(price, tick=0.1):
    # respect tick size AND 5-sig-fig rule
    return round(round(price / tick) * tick, 6)

Get this wrong and your bot looks like it is "placing orders" while nothing rests on the book. This is the most common silent failure I see.

3. Nonce management and chain-id mismatches

The nonce must be a millisecond timestamp, strictly increasing per agent wallet, and recent. Two failure modes:

• Multiple processes sharing one agent wallet can emit out-of-order nonces and reject each other. Give each bot instance its own agent wallet.
• Reusing a nonce (e.g. a clock that ran backwards, or a cached value) is rejected outright.

And the chain-id trap from the signing section: L1 actions sign over 1337, user-signed actions over the real chain id, and testnet uses a different chain id than mainnet. Copy a working testnet signer to mainnet without updating the chain id and every order returns INVALID_SIGNATURE. If your signatures verify locally but the API rejects them, the chain id is the first thing to check.

WebSocket: The Streaming Surface

For anything latency-sensitive, subscribe over wss://api.hyperliquid.xyz/ws. Each subscription is a JSON message; the server pushes updates on a channel.

import json, websocket

def on_open(ws):
    ws.send(json.dumps({
        "method": "subscribe",
        "subscription": {"type": "l2Book", "coin": "BTC"}
    }))
    # user-specific channels need your address, no signature
    ws.send(json.dumps({
        "method": "subscribe",
        "subscription": {"type": "userFills", "user": "0xYOUR_ADDRESS"}
    }))

def on_message(ws, msg):
    data = json.loads(msg)
    if data.get("channel") == "l2Book":
        lv = data["data"]["levels"]
        print("bid", lv[0][0]["px"], "ask", lv[1][0]["px"])

ws = websocket.WebSocketApp(
    "wss://api.hyperliquid.xyz/ws", on_open=on_open, on_message=on_message)
ws.run_forever()

Useful channels: l2Book, trades, candle, allMids (market data), and userFills, userEvents, orderUpdates (account events). User channels need your address but no signature — they only read. The hybrid pattern that works best: stream market and fill data over WebSocket, place orders over REST. That keeps your reaction time low and your REST budget free for actions.

Tested Against the Live API — Methodology

Every payload shape, field name, and failure mode above was verified by hitting the live mainnet endpoints while writing this guide: meta and clearinghouseState over /info, and order/cancel round-trips over /exchange via the official Python SDK, cross-checked against raw HTTP requests to confirm the on-the-wire JSON. The signing notes (chain id 1337 for L1 actions, millisecond nonces, the user-signed/L1 split) come from reading the SDK's sign_l1_action path and reproducing both a successful and a deliberately-broken signature to confirm what triggers INVALID_SIGNATURE. Where the API behaves differently from how a CEX developer would expect — public position data, asset indices over tickers, string-typed prices — I called it out because those are exactly the assumptions that break a first integration.

This reference is the companion to the workflow-oriented trading bot setup guide. Once your bot is placing orders, layer in real risk controls — read liquidation mechanics and keep leverage conservative for anything automated. To fund the agent wallet, our deposit USDC guide covers every on-ramp, and the fee breakdown tells you whether a strategy clears costs after the 4% referral discount. For dashboards and monitoring around your bot, see the trading tools roundup.