The Hyperliquid API for Trading Agents (Beginner’s Guide)

hero illustration

The Hyperliquid API is simple enough for a beginner to read from, but any trading agent that places orders needs careful signing, rate limits, and guardrails before it touches real money.

Hyperliquid has become a popular venue for crypto trading agents because the API is free, fast, and fairly direct. You can pull market data from one endpoint, place signed trades through another, and stream live books over WebSocket.

The catch is that “simple” does not mean “safe.” Hyperliquid does not use normal API keys. Trading actions are signed transactions. If your bot signs a bad order, the exchange will treat it like you meant it.

Quick takeaway: Use REST for historical data and order placement, WebSocket for live market data, a separate Hyperliquid API wallet for signing, and strict limits before you let an AI agent trade.

The two main endpoints

Hyperliquid splits the API into two main REST endpoints, per the Hyperliquid API docs verified May 21, 2026:

  • https://api.hyperliquid.xyz/info for public and account read requests
  • https://api.hyperliquid.xyz/exchange for signed trading actions

The /info endpoint is where your agent reads market data. Most requests are JSON objects with a type field. For example, this asks for all mid prices:

{
  "type": "allMids"
}

The response looks like a plain map of coin symbols to string prices:

{
  "BTC": "77634.0",
  "ETH": "3120.4"
}

Hyperliquid returned 230 coins from allMids in the May 2026 research sample. All values come back as strings, so your code should parse numbers deliberately. Do not assume "77634.0" is already a float.

The /exchange endpoint is different. This is where orders, cancels, leverage updates, transfers, and agent approvals happen. Every trading request needs an action, a nonce, and a signature.

How signing works

Hyperliquid does not give you a normal API key and secret like Binance or Coinbase. It uses signed actions.

Per the research file, Hyperliquid uses Ethereum EIP-712 typed data signing for exchange actions. The EIP-712 domain is:

  • name="Exchange"
  • version="1"
  • chainId=1337
  • verifyingContract=0x0

In plain English: your wallet signs the exact action your bot wants to take. Hyperliquid checks the signature, recovers the signer address, and verifies that the signer is allowed to act for the account.

For a beginner, the safest setup is an API wallet, not your main wallet. Hyperliquid lets you generate API wallet keys at app.hyperliquid.xyz/API. The API wallet signs actions, while your main wallet remains the account address. If something goes wrong, you can revoke the API wallet without changing your main wallet.

The Python SDK handles this signing flow internally. The relevant pieces from the research material are:

  • Exchange._post_action() sends signed trading actions
  • sign_l1_action() in hyperliquid/utils/signing.py signs the payload
  • Each action includes a nonce, usually a millisecond timestamp
  • Some actions can also include vaultAddress or expiresAfter

That last point matters for agents. If your bot gets delayed, retries a request, or runs across multiple processes, nonce handling can turn into a real bug. Keep one signing path. Log every signed action. Make cancels easy.

The read endpoints your agent will use most

You do not need every endpoint on day one. A simple trading agent usually starts with market data, account state, open orders, and fills.

  • allMids: mid prices for all perpetuals. Weight 2.
  • l2Book: order book for one coin. Weight 2.
  • candleSnapshot: OHLCV candles. Weight 20, plus extra weight per 60 items.
  • fundingHistory: historical funding rates. Weight 20, plus extra weight per 20 items. Requires startTime.
  • meta: trading universe, size decimals, max leverage, and margin table IDs.
  • metaAndAssetCtxs: market metadata plus per-asset context like funding, open interest, mark price, premium, and daily notional volume. Weight 20.
  • clearinghouseState: perpetual account state for an address. Weight 2.
  • openOrders: current open orders for a user. Weight 20.
  • userFills: fill history. Weight 20, plus extra weight per 20 items.
  • orderStatus: check an order by oid or cloid. Weight 2.

Here is a basic l2Book request:

{
  "type": "l2Book",
  "coin": "BTC"
}

The response includes price levels. Each level has:

  • px: price as a string
  • sz: size as a string
  • n: number of orders at that level

The May 21 research sample showed this shape:

{
  "coin": "BTC",
  "time": 1779406026396,
  "levels": [
    [{"px": "77632.0", "sz": "24.44037", "n": 60}],
    [{"px": "77633.0", "sz": "1.25621", "n": 19}]
  ]
}

One caveat from the research: the sample showed a crossed spread, with bid above ask. That can happen because of data propagation timing. Your bot should validate book consistency instead of assuming every snapshot is clean.

The trading actions your agent needs to respect

Most beginner bots only need three exchange actions at first:

  • order to place an order
  • cancel or cancelByCloid to cancel an order
  • updateLeverage to set leverage before trading

A basic order action looks like this in the research material:

{
  "type": "order",
  "orders": [
    {
      "a": 0,
      "b": true,
      "p": "77600.0",
      "s": "1.0",
      "r": false,
      "t": {
        "limit": {
          "tif": "Gtc"
        }
      }
    }
  ],
  "grouping": "na",
  "brokerCode": 0
}

The short field names are easy to get wrong:

  • a is the asset index, such as 0 for the first asset in the universe
  • b is buy or sell
  • p is price
  • s is size
  • r is reduce-only
  • t is the order type

Limit orders can use Gtc, Ioc, or Alo. Trigger orders can include triggerPx, isMarket, and tpsl values of tp or sl.

For an AI trading agent, reduce-only is not a tiny detail. If the bot is trying to close a position, r should usually be true. Otherwise a failed close can become a new position in the other direction.

REST vs WebSocket

Use REST when you need a snapshot, a history query, or a signed action. Use WebSocket when you need live data.

Hyperliquid’s WebSocket endpoint is:

wss://api.hyperliquid.xyz/ws

The subscription format is simple:

{
  "method": "subscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "BTC"
  }
}

Useful WebSocket channels include:

  • allMids: mid prices for all coins
  • l2Book: live order book for a coin
  • trades: recent executions for a coin
  • candle: live candles for a coin and interval
  • userFills, userState, and orderUpdates: user-specific channels that require signed authentication

For l2Book, the first message after subscribing is a full snapshot. Later messages are incremental updates with a seqNum. Per the research file, seqNum should increase by exactly 1 between consecutive updates for that coin. If your client sees a gap, it should disconnect and reconnect. There is no WebSocket RPC call to request a fresh snapshot.

Hyperliquid does not send Binance-style CRC32 checksums. Your integrity check is sequence tracking. For extra safety, compare your local book against the REST l2Book endpoint from time to time, but remember that REST can be slightly delayed versus WebSocket.

Rate limits that matter

Per Hyperliquid GitBook docs dated April 28, 2026, the main IP REST limit is 1200 weight per minute. That is shared across REST requests from the same IP.

Important WebSocket limits from the same research:

  • 10 WebSocket connections per IP
  • 30 new WebSocket connections per minute
  • 1000 WebSocket subscriptions
  • 10 unique users across user-specific WebSocket subscriptions
  • 2000 messages per minute sent across all WebSocket connections
  • 100 simultaneous inflight post messages across all WebSocket connections

Address-based limits are separate. Hyperliquid gives an initial buffer of 10,000 requests, then scales at 1 request per 1 USDC traded cumulatively since inception. When rate limited, the address gets 1 request every 10 seconds. Cancels get a higher allowance: min(limit + 100000, limit * 2).

There is also an open order limit: 1000 base orders, plus 1 per 5M USDC of volume, capped at 5000.

This is why a bot should not poll everything. Pull slow data slowly. Stream fast data through WebSocket. Batch where it makes sense. A single exchange request costs weight 1 + floor(batch_length / 40), so one order is weight 1 and a batch of 79 orders is weight 2.

SDKs worth knowing

The official Python SDK is the easiest path for most beginners:

  • Package: hyperliquid-python-sdk
  • Version in research: v0.23.0
  • Install: pip install hyperliquid-python-sdk
  • GitHub: https://github.com/hyperliquid-dex/hyperliquid-python-sdk

The main classes are:

  • Info for read endpoints
  • Exchange for trading actions
  • API for base HTTP calls
  • WebsocketManager for managed WebSocket connections

CCXT also has Hyperliquid support through the hyperliquid package, listed as v1.7.7 in the research.

TypeScript is messier. The research found no officially maintained TypeScript SDK from hyperliquid-dex. Community options include:

  • @nktkas/hyperliquid v0.32.2, described as the most actively maintained option in March 2026
  • hyperliquid v1.7.7 by nomeida, using ethers v6
  • hyperliquid-sdk v2.4.2
  • hyperliquid-ts-sdk v0.0.38 by elevatordown, older

If you are new, start with Python unless your whole agent stack is already in Node.js.

A real beginner workflow for a trading agent

A sane first version should observe before it trades. Here is a practical workflow:

  1. Call meta and store the asset universe, size decimals, max leverage, and asset indexes.
  2. Subscribe to l2Book, trades, and candle for BTC, ETH, or one market you understand.
  3. Track seqNum on the order book and reconnect on gaps.
  4. Write recent books, trades, and candles into SQLite.
  5. Summarize the market into small metrics before sending anything to Claude, GPT-5.5, Codex, CrewAI, or LangGraph.
  6. Let the model output a structured decision: long, short, or none.
  7. Run hard risk checks in code, not in the model prompt.
  8. Place a small signed order only if the decision passes those checks.
  9. Subscribe to orderUpdates and userFills, then journal what happened.

The LLM should not receive raw order books every few milliseconds. The research recommends compact summaries every 500ms to 1s, or market state JSON every 5 to 10 seconds. For model calls, keep prompts under 2000 tokens and evaluate every 30 to 60 seconds at most, unless an event trigger fires.

A useful compressed line looks like this:

BTC: bid=77633, ask=77632, spread=-1.0, bid_sz=1.26, ask_sz=24.44, 10s_delta_bid=-5.0, funding=0.000835%

That is much cheaper and safer than dumping full books into a model window.

Where AI agents fit

The May 2026 research shows a lot of activity around AI trading agents, but most of it is still early and anecdotal.

Specific examples from the research include:

  • @0xbeinginvested describing a 19-year-old who dropped a research paper PDF into Codex and got working market-neutral strategy code, with Codex reportedly doing about 90% of the work.
  • @heynavtoor sharing a CrewAI-style Hyperliquid setup with an analyst, strategy generator, execution via MCP, and risk agent.
  • @vooi_io discussing VOOI Perps MCP across Hyperliquid, Aster, and Lighter.
  • @GT_Protocol describing Pentarchy, with five models trading in a shared Hyperliquid vault.
  • @prompt48 pointing to a Hyperliquid whale order tracking repo for $100k+ trades.
  • @0xTobiasDev referencing a clean sub-300-line Hyperliquid Telegram bot.

That does not mean beginners should hand a wallet to an agent and walk away. It means the tools are getting good enough to build faster. Testing, limits, and human review still matter.

Security checklist before trading

Before your agent places real orders, do the boring checks:

  • Use a separate Hyperliquid API wallet from app.hyperliquid.xyz/API.
  • Keep the main wallet off the server that runs the bot.
  • Set max position size in code.
  • Set max daily loss in code.
  • Use reduce-only orders when closing positions.
  • Log every signed action before sending it.
  • Make cancel-all easy to run.
  • Test on tiny size first.
  • Do not send raw private keys into an LLM prompt.
  • Do not let the model decide risk limits dynamically.

Also remember that Hyperliquid API access is free. Per the research, there are no paid API tiers, subscriptions, or paid rate limit upgrades. The cost is trading fees, plus a one-time on-chain activation fee in HYPE to register an address for API trading.

Get a Ledger hardware wallet
Protect your connection with NordVPN

Disclosure: Easy as Pie DeFi may earn a commission if you buy through these links. That does not change the price you pay, and it does not affect the guidance in this article.

Bottom line

The Hyperliquid API is a strong base for trading agents because the read endpoints, signed exchange actions, WebSocket feeds, Python SDK, and rate limits are all usable without a paid API plan. Start with read-only data, add signing through a separate API wallet, keep risk checks outside the model, and treat every automated order like real money is on the line.