Hyperliquid API Guide: Python, WebSocket and Wallet Tracking (2026)

Quick answer: the Hyperliquid API is a free, public interface with three surfaces: the Info endpoint (POST https://api.hyperliquid.xyz/info) for reading market and account data, the Exchange endpoint for placing orders, and a WebSocket (wss://api.hyperliquid.xyz/ws) for real-time streams. With the official Python SDK you can pull fills, positions and PnL for any wallet in minutes — or skip the code entirely and track any Hyperliquid wallet's PnL, fees and funding instantly with Hyperfolio, the free Hyperliquid wallet tracker.

Every position, fill and liquidation on Hyperliquid lives on-chain and is publicly readable through the API. That is rare in crypto: most exchanges hide their order books and account data behind private endpoints. Hyperliquid exposes them to anyone, which is why builders, quant traders and analytics tools like Hyperfolio are all reading the same raw data.

The problem is that the official docs are reference material, not a tutorial. You end up jumping between the GitBook, the Python SDK repo and old GitHub issues to piece together how it actually works. This guide gives you the working version: endpoints, code, rate limits and the pitfalls that waste developer time — and then shows you what to build yourself versus what a ready-made tracker already solves.

What Is the Hyperliquid API?

The API is split into three surfaces, and each has a different job:

• Info endpoint (REST, read-only): market data, order book state, a user's fills, positions, account value, funding, liquidations and leaderboard data.
• Exchange endpoint (REST, authenticated): placing, canceling and modifying orders, plus withdrawals — signed with an agent wallet.
• WebSocket: real-time push of trades, order book updates, allMids, user fills, funding and more, without polling.

All example calls in the official docs use the mainnet base URL https://api.hyperliquid.xyz; the testnet equivalent is https://api.hyperliquid-testnet.xyz.

Surface	URL	Auth	Use case
Info (REST)	POST api.hyperliquid.xyz/info	None	Read any wallet, market data, leaderboard
Exchange (REST)	POST api.hyperliquid.xyz/exchange	Agent wallet signature	Place/cancel orders, withdraw
WebSocket	wss://api.hyperliquid.xyz/ws	None (read), signed actions	Real-time trades, books, user fills

Quick Start: Python SDK in 5 Minutes

Hyperliquid maintains an official Python SDK (github.com/hyperliquid-dex/hyperliquid-python-sdk), and the community has Rust and TypeScript SDKs as well. Install it and pull the current mid price for any coin:

pip install hyperliquid-python-sdk

from hyperliquid.info import Info

info = Info("https://api.hyperliquid.xyz")
mids = info.all_mids()
print(mids["BTC"])   # e.g. "98452.3"

The Info class wraps every read-only endpoint with typed methods, so you rarely touch raw HTTP. For anything the SDK does not cover, you can POST JSON directly to the Info endpoint yourself — it is just an HTTP API.

Reading Any Wallet with the Info Endpoint

This is the part most guides skip and the one that matters most for tracking: how to read any wallet's state, not just your own. Because Hyperliquid's order book and account state are on-chain, every wallet is public. The key request types are:

• clearinghouseState — open positions, margin summary and account value for a user.
• userFills — the last 2,000 fills, each with px, sz, side, time, fee, feeToken, dir, startPosition and closedPnl.
• userFillsByTime — fills in a time range, paginated; 2,000 per response and only the 10,000 most recent fills are available.
• allMids — mid prices for every perpetual.
• userRateLimit — a wallet's API quota and current usage.

import requests

r = requests.post("https://api.hyperliquid.xyz/info", json={
    "type": "userFills",
    "user": "0xYOUR_OR_ANY_ADDRESS"   # any 42-char address
})
fills = r.json()
for f in fills[:3]:
    print(f["coin"], f["dir"], f["px"], "fee:", f["fee"], "closedPnl:", f["closedPnl"])

Note the two gotchas that bite everyone:

• Use the actual account address. If you query an agent wallet's address you get an empty result — pass the master or sub-account address instead.
• Pagination is capped. Time-range responses return at most 500 elements or blocks; use the last timestamp as the next startTime to page through. Fills stop at 10,000 most recent.

Real-Time Data with WebSocket

Polling the Info endpoint works for small apps, but the WebSocket is the right tool for live tracking. Connect to wss://api.hyperliquid.xyz/ws (mainnet) or wss://api.hyperliquid-testnet.xyz/ws (testnet) and subscribe:

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

info = Info(constants.MAINNET_API_URL, skip_ws=False)
info.subscribe({"type": "trades", "coin": "BTC"}, callback=print)

Or raw with the websockets library:

import asyncio, json, websockets

async def main():
    async with websockets.connect("wss://api.hyperliquid.xyz/ws") as ws:
        await ws.send(json.dumps({"method": "subscribe",
                                  "subscription": {"type": "trades", "coin": "BTC"}}))
        async for msg in ws:
            print(msg)

asyncio.run(main())

Subscription types include trades, allMids, l2Book, userFills, userEvents (funding, liquidations, orders), activeAssetCtx and candle, among others.

Handle reconnects. The docs are explicit: the server disconnects periodically and without announcement. Automated users must detect the disconnect and reconnect gracefully — missed data is present in the snapshot ack on reconnect, and you can backfill with the corresponding Info requests.

Exchange API and Agent Wallets

If you want to trade programmatically, the Exchange endpoint takes signed action payloads (order, cancel, withdraw…). You never sign with your main wallet: you create an agent wallet that can trade but cannot withdraw funds — a design that limits the damage if your API keys leak.

from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from eth_account import Account

account = Account.from_key("0xYOUR_AGENT_PRIVATE_KEY")
exchange = Exchange(account, constants.MAINNET_API_URL)
result = exchange.order("BTC", True, 1.0, 99000.0, {"limit": {"tif": "Gtc"}})
print(result)

Order placement is fully documented in the GitBook under Exchange endpoint, with the exact action payload schemas. For anything more than a personal bot, read the rate limit rules below before writing your first loop.

Rate Limits and the Traps That Waste Hours

The public REST API is capped at roughly 1,200 request weight per minute per IP, and most Info requests cost about 20 points plus per-item surcharges — so a naive polling loop hits the ceiling fast. On top of that, time-range queries only return 500 elements per page, and fills beyond the 10,000 most recent are gone from the API.

The practical consequences for a tracker:

• Watching many wallets requires careful batching and backoff, or you get 429 responses.
• Long-term PnL history needs continuous archiving — you cannot retroactively fetch a full year of fills.
• Funding payments and liquidations are separate event types that must be merged with fills to compute real PnL.
• Fees are charged in the fill's feeToken and include builder fees, so your PnL math must subtract them correctly.

Takeaway: reading Hyperliquid data is easy. Reading it correctly — full history, fees, funding, liquidations, pagination, reconnects — is a small engineering project.

Build Your Own Tracker vs. Hyperfolio

If your goal is a trading bot or a custom backtester, the API is the right foundation. If your goal is tracking — your own PnL, a wallet you copy, or smart money — building it yourself means owning every problem above. Here is the honest math:

Capability	DIY with Hyperliquid API	Hyperfolio
Setup time	Days to weeks	< 1 minute, no signup
Code to write	300–800+ lines (paginate, merge, store)	0 lines
Rate limits	1,200 weight/min/IP — you manage batching	None you see — read any wallet, any time
Fill history	Only last 10,000 fills via API	Continuous tracking with full PnL breakdown
PnL with fees + funding	You implement the math	Built-in, per-venue and per-wallet
Multi-venue (AsterDEX, Lighter, Robinhood Chain)	Separate integration per venue	Unified portfolio out of the box
Push alerts on fills/liquidations	You build the notification pipeline	Built-in push alerts
Price	Your dev hours	Free

Hyperfolio is built on the same public data, but it solves the tracking layer so you do not have to: connect your wallet or search any Hyperliquid address and you get PnL broken down by fees and funding, open positions, smart money radar and push alerts — no registration, no infrastructure.

Where the Raw API Still Wins

To stay honest: the API is the better choice when your goal is a trading bot, a custom backtest engine, or research datasets at scale. Hyperfolio is not a replacement for code — it is a replacement for the tracking dashboard you would otherwise build yourself. If you need order execution, custom indicators or machine-readable archives, use the SDK and the Exchange endpoint. If you need to know what a wallet did, what it earned and what it paid in fees, Hyperfolio gives you that instantly.

FAQ

Is the Hyperliquid API free?

Yes. The Info and WebSocket endpoints are public and free to use, subject to rate limits (~1,200 request weight per minute per IP). You only pay trading fees when placing orders through the Exchange endpoint.

What is the Hyperliquid WebSocket URL?

Mainnet is wss://api.hyperliquid.xyz/ws and testnet is wss://api.hyperliquid-testnet.xyz/ws. Send a subscribe message with the subscription type (e.g. trades, allMids, userFills) and handle reconnects.

Can I track another wallet's PnL with the Hyperliquid API?

Yes — every wallet is public on Hyperliquid. Query userFills and clearinghouseState with the wallet's address, then compute PnL from closedPnl minus fees and funding. Or search the address in Hyperfolio and get the breakdown instantly, without code.

What is an agent wallet in Hyperliquid?

An agent wallet is a separate key you authorize to trade on behalf of your main account. It can place and cancel orders but can never withdraw funds, which protects your balance if the key is compromised.

Does the API return fees and funding separately?

Fills include the fee field (and builderFee), while funding payments arrive as separate events. Combining both with closedPnl is exactly what Hyperfolio does automatically to show your real PnL.

Start Tracking Without Writing a Line of Code

The Hyperliquid API is a gift to builders, but not every question needs a codebase. If you want your real PnL — after fees and funding — for your own wallet or any address you are watching, open Hyperfolio, connect your wallet or paste any Hyperliquid address, and see the full breakdown for free. No registration, no API keys, no 429s.

And if you are building, pair this guide with our deep dive on calculating real PnL with fees and funding so your math matches what the exchange actually settles.