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 markets                    # every perp + max leverage
hl-read positions 0xYourAddr...    # anyone's positions (public data)
hl-read orders 0xYourAddr...       # resting orders
hl-read fills 0xYourAddr... --limit 20
hl-read watch ETH                  # live order book over websocket

Global flags: --testnet (use the testnet API), --json (raw JSON, great for piping to jq).

hl-read --json funding | jq '.[] | select(.funding > 0.0001)'

Library

from hl_read import HLRead

hl = HLRead()                     # mainnet; HLRead(testnet=True) for testnet
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.funding()                      # funding / mark / oracle / OI per market
hl.fills("0xabc...", limit=20)    # recent fills

# live stream (opens its own websocket)
hl.stream_book("ETH", lambda msg: print(msg["data"]["levels"][0][0]))

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: list_markets, get_mids, get_book, get_funding, get_funding_history, get_positions, get_open_orders, get_fills, get_candles. 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.

License

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