Hyperliquid Python SDK: A Practical Guide (2026)

Q: What is the Hyperliquid Python SDK?

The Hyperliquid Python SDK (hyperliquid-python-sdk) is the official Python library for interacting with the Hyperliquid exchange API. It wraps the Info API (read-only) and Exchange API (order placement) into two Python classes: Info and Exchange.

Q: Is the Hyperliquid Python SDK free to use?

Yes. The SDK is open source (MIT license) and free to use. The underlying Info API endpoints it calls are also free with no authentication required for read-only queries.

Hyperliquid's entire order book state lives on-chain, which means every wallet's positions, fills, and P&L are publicly readable via API. The official Python SDK makes that accessible without writing raw HTTP clients or handling cryptographic signing yourself.

This guide covers installation, the two main SDK classes, practical code examples for the most common use cases, rate limit behavior, and what you can realistically build.

What Is the Hyperliquid Python SDK?

The Hyperliquid Python SDK (hyperliquid-python-sdk) is the official Python library for the Hyperliquid exchange API. It wraps two API surfaces into two clean classes: Info for reading data and Exchange for placing and managing orders.

If you want to understand the underlying API it wraps, the full Hyperliquid API guide covers the three API surfaces (Info, Exchange, WebSocket) in detail. The SDK is essentially a convenience layer on top of that.

The SDK is open source under an MIT license and hosted on Hyperliquid's GitHub. It handles JSON serialization, Ethereum key signing for authenticated requests, and exposes a clean Python interface so you are not constructing raw POST bodies manually.

How Do You Install the Hyperliquid Python SDK?

Install via pip from PyPI:

pip install hyperliquid-python-sdk

The SDK requires Python 3.10 exactly. Python 3.11 and above have dependency conflicts with the current release (primarily around eth_account and related cryptographic libraries). If you install into a 3.11+ environment and hit errors, this is why.

Set up a dedicated virtual environment pinned to 3.10:

python3.10 -m venv venv
source venv/bin/activate
pip install hyperliquid-python-sdk

On Windows, replace source venv/bin/activate with venv\Scripts\activate.

Verify the install works:

from hyperliquid.info import Info
from hyperliquid.utils import constants
print("SDK loaded OK")

If that imports without error, you are ready.

How Do You Read Wallet Data with the SDK?

Reading wallet data requires no authentication. The Info class handles all read-only queries and you initialize it with just the API URL.

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

# skip_ws=True disables WebSocket for simple polling use cases
info = Info(constants.MAINNET_API_URL, skip_ws=True)

wallet = "0xYourWalletAddressHere"
state = info.user_state(wallet)

# Print open positions
for position in state["assetPositions"]:
    pos = position["position"]
    size = float(pos["szi"])
    if size != 0:
        print(f"{pos['coin']}: size={size}, entry={pos['entryPx']}, unrealized PnL={pos['unrealizedPnl']}")

The user_state() call returns the full clearinghouse state: open positions, margin summary (cross margin, isolated margin, total notional), and withdrawable balance. This is the same data shown in the Hyperliquid UI for any wallet.

This is also what makes tracking wallets on Hyperliquid programmatically possible at scale. Every wallet on the exchange is readable with the same call.

Reading Fill History

fills = info.user_fills(wallet)

for fill in fills[:10]:  # most recent 10
    print(f"{fill['coin']} {fill['side']} {fill['sz']} @ {fill['px']} | fee={fill['fee']}")

user_fills() returns up to 2,000 recent fills. For larger date ranges, use user_fills_by_time() with start/end timestamps (in milliseconds):

import time

now_ms = int(time.time() * 1000)
seven_days_ago_ms = now_ms - (7 * 24 * 60 * 60 * 1000)

fills = info.user_fills_by_time(wallet, seven_days_ago_ms, now_ms)

How Do You Get Market Data?

Market data queries are also unauthenticated. A few of the most useful endpoints:

Mid Prices for All Assets

mids = info.all_mids()
# Returns a dict: {"BTC": "83421.5", "ETH": "1894.2", ...}
print(f"BTC mid: {mids['BTC']}")

This is the cheapest way to check current prices. It returns a single dictionary with mid prices for every listed perpetual in one call.

Order Book Depth

book = info.l2_snapshot("BTC")

bids = book["levels"][0]  # list of [price, size] pairs, best bid first
asks = book["levels"][1]  # list of [price, size] pairs, best ask first

best_bid = bids[0]
best_ask = asks[0]
print(f"BTC spread: {best_ask[0]} / {best_bid[0]}")

OHLCV Candle Data

candles = info.candles_snapshot("BTC", "1h", start_time_ms, end_time_ms)

for candle in candles[-5:]:  # last 5 candles
    print(f"open={candle['o']} high={candle['h']} low={candle['l']} close={candle['c']} vol={candle['v']}")

The candleSnapshot endpoint supports intervals from 1m to 1M and returns up to 5,000 candles per call. It is the practical starting point for backtesting or building on-chain analytics on Hyperliquid.

How Do You Place Orders with the SDK?

Order placement requires authentication via Ethereum key signing. The Exchange class handles this. The recommended pattern is to use a dedicated API wallet rather than your main wallet's private key directly.

Create an API wallet at app.hyperliquid.xyz/API, then initialize the Exchange class:

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

# API wallet private key (NOT your main wallet key)
api_key = "0xYourAPIWalletPrivateKeyHere"
account = eth_account.Account.from_key(api_key)

exchange = Exchange(
    account,
    constants.MAINNET_API_URL,
    account_address="0xYourMainWalletAddress"  # main wallet, not the API wallet
)

The account_address parameter is critical. It must be your main wallet address. If you omit it and your API wallet differs from your main wallet, orders will not link to the right account.

Placing a Market Order

# Market buy 0.01 BTC with up to 1% slippage
result = exchange.market_open(
    name="BTC",
    is_buy=True,
    sz=0.01,
    slippage=0.01
)
print(result)

Placing a Limit Order

result = exchange.order(
    name="BTC",
    is_buy=True,
    sz=0.01,
    limit_px=80000.0,
    order_type={"limit": {"tif": "Gtc"}}  # Good-till-cancelled
)

tif options are Gtc (good-till-cancelled), Alo (add liquidity only / post-only), and Ioc (immediate-or-cancel).

What Are the SDK Rate Limits?

The SDK uses the same rate limit system as the raw API. Requests draw from a weight budget of 1,200 units per minute.

Weight costs per endpoint type:

l2Book, allMids, clearinghouseState, orderStatus: 2 weight units
Exchange API orders: 1 weight unit
Most other Info API endpoints: 20 weight units

At 20 weight units per general query, you get roughly 60 calls per minute from that endpoint type before hitting the cap. For scraping data across many wallets, this is the practical ceiling to design around.

Each wallet also accumulates a long-term buffer: 1 additional request per 1 USDC of trading volume since account creation, starting with a base buffer of 10,000. Active traders rarely hit limits. Bots polling many addresses at once do.

Check your remaining rate limit budget programmatically:

rate_limit = info.query_user_rate_limit(wallet)
print(rate_limit)
# Returns current consumed requests and the cumulative limit

Build retry logic with exponential backoff for production bots. A 429 response means you have exhausted your budget for the current window.

What Can You Build with the Hyperliquid Python SDK?

The combination of public position data and a programmatic trading interface makes a range of projects practical.

Portfolio trackers: Query any wallet's positions, fill history, and funding payments to build custom P&L dashboards. Hyperliquid's native UI shows recent activity but does not expose everything a serious trader wants, like custom metric breakdowns or cross-wallet aggregation.

Data pipelines: Fetch candle data and fills for backtesting or strategy research. The candleSnapshot endpoint returns clean OHLCV data without needing a paid data provider.

Alerting systems: Poll allMids and clearinghouseState on a schedule to alert on price movements or when tracked wallets open new positions. A simple cron job and a Telegram bot is enough infrastructure for a basic version.

Automated trading bots: The Exchange API gives you market orders, limit orders, and cancellations. Pair it with the WebSocket for low-latency signal input and you have the core infrastructure for a systematic strategy.

Wallet monitoring tools: Because all positions are public, you can build screeners that watch a curated list of wallets and surface when specific traders open or close positions. This is the raw capability behind what what Hyperliquid is making possible for on-chain intelligence tools.

The gotcha for wallet monitoring at scale: polling hundreds of addresses with 20-weight queries burns through your budget fast. You need to be deliberate about polling frequency, batching, and which endpoints you hit.

SDK Best Practices

A few patterns worth adopting from the start:

Use skip_ws=True for simple scripts. The Info class opens a WebSocket connection by default. If you are just running batch queries, disable it to avoid unnecessary connection overhead.

Never hardcode private keys. Load them from environment variables or a secrets manager:

import os
api_key = os.environ["HL_API_KEY"]

Implement retry logic. The API returns 429s under rate pressure and occasionally returns 5xx errors. A simple retry with backoff prevents your script from crashing on transient errors.

Always pass account_address on Exchange. This is the most common setup error. If your API wallet address differs from your main wallet, omitting account_address will cause orders to fail or go to the wrong account.

Handle spot coin formats separately. Spot assets use @{index} format rather than the ticker. If you are querying both perpetuals and spot, branch your coin name handling accordingly.

Building From Scratch vs. Using Pre-Built Intelligence

The SDK gives you the raw building blocks. Reading a wallet's positions is a few lines of code. The harder part is everything around it: persistent storage for historical data, a scoring system that identifies which wallets are actually worth following, deduplication for wallets that move in lockstep, and signal logic that only fires when there is genuine conviction across multiple independent actors.

That is the infrastructure HyprSwarm's live intelligence dashboard is built around. It pulls and processes position data from a curated universe of Hyperliquid wallets, rates each one based on directional accuracy over time, and surfaces Swarm Formation signals when the top-rated wallets converge on the same side of a trade.

If you are exploring what the SDK can do and want the context of how production-scale on-chain data works, on-chain analytics on Hyperliquid is worth reading next. If you would rather skip straight to the signals layer, the dashboard is live at hyprswarm.com.

Hyperliquid Python SDK FAQ

What is the Hyperliquid Python SDK?

The Hyperliquid Python SDK (hyperliquid-python-sdk) is the official Python library for interacting with the Hyperliquid exchange API. It wraps the Info API (read-only) and Exchange API (order placement) into two Python classes: Info and Exchange.

What Python version does the Hyperliquid Python SDK require?

The SDK requires Python 3.10 exactly. Python 3.11 and above have dependency conflicts with the current release. Pin your virtual environment to 3.10 for reliable installs.

Is the Hyperliquid Python SDK free to use?

Yes. The SDK is open source under an MIT license and free to use. The underlying Info API endpoints are also free with no authentication required for read-only queries.

Can I read any wallet's positions with the SDK?

Yes. Hyperliquid runs its order book on-chain, which means all wallet positions are publicly readable. You can query any wallet address using info.user_state() with no authentication required.

Does the SDK support WebSocket streaming?

The SDK includes a WebSocket manager class for subscribing to real-time data streams. For simpler use cases, initialize the Info class with skip_ws=True to disable WebSocket and use HTTP polling only.

Code examples are simplified for clarity. Add error handling, retry logic, and proper secrets management before deploying anything to production. Trading perpetual futures carries significant financial risk.