Usage Guide & Core Concepts

This section explains the fundamental concepts of the Hyperliquid Python SDK to help you build a solid understanding of how it works.

Info vs. Exchange Classes

The SDK is primarily divided into two main classes: Info and Exchange.

The Info Class

The Info class is your gateway to all public, read-only data on the Hyperliquid exchange. You do not need an API key or private key to use it. It's used for tasks like:

  • Fetching market data (order books, trade history, funding rates).
  • Querying exchange metadata (available assets, decimal precision).
  • Looking up the state of any user's account (positions, margin).
  • Subscribing to public WebSocket channels.

Example Initialization: 

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

# Initialize for read-only data access (no WebSocket connection)
info = Info(constants.TESTNET_API_URL, skip_ws=True)

# Get all mid prices
all_mids = info.all_mids()
print(all_mids)

The Exchange Class

The Exchange class is used for all actions that require authentication and cryptographic signatures. This includes any action that modifies your account's state on the exchange. You must provide a wallet with a private key to initialize this class.

Use the Exchange class for:

  • Placing, modifying, and canceling orders.
  • Adjusting leverage and margin.
  • Withdrawing funds or making transfers.
  • Managing agents, subaccounts, and vaults.

Example Initialization: 

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

# Your private key and account address
secret_key = "0x..."
account_address = "0x..."

wallet = eth_account.Account.from_key(secret_key)
exchange = Exchange(wallet, constants.TESTNET_API_URL, account_address=account_address)

# Place a limit order
order_result = exchange.order("ETH", True, 0.01, 1500, {"limit": {"tif": "Gtc"}})
print(order_result)

Mainnet vs. Testnet

Hyperliquid provides both a mainnet for real trading and a testnet for development and testing. The SDK includes constants for both API URLs.

  • Mainnet: https://api.hyperliquid.xyz
  • Testnet: https://api.hyperliquid-testnet.xyz

The SDK provides these URLs in hyperliquid.utils.constants:

from hyperliquid.utils import constants

mainnet_url = constants.MAINNET_API_URL
testnet_url = constants.TESTNET_API_URL

It is crucial to use the correct URL for your intended environment. Actions signed for one network are not valid on the other.

Asset and Order Precision (szDecimals)

When placing orders, both the size (sz) and price (px) must adhere to the precision rules of the exchange for a given asset.

  • Size Precision (szDecimals): Each asset has a specific number of decimal places allowed for its size. For example, if ETH has szDecimals of 4, you can place an order for 0.1234 ETH, but not 0.12345 ETH.
  • Price Precision: Prices can have up to 5 significant figures. For perpetuals, they are limited to 6 decimal places. For spot assets, this limit is 8 decimal places minus the asset's szDecimals.

You can fetch the szDecimals for all assets using the info.meta() method.

meta = info.meta()
# Returns a mapping like {'BTC': 5, 'ETH': 4, ...}
sz_decimals_map = {asset['name']: asset['szDecimals'] for asset in meta['universe']}

# Rounding example
raw_size = 0.123456
coin = "ETH"
rounded_size = round(raw_size, sz_decimals_map[coin]) # -> 0.1235

See the Rounding Example for a detailed implementation.

Action Signing

All private actions (like placing an order) are packaged into a structured message and signed locally using your private key. This signature proves to the Hyperliquid backend that the action was authorized by you.

The SDK handles all the complex details of message formatting and signing. There are two main categories of signed actions:

  1. L1 Actions: These are the most common actions, related to trading on the Layer 1 order book (e.g., order, cancel, updateLeverage). The SDK's sign_l1_action utility handles this.
  2. User-Signed Actions: These are special actions that are not directly tied to the L1 order book state, such as usd_transfer or withdraw_from_bridge. They use a different EIP-712 signing domain.

As a user of the Exchange class, you do not need to interact with these signing functions directly; the class methods handle it for you.