Hyperliquid Python SDK

Common errors

• ModuleNotFoundError: No module named 'hyperliquid'

  cause The `hyperliquid-python-sdk` library is not installed in your current Python environment.
  fix Run `pip install hyperliquid-python-sdk` to install the library.

• hyperliquid.exceptions.HyperliquidError: invalid signature

  cause The private key provided to the `Wallet` is incorrect, or the `Exchange` client is attempting to sign a request with a key that doesn't match the associated account on Hyperliquid, or the payload itself is malformed before signing.
  fix Verify that your `HL_WALLET_PRIVATE_KEY` environment variable holds the correct private key corresponding to the Hyperliquid account you are trying to interact with. Ensure no leading/trailing spaces or incorrect characters. Also confirm you are using the correct network (Testnet/Mainnet) for the key.

• hyperliquid.exceptions.HyperliquidError: Insufficient margin

  cause An order placement or position adjustment failed because the account does not have enough collateral (margin) to cover the required initial margin for the operation.
  fix Ensure your Hyperliquid account has sufficient funds. You may need to deposit more collateral or reduce the size of your trade.

• aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host api.hyperliquid.xyz:443 ssl:True [hostname 'api.hyperliquid.xyz' doesn't match 'hyperliquid.xyz']

  cause This specific error indicates an SSL certificate mismatch or a general network connectivity issue to the Hyperliquid API endpoint.
  fix Check your internet connection, firewall settings, and ensure the base URL for the `Info` and `Exchange` clients is correct (e.g., `https://api.hyperliquid.xyz` for mainnet, `https://api.testnet.hyperliquid.xyz` for testnet). Rarely, it might indicate a temporary issue with Hyperliquid's API servers.

Warnings

• breaking The `perp_dex_class_transfer` action was removed in version `0.16.0`. Any code attempting to use this function will now fail.
  Fix: Review your code for `perp_dex_class_transfer` calls and update to use alternative or new transfer mechanisms if applicable, or remove the deprecated functionality.
• gotcha The library is under active and rapid development. Frequent minor version updates often introduce new features, but also new API parameters or slight behavior changes, especially in newer abstraction layers.
  Fix: Always pin your dependency to a specific minor version (e.g., `hyperliquid-python-sdk==0.23.*`) and review release notes for each update before upgrading in production environments.
• gotcha Handling private keys: The `Exchange` client requires a `Wallet` object initialized with a private key. Incorrect handling (e.g., hardcoding keys, using wrong keys for testnet/mainnet) can lead to 'invalid signature' errors or security risks.
  Fix: Store private keys securely, preferably using environment variables or a secret management service. Always verify you're using the correct key for the targeted network (testnet vs. mainnet).

Install

• pip install hyperliquid-python-sdk Install latest version

Imports

• Info

  from hyperliquid.info import Info

  Used for fetching public market data and account information.
• Exchange

  from hyperliquid.exchange import Exchange

  Used for authenticated operations like placing orders, managing positions, and transferring funds.
• Wallet

  from hyperliquid.utils import Wallet

  Helper class to manage cryptographic keys and generate wallet addresses.

Quickstart

This quickstart demonstrates how to initialize the `Info` client to fetch public market data like mid prices for assets on Hyperliquid Mainnet. It also includes commented-out code showing how to set up the `Exchange` client for authenticated operations, which requires a private key from an environment variable (`HL_WALLET_PRIVATE_KEY`). Ensure Python 3.9+ is used.

import os
from hyperliquid.info import Info

# Configuration
# Mainnet API URL for public data
MAINNET_API_URL = "https://api.hyperliquid.xyz"

try:
    # Initialize Info client for public market data
    info_client = Info(MAINNET_API_URL)

    print(f"Fetching market data from Hyperliquid Mainnet: {MAINNET_API_URL}")

    # Get all mid prices
    mids = info_client.all_mids()
    print("\nMid prices for all assets:")
    # Print only a few for brevity
    for i, (asset, price) in enumerate(mids.items()):
        if i >= 5: # Limit to first 5 assets
            break
        print(f"  {asset}: {price}")
    if len(mids) > 5:
        print(f"  ... ({len(mids) - 5} more assets)")

    # Example of getting an asset's ID
    eth_asset_id = info_client.asset_to_id("ETH")
    print(f"\nETH Asset ID: {eth_asset_id}")

    # To use the Exchange client for authenticated operations (e.g., placing orders),
    # you would need a private key set in an environment variable:
    # PRIVATE_KEY = os.environ.get("HL_WALLET_PRIVATE_KEY", "")
    # if PRIVATE_KEY:
    #     from hyperliquid.utils import Wallet
    #     from hyperliquid.exchange import Exchange
    #     wallet = Wallet(PRIVATE_KEY)
    #     exchange_client = Exchange(wallet, MAINNET_API_URL)
    #     print(f"\nExchange client initialized for address: {wallet.address}")
    # else:
    #     print("\nSet HL_WALLET_PRIVATE_KEY environment variable to use Exchange client.")

except Exception as e:
    print(f"An error occurred: {e}")