API Reference

This page provides a detailed reference for the core classes and methods in the Hyperliquid Python SDK.

Info Class

The Info class provides methods for accessing public, read-only data from the Hyperliquid API.

Initialization: 

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

# Initialize with WebSocket support (default)
info = Info(constants.MAINNET_API_URL)

# Initialize without WebSocket support for REST API calls only
info_no_ws = Info(constants.MAINNET_API_URL, skip_ws=True)

Methods

  • user_state(address: str): Retrieves the trading state for a user, including positions and margin summary.
  • spot_user_state(address: str): Retrieves the spot trading state for a user, including token balances.
  • open_orders(address: str): Retrieves a list of all open orders for a user.
  • all_mids(): Retrieves the current mid-market price for all actively traded assets.
  • user_fills(address: str): Retrieves the most recent trade fills for a user.
  • user_fills_by_time(address: str, start_time: int, end_time: Optional[int] = None): Retrieves user fills within a specified millisecond timestamp range.
  • meta(): Retrieves the exchange metadata, including asset information like szDecimals.
  • spot_meta(): Retrieves metadata for spot markets.
  • funding_history(name: str, startTime: int, endTime: Optional[int] = None): Retrieves funding rate history for a specific asset.
  • l2_snapshot(name: str): Retrieves a snapshot of the Layer 2 order book for an asset.
  • candles_snapshot(name: str, interval: str, startTime: int, endTime: int): Retrieves historical candlestick data for an asset.
  • query_order_by_oid(user: str, oid: int): Queries the status of a specific order by its Order ID (OID).
  • query_order_by_cloid(user: str, cloid: Cloid): Queries the status of a specific order by its client-provided ID (CLOID).

WebSocket Methods

These methods are only available if skip_ws was False during initialization.

  • subscribe(subscription: Subscription, callback: Callable[[Any], None]) -> int: Subscribes to a WebSocket channel.
    • subscription: A dictionary specifying the subscription type (e.g., {"type": "l2Book", "coin": "ETH"}).
    • callback: A function that will be called with each message received on the channel.
    • Returns a subscription ID.
  • unsubscribe(subscription: Subscription, subscription_id: int) -> bool: Unsubscribes from a channel.
    • Returns True if successful.

Exchange Class

The Exchange class provides methods for performing signed actions, such as trading and account management.

Initialization: 

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

secret_key = "0x..."
address = "0x..."

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

Order Placement Methods

  • order(name: str, is_buy: bool, sz: float, limit_px: float, order_type: OrderType, reduce_only: bool = False, cloid: Optional[Cloid] = None): Places a single order with detailed parameters.
  • bulk_orders(order_requests: List[OrderRequest]): Places multiple orders in a single atomic transaction.
  • market_open(name: str, is_buy: bool, sz: float, px: Optional[float] = None, slippage: float = 0.05): Opens a position with a market order.
  • market_close(coin: str, sz: Optional[float] = None, px: Optional[float] = None, slippage: float = 0.05): Closes an entire position for a given coin with a market order.

Order Management Methods

  • cancel(name: str, oid: int): Cancels a single order by its OID.
  • cancel_by_cloid(name: str, cloid: Cloid): Cancels a single order by its CLOID.
  • bulk_cancel(cancel_requests: List[CancelRequest]): Cancels multiple orders in a single atomic transaction.
  • modify_order(oid: OidOrCloid, name: str, is_buy: bool, sz: float, limit_px: float, order_type: OrderType): Modifies an existing order.

Account Management Methods

  • update_leverage(leverage: int, name: str, is_cross: bool = True): Sets the leverage for an asset, either cross-margin or isolated.
  • update_isolated_margin(amount: float, name: str): Adds or removes margin from an isolated margin position.
  • usd_transfer(amount: float, destination: str): Transfers USDC between Hyperliquid user accounts.
  • spot_transfer(amount: float, destination: str, token: str): Transfers a spot asset between Hyperliquid user accounts.
  • withdraw_from_bridge(amount: float, destination: str): Initiates a withdrawal of USDC to an L1 wallet via the bridge.
  • approve_agent(name: Optional[str] = None): Creates and approves a new API wallet (agent) for trading. Returns the API response and the new agent's private key.
  • set_referrer(code: str): Sets a referral code for your account.
  • create_sub_account(name: str): Creates a new subaccount under your main account.