Skip to content

glitchymagic/hyperliquid-python-client

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

hyperliquid-python-client

Lightweight Python client for the Hyperliquid REST API -- crypto perps, stock perps (HIP-3), candles, funding rates, open interest, and real-time prices. Zero dependencies beyond requests and httpx.

Features

  • Crypto perpetuals -- prices, funding rates, candles (OHLCV), order books, whale-wall detection
  • HIP-3 stock perpetuals -- TSLA, NVDA, AAPL, and 50+ stock perps via Trade.xyz on Hyperliquid
  • Multi-exchange aggregation -- OI, funding, and long/short ratios from Binance, Bybit, OKX
  • Automatic failover -- price fetching cascades through Hyperliquid -> Binance -> Bybit -> CoinGecko
  • 429 back-off -- built-in retry logic with exponential back-off for rate limits
  • CLI included -- every feature is accessible from the command line

Installation

git clone https://github.com/glitchymagic/hyperliquid-python-client.git
cd hyperliquid-python-client
pip install httpx requests

Quick Start

from hl_client import HyperliquidClient
from price_fetcher import get_prices

# Simple price fetch (auto-routes crypto vs stock perps)
prices = get_prices(["BTC", "ETH", "TSLA", "NVDA"])
print(prices)
# {'BTC': 95123.5, 'ETH': 3412.1, 'TSLA': 248.3, 'NVDA': 131.7}

# Full market data with the client
with HyperliquidClient() as client:
    data = client.get_market_data(["BTC", "ETH", "SOL"])
    for sym, info in data.items():
        print(f"{sym}: ${info['price']:,.2f}  funding: {info['funding_apr']:+.1f}%")

Modules

hl_client.py -- Hyperliquid API Client

Direct wrapper around the Hyperliquid REST API. Covers both crypto perps and HIP-3 stock perps.

from hl_client import HyperliquidClient

with HyperliquidClient() as client:
    # Crypto perps
    client.get_market_data(["BTC", "ETH"])       # price, funding, OI, volume
    client.get_universe()                          # all available perps
    client.get_candles("BTC", "4h", 72)           # OHLCV candles
    client.get_funding_history("ETH", hours=48)   # funding rate history
    client.get_orderbook("BTC", depth=20)         # L2 order book
    client.get_whale_walls("BTC", min_size_usd=500_000)  # large resting orders

    # HIP-3 stock perps
    client.get_stock_market_data(["TSLA", "NVDA"])  # stock perp market data
    client.get_stock_universe()                      # all stock perps
    client.get_stock_orderbook("TSLA")               # stock perp order book
    client.get_stock_funding_history("TSLA", 48)     # stock perp funding

price_fetcher.py -- Unified Price Fetching

Routes each symbol to the correct data source automatically. Crypto goes to Hyperliquid (CoinGecko fallback), stocks go to the HIP-3 endpoint.

from price_fetcher import get_prices, get_price, get_all_crypto_mids, get_all_stock_mids

# Mixed fetch (auto-routes by asset type)
prices = get_prices(["BTC", "ETH", "TSLA", "GOLD"])

# Single price
btc = get_price("BTC")

# Bulk fetches
all_crypto = get_all_crypto_mids()   # every crypto perp
all_stocks = get_all_stock_mids()    # every HIP-3 stock perp

market_data.py -- Multi-Exchange Market Data

Aggregates open interest, funding rates, and positioning data from Binance, Bybit, and OKX alongside Hyperliquid.

from market_data import MarketData

md = MarketData()

price, source = md.get_price_with_failover("BTC")  # auto-failover pricing
oi = md.get_btc_open_interest()                      # aggregate OI
funding = md.get_funding_rates()                     # cross-exchange funding
ratios = md.get_long_short_ratio()                   # Binance L/S ratios
snapshot = md.get_full_snapshot("BTC")               # everything at once

print(md.format_snapshot(snapshot))

CLI Usage

Every module doubles as a CLI tool:

# hl_client.py
python hl_client.py market BTC ETH SOL          # market data
python hl_client.py candles BTC --interval 4h    # OHLCV candles
python hl_client.py funding ETH --hours 48       # funding history
python hl_client.py book BTC --depth 20          # order book
python hl_client.py whales BTC --min-size 500000 # whale walls
python hl_client.py universe                     # all crypto perps
python hl_client.py stock-perps                  # all HIP-3 stock perps
python hl_client.py stock-book TSLA NVDA         # stock perp order books
python hl_client.py stock-funding TSLA           # stock perp funding

# market_data.py
python market_data.py                            # BTC market snapshot
python market_data.py --symbol ETH --json        # raw JSON output

# example.py
python example.py                                # run all examples

API Reference

HyperliquidClient

Method Description Returns
get_market_data(symbols) Price, funding, OI, volume, 24h change dict[str, dict]
get_universe() All crypto perps sorted by volume list[dict]
get_candles(symbol, interval, hours) Historical OHLCV list[dict]
get_funding_history(symbol, hours) Funding rate history list[dict]
get_orderbook(symbol, depth) L2 order book with spread dict
get_whale_walls(symbol, min_usd, depth) Large resting orders list[dict]
all_mids() All crypto mid-prices dict[str, str]
get_stock_market_data(symbols) HIP-3 stock perp data dict[str, dict]
get_stock_universe() All HIP-3 stock perps list[dict]
get_stock_orderbook(symbol, depth) Stock perp order book dict
get_stock_funding_history(symbol, hours) Stock perp funding list[dict]
stock_perp_mids() All stock perp mid-prices dict[str, str]

price_fetcher

Function Description Returns
get_prices(symbols) Auto-routed multi-asset prices dict[str, float]
get_price(symbol) Single price fetch float | None
get_all_crypto_mids() Every crypto perp price dict[str, float]
get_all_stock_mids() Every stock perp price dict[str, float]

MarketData

Method Description Returns
get_price_with_failover(symbol) Price with auto-failover tuple[float, str]
get_btc_open_interest() Aggregate OI from 3 exchanges dict
get_funding_rates() Cross-exchange funding rates dict
get_long_short_ratio() Binance L/S ratios dict
get_full_snapshot(symbol) Complete market snapshot dict
format_snapshot(snapshot) Human-readable snapshot str

Hyperliquid API Notes

  • Crypto perps use the standard https://api.hyperliquid.xyz/info endpoint
  • Stock perps (HIP-3) require "dex": "xyz" in the request payload and use xyz:TICKER naming (e.g. xyz:TSLA)
  • Rate limits: The API returns HTTP 429 when rate-limited. This client handles it automatically with exponential back-off
  • Candle intervals: 1m, 5m, 15m, 1h, 4h, 1d
  • No authentication required for read-only market data

License

MIT

About

Lightweight Python client for Hyperliquid REST API — crypto perps, stock perps (HIP-3), candles, funding, OI, real-time prices

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages