Skip to content

Info Endpoint¤

Hyperliquid's Official Info Endpoint Docs

Overview¤

The Info endpoint provides comprehensive access to market data, user information, and trading details for both perpetual and spot markets on Hyperliquid. This endpoint serves as the primary source for retrieving real-time and historical data about the exchange state, user positions, orders, and market conditions.

The Info class offers methods to interact with various aspects of the exchange, from basic market data like price feeds and order books to detailed user-specific information such as trading history, funding payments, and account states. All methods are asynchronous and designed to work seamlessly with both perpetual and spot trading functionalities.

Key Features¤

  • Market Data: Access real-time prices, order books, and candlestick data
  • User Information: Retrieve account states, positions, and trading history
  • Order Management: Check order statuses and open orders
  • Historical Data: Access funding history, fill history, and ledger updates
  • Cross-Product Support: Works with both perpetual and spot markets
  • Rate Limiting: Built-in rate limit information for API usage
  • Flexible Authentication: Support for both address strings and Account objects
  • Vault Support: Access vault-specific information and equities
  • Delegation Features: Query staking delegation information and rewards

Authentication Methods¤

The Info class supports flexible authentication for user-specific methods:

  1. Class-level account - Set during Api.create() and used automatically
  2. Method-level address - Pass address string directly to methods
  3. Method-level account - Pass different Account object for specific calls
# Method 1: Class-level account (recommended)
api = await Api.create(account=account)
orders = await api.info.user_open_orders()  # Uses class account

# Method 2: Direct address
orders = await api.info.user_open_orders(address="0x...")

# Method 3: Different account per call
other_account = Account(address="0x...", secret_key="0x...")
orders = await api.info.user_open_orders(account=other_account)

Methods Reference¤

Convenience Methods¤

  • get_universe(): Retrieve the complete universe of available assets for both perpetual and spot markets

General Market & User Data¤

Perpetual Markets¤

Spot Markets¤

Usage Examples¤

Basic Market Data¤

from hl import Api

async def get_market_data():
    api = await Api.create()

    # Get all current mid prices
    result = await api.info.all_mids()
    if result.is_ok():
        mids = result.unwrap()
        print(f"BTC mid price: ${mids.get('BTC', 'N/A')}")

    # Get order book for a specific coin
    result = await api.info.l2_book(asset="BTC")
    if result.is_ok():
        book = result.unwrap()
        if book['levels']:
            best_bid = book['levels'][0][0]['px']
            print(f"Best bid: ${best_bid}")

asyncio.run(get_market_data())

User Account Information¤

from hl import Api, Account
import os

async def get_user_info():
    # Initialize with account for automatic authentication
    account = Account(
        address=os.environ["HL_ADDRESS"],
        secret_key=os.environ["HL_SECRET_KEY"]
    )
    api = await Api.create(account=account)

    # Get user's open orders (uses class account automatically)
    result = await api.info.user_open_orders()
    if result.is_ok():
        orders = result.unwrap()
        print(f"Open orders: {len(orders)}")

    # Get user's current state and positions
    result = await api.info.user_state()
    if result.is_ok():
        state = result.unwrap()
        print(f"Withdrawable balance: ${state['withdrawable']}")

    # Get trading fills
    result = await api.info.user_fills()
    if result.is_ok():
        fills = result.unwrap()
        print(f"Recent fills: {len(fills)}")

asyncio.run(get_user_info())

Historical Data and Time-based Queries¤

from datetime import datetime, timedelta

async def get_historical_data():
    api = await Api.create(account=account)

    # Get recent fills within last 7 days
    end_time = datetime.now()
    start_time = end_time - timedelta(days=7)

    result = await api.info.user_fills_by_time(
        start=start_time,
        end=end_time,
        aggregate_by_time=True  # Combine partial fills
    )
    if result.is_ok():
        fills = result.unwrap()
        print(f"Fills in last 7 days: {len(fills)}")

    # Get funding history for BTC over last 30 days
    result = await api.info.funding_history(
        asset="BTC",
        start=datetime.now() - timedelta(days=30)
    )
    if result.is_ok():
        funding = result.unwrap()
        print(f"BTC funding events: {len(funding)}")

asyncio.run(get_historical_data())

Error Handling¤

All Info methods return Result[T, ApiError] types for explicit error handling:

async def safe_info_call():
    api = await Api.create()

    result = await api.info.all_mids()
    if result.is_ok():
        mids = result.unwrap()
        # Handle successful response
        return mids
    else:
        error = result.unwrap_err()
        print(f"API Error: {error.message}")
        # Handle error case
        return None

Advanced Features¤

Asset Name/ID Conversion¤

The Info class automatically handles asset name/ID conversion through the Universe:

# These are equivalent - SDK handles conversion automatically
book_by_name = await api.info.l2_book(asset="BTC")
book_by_id = await api.info.l2_book(asset=0)  # BTC has ID 0

Best Practices¤

  1. Reuse Api instances - Avoid creating multiple instances unnecessarily
  2. Handle Results properly - Always check is_ok() before calling unwrap()
  3. Use appropriate authentication - Class-level accounts for repeated calls, method-level for one-offs
  4. Cache Universe data - The universe is automatically fetched and cached during Api.create()