Hyperliquid runs the order book, positions, and account state entirely on-chain. That means everything a trader can see in the UI is also accessible programmatically, with no permissioning, no KYC, and no API key sign-up form.

This guide covers the three API surfaces you'll actually use: the Info API for reading data, the Exchange API for placing orders, and the WebSocket for streaming. It includes Python examples using the official SDK, rate limit details, and the gotchas that bite developers early.

What Are the Hyperliquid API Endpoints?

Hyperliquid exposes three main API surfaces. You will likely use all three if you are building anything serious.

Info API (POST https://api.hyperliquid.xyz/info) handles all read operations. Market data, wallet positions, order history, fills, fees, vault data. No authentication required. This is where most developers spend the majority of their time.

Exchange API (POST https://api.hyperliquid.xyz/exchange) handles write operations. Placing orders, cancelling orders, modifying positions, approving builder fees. Requires a signed request with your private key.

WebSocket (wss://api.hyperliquid.xyz/ws) provides push-based streaming for price feeds, order book updates, trade ticks, and user events. More efficient than polling the Info API for anything latency-sensitive.

The testnet equivalents use api.hyperliquid-testnet.xyz. If you are testing a strategy on Hyperliquid testnet before going live, swap the base URL and you get identical behavior with paper funds.

The Info API: Reading All Exchange Data

The Info API handles every read-only query. You send a POST request with a JSON body specifying the request type and parameters. No signing required.

Market Data Queries

The most commonly used market data methods:

  • allMids: Returns mid prices for every asset currently listed. Fast and cheap. Good for building dashboards or screening for moves.
  • l2Book: Returns up to 20 levels of order book depth per side for a given asset. Supports optional aggregation. Costs 2 weight units (cheaper than most).
  • candleSnapshot: Returns up to 5,000 OHLCV candles in intervals from 1 minute to 1 month. Solid for backtesting price action strategies.

Wallet and Position Queries

This is the part that makes Hyperliquid worth building on. Every wallet's state is public.

  • clearinghouseState: Returns the full position state for a wallet address. Open positions, margin, unrealized P&L, withdrawable balance.
  • userFills: Up to 2,000 most recent fills. For pagination, use userFillsByTime with time-range filtering (limited to 10,000 fills, with 500 per page).
  • openOrders: All active open orders for a wallet.
  • portfolio: Historical account value and P&L across multiple timeframes. This is what powers Hyperliquid stats dashboards.

One important note: always pass the main account address, not an agent wallet address. If you pass an agent key, the query returns incorrect or empty data.

Spot Format Gotcha

Spot assets use a different coin format from perpetuals. Perpetuals use the ticker directly (BTC, ETH). Spot uses @{index} format, where the index corresponds to the asset's spot listing number. If you are querying spot data and getting empty results, this is probably why.

How Do You Authenticate with the Hyperliquid API?

Authentication on the Exchange API is cryptographic, using Ethereum-compatible key signing. There is no token to request, no OAuth flow, and no registration. If you have a funded wallet, you can start placing orders.

Two authentication patterns:

Main wallet key: Use your primary wallet's private key directly. Works, but exposing your main key in a bot's environment is a security risk.

API wallet: Create a dedicated subkey at app.hyperliquid.xyz/API. This key can place and cancel orders on behalf of your main wallet, but cannot withdraw funds. For bots, this is the right approach. Configure it with your main wallet's public address as account_address and the API wallet's private key as secret_key.

Getting Started with the Hyperliquid Python SDK

The official SDK (hyperliquid-python-sdk) wraps the Info and Exchange APIs into two clean classes.

Install it:

pip install hyperliquid-python-sdk

The SDK requires Python 3.10 exactly. Higher versions have dependency conflicts with the current release. Pin your environment.

Reading Wallet Data

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

# No authentication needed for read-only queries
info = Info(constants.MAINNET_API_URL, skip_ws=True)

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

# state contains positions, margin summary, withdrawable balance
for position in state["assetPositions"]:
    pos = position["position"]
    print(f"{pos['coin']}: {pos['szi']} @ entry {pos['entryPx']}")

Placing an Order

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

# Load your API wallet private key
key = "0xYourPrivateKeyHere"
account = eth_account.Account.from_key(key)

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

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

Fetching Open Interest

Open interest data comes through the perpetuals meta endpoint:

meta = info.meta()
ctx_data = info.meta_and_asset_ctxs()

for asset_ctx in ctx_data[1]:
    print(f"OI: {asset_ctx['openInterest']}")

How Does the WebSocket API Work?

The WebSocket is the right choice when you need low-latency updates. Polling the Info API for price changes is fine for analytics. For a trading bot that reacts to order book shifts, you want push-based data.

Connect to wss://api.hyperliquid.xyz/ws and send a JSON subscription message:

import asyncio
import json
import websockets

async def stream_trades():
    uri = "wss://api.hyperliquid.xyz/ws"
    async with websockets.connect(uri) as ws:
        # Subscribe to BTC trades
        sub = {
            "method": "subscribe",
            "subscription": {"type": "trades", "coin": "BTC"}
        }
        await ws.send(json.dumps(sub))

        async for message in ws:
            data = json.loads(message)
            # First message has isSnapshot: true with recent history
            # Subsequent messages are live trade ticks
            print(data)

asyncio.run(stream_trades())

Useful WebSocket Subscriptions

  • trades: Live trade ticks for a specific asset. Includes price, size, side, and liquidation flag.
  • l2Book: Order book snapshot updates. Sent when the book changes.
  • bbo: Best bid/offer only. Lighter than the full book. Sent only when the BBO actually changes on a block.
  • candle: OHLCV candles in real time across 14 intervals (1m to 1M).
  • userEvents: Fills, liquidations, and funding payments for your wallet. Requires your wallet address.
  • clearinghouseState: Real-time position and margin updates for a wallet.

The WebSocket limit is 1,000 subscriptions per IP address. If you are building multi-asset monitoring and approaching that limit, consider a routing layer that aggregates subscriptions across multiple connections.

Each subscription sends an initial snapshot (isSnapshot: true) followed by delta updates. Always handle the snapshot first to initialize your local state.

What Are the Hyperliquid API Rate Limits?

Rate limits use a weight system. Every request draws from a shared budget of 1,200 weight units per minute.

Endpoint weights: - Exchange API orders: 1 weight per request - l2Book, allMids, clearinghouseState, orderStatus: 2 weight units - Most other Info API endpoints: 20 weight units

Each wallet also accumulates a long-term buffer: 1 additional request per 1 USDC traded since account inception, starting with an initial buffer of 10,000. Active traders on Hyperliquid rarely hit rate limits. Bots scraping data across many wallets do.

Use the userRateLimit endpoint to check your remaining budget before hitting a wall in production.

For scraping data across many wallet addresses (as part of wallet tracking or on-chain analytics), batch your requests thoughtfully. The 20-weight cost on most info queries means you get roughly 60 calls per minute before hitting the cap from that endpoint type alone.

What Can You Build with the Hyperliquid API?

The combination of public position data and a clean Exchange API makes a wide range of things practical.

Automated trading bots: The Exchange API plus WebSocket gives you everything needed for systematic strategies. Market orders, limit orders, TWAP execution, stop losses. The Python SDK handles the signing. The main constraint is latency, not API access.

Wallet intelligence dashboards: Read every wallet's positions, entries, and P&L without permission. This is what makes smart money tracking possible at scale. You can build a screener that monitors hundreds of wallets and alerts when high-rated traders open new positions.

Custom analytics: Fetch fills history, funding payments, and portfolio values to build performance analytics that go beyond what the native UI shows. Pair with Hyperliquid's stats data for exchange-level context.

Arbitrage and hedging infrastructure: For funds running positions across venues, the Exchange API enables automated position management on the Hyperliquid side. Funding rate arbitrage between Hyperliquid and centralized exchanges is a common use case given that you can trade on Hyperliquid with no KYC.

Copy trading systems: Query what target wallets are holding, then mirror positions through the Exchange API. The data latency from polling is typically a few seconds, which is acceptable for position-level copy trading (less so for scalping).

The Gap Between Raw API Access and Actionable Intelligence

The API gives you the data. It does not tell you what to do with it.

Tracking one wallet is straightforward. Tracking a thousand wallets, filtering for the ones that have actually outperformed consistently, weighting signals by each wallet's track record, and surfacing when there is genuine consensus across the best performers, that is a different problem.

That infrastructure is what HyprSwarm is built around. The dashboard aggregates position data from over a thousand tracked wallets, rates each one using an ELO-inspired scoring system that adjusts for directional accuracy over time, and surfaces Swarm Formation signals when the top-rated wallets converge on the same side of a trade. The raw API access is table stakes. The signal layer on top is where the edge comes from.

Building that yourself is possible. It requires a persistent data store, a scoring system that degrades gracefully for wallets that go inactive, deduplication logic for wallets that move in lockstep, and enough compute to keep up with real-time position changes. If you want to understand how on-chain analytics work on Hyperliquid, starting with the API directly is the right move.

Hyperliquid API FAQ

Is the Hyperliquid API free to use?

Yes. The Info API and WebSocket feeds require no authentication and are free to query. You only need a private key when using the Exchange API to place or cancel orders.

What are the Hyperliquid API rate limits?

Requests draw from a shared weight budget of 1,200 per minute. Most info queries cost 20 weight units. Order endpoints cost 1 weight unit. Addresses also get a cumulative buffer based on trading volume (1 extra request per 1 USDC traded since account inception), starting at 10,000.

Do I need to verify my identity to use the Hyperliquid API?

No KYC is required. Authentication is purely cryptographic. You sign requests with an Ethereum-compatible private key, either your main wallet key or a dedicated API wallet key that you create in the Hyperliquid UI.

What Python version does the Hyperliquid SDK require?

The official hyperliquid-python-sdk requires Python 3.10 exactly for development. Python 3.11 and above have dependency compatibility issues with the current SDK release. For production bots, pin your environment to 3.10.

Can I stream real-time price data with the Hyperliquid API?

Yes. The WebSocket API streams order book updates, trade ticks, OHLCV candles, and best bid/offer changes in real time. You connect to wss://api.hyperliquid.xyz/ws and send a JSON subscription message.

How do I check Hyperliquid fees before placing an order?

Query the userFees endpoint via the Info API with your wallet address. It returns your current fee tier, applicable Hyperliquid fees for maker/taker, and any active discounts.

This guide is for educational purposes. Code examples are simplified for clarity and may need error handling, retry logic, and security hardening before production use. Trading perpetual futures carries significant risk of loss.