Hl Read

A key-free, read-only toolkit for Hyperliquid. Use it as a Python library, a CLI, or an MCP server that lets an LLM agent (Claude, n8n, …) observe Hyperliquid markets and any wallet's public state.

Why "read-only" is the feature. hl-read imports only the read side of the Hyperliquid SDK (Info) — never Exchange. There is no code path that can sign a transaction, place an order, or move funds. You never hand it a private key, so there is no key to leak. Most Hyperliquid MCP servers ask for your key so the model can trade; this one is safe to point an autonomous agent at by construction.

Everything it reads is public on-chain / exchange data: prices, order books, funding, and any address's positions, orders and fills.

Install

pip install hl-read            # library + CLI
pip install "hl-read[mcp]"     # also installs the MCP server deps

CLI

hl-read mids                       # all mid prices
hl-read mids BTC ETH               # just these
hl-read book ETH --depth 5         # order book snapshot
hl-read funding --top 10           # markets with the most extreme funding
hl-read predicted BTC ETH          # predicted funding across venues (HL vs Binance/Bybit)
hl-read markets                    # every perp + max leverage
hl-read spot                       # every spot pair + mid price
hl-read spot PURR                  # filter by base coin / pair
hl-read positions 0xYourAddr...    # anyone's positions (public data)
hl-read positions 0xYourAddr... --watch    # live, re-polled every few seconds
hl-read portfolio 0xYourAddr...    # account value / PnL history by period
hl-read ledger 0xYourAddr...       # deposits / withdrawals / transfers (--since, --limit 0 = all)
hl-read balances 0xYourAddr...     # spot token balances
hl-read orders 0xYourAddr...       # resting orders
hl-read fills 0xYourAddr... --limit 20
hl-read fills 0xYourAddr... --since 7d     # fills within a time window (e.g. 24h/7d, 2024-01-31)
hl-read watch ETH                  # live order book over websocket
hl-read health                     # is the API up? round-trip latency (exit 1 if down)

Global flags: --testnet (use the testnet API), --json (raw JSON, great for piping to jq), --format table|json|csv|ndjson (output format; --json is the alias for --format json), --retries N (retry transient failures), --rate-limit N (cap HTTP calls/min), --no-cache (always fetch fresh), --api-url URL (override the endpoint, e.g. a proxy/mirror), --fallback-url URL (repeatable; tried on persistent failure).

hl-read --json funding | jq '.[] | select(.funding > 0.0001)'
hl-read --format csv funding > funding.csv          # any list command as CSV / NDJSON

Export to a file

export writes straight to a UTF-8 file (no BOM) so it survives the Windows/PowerShell > redirect, which otherwise emits UTF-16 and corrupts CSVs. Defaults to CSV; use --format json|ndjson to change.

hl-read export ledger 0xYourAddr... --out ledger.csv         # full deposit/withdrawal history
hl-read export fills  0xYourAddr... --since 30d --out fills.csv
hl-read --format ndjson export candles BTC --hours 168 --out btc.ndjson

Library

from hl_read import HLRead

hl = HLRead()                     # mainnet; HLRead(testnet=True) for testnet
# custom endpoint + optional fallbacks (Hyperliquid is single-host, so these
# only matter for your own proxy/mirror; failover applies at connect and reads):
# HLRead(api_url="https://my-proxy", fallback_urls=["https://api.hyperliquid.xyz"])
hl.mids()["BTC"]                  # current mid price
hl.book("ETH", depth=5)           # {"bids": [...], "asks": [...], "mid": ..., "spread": ...}
hl.positions("0xabc...")          # account value + open positions for any address
hl.portfolio("0xabc...")          # account-value / PnL history by period (day..allTime)
hl.funding()                      # funding / mark / oracle / OI per market
hl.predicted_fundings()           # predicted funding per coin across venues (HL + CEXes)
hl.fills("0xabc...", limit=20)    # recent fills
hl.fills_by_time("0xabc...", start_ms, end_ms)   # fills within an epoch-ms window
hl.ledger("0xabc...")             # deposits/withdrawals/transfers (non-funding ledger)
hl.health()                       # liveness probe: {ok, latency_ms, markets, error}
hl.spot_markets()                 # spot pairs: name, base/quote token, mid
hl.spot_balances("0xabc...")      # spot token balances for any address

# live streams (open their own websocket — keep the returned Info alive)
hl.stream_book("ETH", lambda msg: print(msg["data"]["levels"][0][0]))
hl.stream_user_events("0xabc...", print)   # live fills / funding / liquidations

# auto-reconnecting streams — survive a dropped connection (the SDK's don't):
# the supervisor rebuilds the socket and re-subscribes with backoff.
stream = hl.resilient_stream_book("BTC", on_msg, on_reconnect=lambda: print("reconnected"))
# ... stream.connected -> bool;  stream.close() to stop

The CLI watch uses this, so a long-running order-book view recovers on its own after a network blip.

Resilience (built in, configurable)

Every HTTP read goes through a default timeout, exponential backoff with jitter on transient failures (network errors, HTTP 429/5xx → HLReadError once exhausted), an optional client-side rate limit, and short-lived caching of the high-frequency market endpoints (so e.g. mid() in a loop costs one fetch per cache window, not one per call). Websocket streams can auto-reconnect (resilient_stream*), and you can point at a custom endpoint with optional fallbacks (applied at connect and on persistent read failure).

hl = HLRead(
    max_retries=4,            # retry transient failures
    rate_limit_per_min=600,   # cap HTTP calls/min (None = off)
    cache_ttl=1.0,            # seconds to cache mids / funding ctxs (0 = always fresh)
    meta_ttl=300.0,           # seconds to cache the market/token tables
    http_timeout=10.0,        # per-request timeout
    api_url=None,             # override endpoint (None = official mainnet/testnet)
    fallback_urls=None,       # e.g. ["https://api.hyperliquid.xyz"]; tried on failure
)
hl.clear_cache()              # drop cached data on demand

MCP server (the differentiator)

Expose read-only Hyperliquid data to any MCP client over stdio.

hl-read-mcp                       # mainnet
HL_READ_TESTNET=1 hl-read-mcp     # testnet

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "hl-read": { "command": "hl-read-mcp" }
  }
}

Claude Code:

claude mcp add hl-read -- hl-read-mcp

Tools exposed to the model (16): get_health, list_markets, get_mids, get_book, get_funding, get_funding_history, get_predicted_fundings, get_positions, get_portfolio, get_open_orders, get_ledger, get_fills, get_fills_by_time, get_candles, get_spot_markets, get_spot_balances. None of them can place an order.

Ask Claude: "What's the funding on the top 5 Hyperliquid perps right now, and what's 0xabc…'s open position on the highest one?" — it answers using only public reads.

Safety model

• No key, ever. The library has no parameter, env var, or file from which it reads a private key.
• No trading code in the import graph. hyperliquid.exchange.Exchange is never imported, so signing/order/cancel functions are not reachable.
• Read-only network calls. Only Hyperliquid's public info endpoint and public websocket subscriptions are used.

This makes hl-read a sound base for monitoring bots, dashboards, and autonomous agents where you want market awareness without ceding the ability to spend.

Development

pip install -e ".[dev]"
python -m unittest discover -s tests   # or: pytest

The test suite is fully offline — the SDK is mocked, so it exercises the retry/backoff, cache, and parsing logic deterministically without touching the network.

License

MIT © akagifreeez. Not affiliated with Hyperliquid. Public market data only; nothing here is financial advice.