Getting Started with the Hyperliquid API: A Beginner’s Guide for 2026

• hyperliquid api

• hyperliquid api guide

• Hyperliquid API tutorial

• on-chain trading API

If you have ever wanted to trade on-chain perpetuals programmatically, the Hyperliquid API is one of the closest DEX experiences to a centralized exchange API. It supports market data queries, account state, order placement, and WebSocket streams, making it useful for everything from simple automation to more advanced market-making systems.

This guide is written for developers who are new to the Hyperliquid API. We’ll cover the API structure, authentication model, basic examples, common pitfalls, and practical security considerations.

What can the Hyperliquid API do?

Based on Hyperliquid’s official documentation, the API can be grouped into three main areas:

Info endpoints

Info endpoints are used to fetch public and account-related data, including:

• Current order book snapshots
• Recent trades
• Funding rate history
• Account positions
• Historical orders

These endpoints do not require signatures and are publicly accessible.

Exchange endpoints

Exchange endpoints are used for write operations, such as:

• Placing orders
• Cancelling orders
• Updating leverage
• Adjusting margin

These requests must be signed with a wallet key. Because they can directly affect funds and positions, they require much stricter security handling.

WebSocket streams

Hyperliquid also provides WebSocket streams for real-time data, including:

• Order book updates
• Trade streams
• Account events
• Funding-related data

WebSockets are useful for strategies that need faster reaction times than polling REST endpoints.

Base URL and API structure

The REST API base URL is:

https://api.hyperliquid.xyz

All REST requests use the POST method with a JSON request body.

• Info requests go to /info
• Exchange requests go to /exchange

Always check the official Hyperliquid documentation for the latest field definitions. The examples below are for getting started and should be verified before you use them in production.

Authentication model

Hyperliquid’s trading API uses EIP-712 structured data signatures instead of the traditional API key + secret model.

That means:

• You use an Ethereum-compatible wallet address as your identity.
• Trading requests must be signed with the corresponding private key.
• The signature proves that the request was authorized by the holder of that address.
• There is no separate API key that can be leaked or revoked in the same way as a centralized exchange key.

This design removes one common attack surface, but it also makes private key security critical. If a private key is compromised, an attacker may be able to produce valid signatures and control the account.

This is where OneKey can be useful. A OneKey hardware wallet keeps private keys isolated inside the device, and signing happens on the hardware wallet instead of exposing the key to your computer or the network. For developers and quantitative traders using APIs, a practical approach is to create a dedicated account or sub-account for API trading, keeping it separate from your main holdings.

Info endpoint example: Python and curl

Here is a simple request to fetch metadata for all tradable assets.

Using curl:

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "meta"}'

Using Python with requests:

import requests
import json

url = "https://api.hyperliquid.xyz/info"
payload = {"type": "meta"}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

print(json.dumps(data, indent=2))

The response includes basic information about tradable contracts, such as asset names, maximum leverage, and minimum order size. Since this is a public Info endpoint, no authentication is required. It is one of the best places to start when learning the Hyperliquid API.

Querying account positions

You can also query the state of a specific address through an Info endpoint:

payload = {
    "type": "clearinghouseState",
    "user": "0xYOUR_WALLET_ADDRESS"
}

response = requests.post(url, json=payload, headers=headers)

The response can include margin balance, open positions, unrealized PnL, and related account data.

Important: this is publicly queryable on-chain-related data. Anyone can look up the position state of any address, so do not assume account position data is private.

WebSocket real-time subscriptions

The WebSocket endpoint is:

wss://api.hyperliquid.xyz/ws

After connecting, you can send a subscription message to start receiving live updates.

Example: subscribing to the BTC L2 order book:

import asyncio
import websockets
import json

async def subscribe_orderbook():
    uri = "wss://api.hyperliquid.xyz/ws"

    async with websockets.connect(uri) as ws:
        sub_msg = {
            "method": "subscribe",
            "subscription": {
                "type": "l2Book",
                "coin": "BTC"
            }
        }

        await ws.send(json.dumps(sub_msg))

        while True:
            msg = await ws.recv()
            data = json.loads(msg)
            print(data)

asyncio.run(subscribe_orderbook())

Common subscription types include:

• l2Book: L2 order book updates
• trades: recent trades
• userEvents: account events, tied to a user address
• Funding-related global data

Check the official documentation for the latest subscription schema and required fields.

Common pitfalls

Incorrect request formatting

Strict JSON formatting is one of the most common sources of errors. Hyperliquid’s API expects exact field names and types. For example, sending a number as a string may cause a request to fail.

If an error message is not obvious, compare your payload carefully against the official docs or a working SDK example.

EIP-712 signature construction

EIP-712 signing includes details such as typed data definitions and domain separation. Implementing it manually is easy to get wrong.

For most developers, using a maintained Hyperliquid SDK in Python or JavaScript is a better starting point. SDKs can reduce boilerplate and lower the chance of malformed signatures.

Timestamp synchronization

Trading requests often include a current timestamp and may only be valid within a limited time window. If your local machine clock is too far out of sync, requests may be rejected as expired.

Use reliable time synchronization on any machine running automated trading code.

Network failure handling

Production systems must handle network interruptions.

A WebSocket connection can drop. REST requests can fail temporarily. Your strategy should include:

• Automatic reconnect logic
• Request retries where appropriate
• Backoff behavior
• State reconciliation after reconnecting

Do not assume that a single request or subscription will remain healthy indefinitely.

Rate limits

Hyperliquid applies different rate limits to different endpoint categories. The exact limits should always be checked in the latest official documentation.

In general:

• Info endpoints are usually more permissive.
• Exchange endpoints are stricter because they affect trading activity.
• High-frequency order placement and cancellation strategies need extra care.

If you receive a 429 response, stop sending requests immediately and use exponential backoff instead of blindly retrying.

Development environment recommendations

Before deploying any strategy with meaningful capital, consider the following steps.

Start with small live size

It has been reported that Hyperliquid does not currently provide a separate perpetuals testnet environment for full trading simulation. If you need to test live execution, use very small position sizes first.

Even a correct-looking strategy can behave unexpectedly once real fills, latency, funding, and liquidation mechanics are involved.

Separate your signing key from your main funds

Do not use the same wallet that holds your long-term assets as your API trading wallet.

A more practical setup is:

• Create a dedicated API trading account or separate address.
• Fund it only with the amount you are prepared to risk for that strategy.
• Keep your main holdings isolated.
• Monitor open orders, positions, and margin regularly.

OneKey’s multi-account workflow can help with this separation. You can use OneKey to manage different accounts for different purposes, while keeping private keys protected by hardware-level isolation.

Review secure wallet integration patterns

For developers, OneKey GitHub resources may be useful as references for how wallet signing can be integrated safely at the application layer.

Where OneKey Perps fits in

If you are exploring Hyperliquid because you want a smoother on-chain perps workflow, you do not have to start with API trading immediately.

OneKey Perps provides a practical way to access perpetuals trading from within the OneKey ecosystem, while keeping wallet security at the center of the workflow. For many users, the better progression is:

1. Use OneKey to create and secure a dedicated trading account.
2. Try manual perps trading through OneKey Perps with small size.
3. Understand margin, liquidation, funding, and order behavior.
4. Only then consider API-based automation for strategies you fully understand.

This approach helps reduce operational mistakes and keeps your private key management separate from your trading logic.

FAQ

Q1: Do I need to register an account to use the Hyperliquid API?

No traditional registration is required. You need an Ethereum-compatible wallet address. After the address has completed its first relevant action on Hyperliquid, such as funding or interacting with the protocol, it can be used with the API.

There is no standard email registration or KYC flow in the same sense as many centralized exchanges.

Q2: Is there a Python SDK for the Hyperliquid API?

Yes, SDKs are available from official and community sources. The best practice is to check Hyperliquid’s official GitHub or documentation for the currently maintained version.

Using an SDK can simplify request formatting, EIP-712 signing, and error handling.

Q3: How should I reconnect after a WebSocket disconnects?

Implement heartbeat checks and automatic reconnect logic in your WebSocket client.

A common approach is:

1. Detect a broken connection.
2. Wait briefly, such as 1–5 seconds.
3. Reconnect.
4. Re-subscribe to the required channels.
5. Reconcile local state with REST queries if needed.

For repeated failures, use exponential backoff to avoid creating a request storm during service or network issues.

Q4: How can I improve API trading fund security?

API trading security depends heavily on private key management.

Using a OneKey hardware wallet for signing helps ensure that private keys are not exposed to internet-connected devices. You should also:

• Use a dedicated API trading account.
• Limit the funds allocated to automated strategies.
• Review open orders and positions regularly.
• Avoid storing plaintext private keys on servers.
• Keep strategy permissions and account exposure as limited as possible.

Q5: Does Hyperliquid support conditional orders and stop-loss orders?

Hyperliquid supports trigger order types, including logic commonly used for stop-loss and take-profit behavior. Check the official documentation for the latest parameters, order types, and trigger conditions.

For more complex rules, you can also implement conditional logic at the strategy layer by monitoring market data and account state.

Summary

The Hyperliquid API gives developers a capable on-chain perps interface with public market data, account queries, trading endpoints, and real-time WebSocket streams. Info endpoints are a good starting point for analytics and monitoring tools, while Exchange endpoints and WebSockets can support more advanced automated trading systems.

The key security takeaway is simple: EIP-712 signing makes private key management central to your risk model. If your trading key is exposed, your account can be exposed.

Using OneKey as your wallet and signing layer can help isolate private keys and reduce operational risk. If you are just getting started, consider downloading OneKey, setting up a dedicated trading account, and trying OneKey Perps with small size before moving into API-based automation.

---Disclaimer---

This article is for technical reference only and is not investment, financial, legal, or tax advice. API trading involves automation risk, and strategy bugs can cause unexpected losses. Perpetual futures are highly risky and may involve leverage, liquidation, and rapid market moves. Only participate after you fully understand the technical and market risks. Past strategy performance does not indicate future results.