Skip to main content
Glama
akagifreeez

hl-read

by akagifreeez
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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

Related MCP server: 0xarchive-mcp

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.

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/akagifreeez/hl-read'

If you have feedback or need assistance with the MCP directory API, please join our Discord server