example.py

#!/usr/bin/env python3
"""
Usage examples for hyperliquid-python-client.

Run with:
    pip install httpx requests
    python example.py
"""

from hl_client import HyperliquidClient
from price_fetcher import get_price, get_prices, get_all_crypto_mids, get_all_stock_mids
from market_data import MarketData


def example_crypto_prices():
    """Fetch real-time crypto prices."""
    print("=" * 60)
    print("1. Real-time crypto prices")
    print("=" * 60)

    prices = get_prices(["BTC", "ETH", "SOL", "DOGE"])
    for symbol, price in prices.items():
        print(f"  {symbol}: ${price:,.2f}")

    # Single price
    btc = get_price("BTC")
    print(f"\n  BTC (single fetch): ${btc:,.2f}" if btc else "\n  BTC: unavailable")
    print()


def example_stock_perp_prices():
    """Fetch HIP-3 stock perpetual prices."""
    print("=" * 60)
    print("2. HIP-3 stock perp prices")
    print("=" * 60)

    prices = get_prices(["TSLA", "NVDA", "AAPL", "MSFT"])
    for symbol, price in prices.items():
        print(f"  {symbol}: ${price:,.2f}")
    print()


def example_all_mids():
    """Fetch all mid-prices at once."""
    print("=" * 60)
    print("3. All mid-prices (crypto + stocks)")
    print("=" * 60)

    crypto = get_all_crypto_mids()
    stocks = get_all_stock_mids()
    print(f"  Crypto perps available: {len(crypto)}")
    print(f"  Stock perps available:  {len(stocks)}")

    # Show top 5 crypto by... just the first 5 alphabetically
    for sym in sorted(crypto)[:5]:
        print(f"    {sym}: ${crypto[sym]:,.2f}")
    print()


def example_market_data():
    """Detailed market data via HyperliquidClient."""
    print("=" * 60)
    print("4. Detailed market data (funding, OI, volume)")
    print("=" * 60)

    with HyperliquidClient() as client:
        data = client.get_market_data(["BTC", "ETH", "SOL"])
        for sym, info in data.items():
            print(f"\n  {sym}:")
            print(f"    Price:        ${info['price']:,.2f}")
            print(f"    Funding APR:  {info['funding_apr']:+.1f}%")
            print(f"    Open Interest: ${info['open_interest']:,.0f}")
            print(f"    Volume 24h:   ${info['volume_24h']:,.0f}")
            print(f"    Change 24h:   {info['price_change_24h']:+.2f}%")
    print()


def example_candles():
    """Fetch historical candles."""
    print("=" * 60)
    print("5. Historical candles (BTC 4h, last 24 hours)")
    print("=" * 60)

    with HyperliquidClient() as client:
        candles = client.get_candles("BTC", interval="4h", lookback_hours=24)
        for c in candles:
            print(
                f"  {c['time']}  O:{c['open']:>10,.2f}  "
                f"H:{c['high']:>10,.2f}  L:{c['low']:>10,.2f}  "
                f"C:{c['close']:>10,.2f}"
            )
    print()


def example_funding_history():
    """Fetch funding rate history."""
    print("=" * 60)
    print("6. Funding rate history (ETH, last 48 hours)")
    print("=" * 60)

    with HyperliquidClient() as client:
        history = client.get_funding_history("ETH", hours=48)
        for entry in history[-10:]:  # last 10 entries
            print(f"  {entry['time']}  rate: {entry['rate']:.6f}  ({entry['apr']:+.1f}% APR)")
    print()


def example_orderbook():
    """Fetch order book and detect whale walls."""
    print("=" * 60)
    print("7. Order book + whale walls (BTC)")
    print("=" * 60)

    with HyperliquidClient() as client:
        book = client.get_orderbook("BTC", depth=10)
        print(f"  Spread: {book['spread_bps']:.2f} bps")
        print(f"  Top 3 bids:")
        for b in book["bids"][:3]:
            print(f"    ${b['price']:,.2f}  size: {b['size']:.4f}  (${b['usd']:,.0f})")
        print(f"  Top 3 asks:")
        for a in book["asks"][:3]:
            print(f"    ${a['price']:,.2f}  size: {a['size']:.4f}  (${a['usd']:,.0f})")

        # Whale walls
        walls = client.get_whale_walls("BTC", min_size_usd=100_000)
        if walls:
            print(f"\n  Whale walls (>$100k):")
            for w in walls[:5]:
                print(f"    {w['side']:<4}  ${w['price']:,.2f}  ${w['size_usd']:,.0f}")
        else:
            print("\n  No whale walls >$100k found")
    print()


def example_stock_perps():
    """Explore the HIP-3 stock perp universe."""
    print("=" * 60)
    print("8. HIP-3 stock perp universe")
    print("=" * 60)

    with HyperliquidClient() as client:
        stocks = client.get_stock_universe()
        print(f"  {len(stocks)} stock perps available\n")
        print(f"  {'Ticker':<10} {'Price':>10} {'Volume':>12} {'Funding':>10}")
        print(f"  {'-' * 46}")
        for s in stocks[:10]:
            print(
                f"  {s['coin']:<10} ${s['price']:>8,.2f} "
                f"${s['volume_24h'] / 1e6:>8.1f}M "
                f"{s['funding_apr']:>+8.1f}%"
            )
    print()


def example_multi_exchange_data():
    """Multi-exchange OI, funding, and long/short ratios."""
    print("=" * 60)
    print("9. Multi-exchange market snapshot (BTC)")
    print("=" * 60)

    md = MarketData()
    snapshot = md.get_full_snapshot("BTC")
    print(md.format_snapshot(snapshot))
    print()


if __name__ == "__main__":
    print("\nhyperliquid-python-client -- Usage Examples\n")

    example_crypto_prices()
    example_stock_perp_prices()
    example_all_mids()
    example_market_data()
    example_candles()
    example_funding_history()
    example_orderbook()
    example_stock_perps()
    example_multi_exchange_data()

    print("Done.")