hyperliquid-reader

Hyperliquid Reader (Read-Only)

Reads Hyperliquid — the on-chain perps/spot DEX — for market data via opencli and the hyperliquid plugin in this repo's opencli-plugins/hyperliquid tree (a separate plugin from opencli's built-in adapters, installed via opencli's monorepo subpath syntax).

This skill is read-only and market-data only. It reads Hyperliquid's fully public info API for analysis: market tables, funding, order book, and candles. It does NOT read individual accounts, place/modify/cancel orders, or move funds. There is no trading path in the plugin — order placement requires wallet-signed actions on a separate endpoint this adapter never calls.

How it works: every command issues a single POST https://api.hyperliquid.xyz/info with a { "type": "..." } body and normalizes the response. No API key, no wallet, no login, no running app — the info API is public.

---

Step 1: Ensure opencli + Plugin Are Installed and Ready

Current environment status:

!`(command -v opencli && opencli hyperliquid markets --coin BTC -f json 2>&1 | head -3 && echo "READY" || echo "SETUP_NEEDED") 2>/dev/null || echo "NOT_INSTALLED"`

If the status above shows READY, skip to Step 2. Otherwise:

NOT_INSTALLED — Install opencli

npm install -g @jackwener/opencli

Requires Node.js >= 22 (built-in fetch).

SETUP_NEEDED — Install the Hyperliquid plugin

The Hyperliquid adapter is not built into opencli — it's a separate plugin:

opencli plugin install github:himself65/finance-skills/hyperliquid

That's the entire setup — no auth, no launch step. Verify with opencli hyperliquid markets --coin BTC.

Common setup issues

Symptom	Fix
opencli: command not found	npm install -g @jackwener/opencli (Node ≥ 22)
Unknown command: hyperliquid	opencli plugin install github:himself65/finance-skills/hyperliquid
hyperliquid info 429	Rate limited — wait a few seconds and retry

---

Step 2: Identify What the User Needs

User Request	Command	Key Flags
Perp markets overview / top by volume	opencli hyperliquid markets	--sort, --limit, --coin
One perp's price + funding + OI	opencli hyperliquid markets --coin BTC	—
Spot pairs overview	opencli hyperliquid spot-markets	--sort, --limit, --pair, --canonical-only
All current mid prices	opencli hyperliquid mids	--coin <substring>
Order book for a coin	opencli hyperliquid book --coin ETH	--depth, --n-sig-figs
OHLCV candles	opencli hyperliquid candles --coin BTC --interval 1h	--limit
Historical funding for a coin	opencli hyperliquid funding-history --coin BTC	--hours, --limit
Funding arb: HL vs Binance vs Bybit	opencli hyperliquid funding-compare	--coin, --sort, --limit

---

Step 3: Execute the Command

General pattern

# Use -f json or -f yaml for structured output
opencli hyperliquid markets --sort fundingAprPct --limit 15 -f json
opencli hyperliquid funding-compare --sort hlVsBinancePct --limit 20 -f md
opencli hyperliquid candles --coin BTC --interval 4h --limit 50 -f csv
opencli hyperliquid book --coin ETH --depth 5 -f json

Key rules

1. Coin symbols are bare perp names — BTC, ETH, SOL, HYPE (no exchange prefix). Spot pairs are BASE/USDC (e.g. PURR/USDC); for book/candles you can pass either a perp coin or a spot pair.
2. markets is the default lens for "how is X / the market doing" — it carries mark/oracle/mid price, 24h change, hourly funding + APR, open interest (coins and notional), and 24h volume in one row per perp. Filter with --coin for a single asset.
3. Funding is reported two ways — fundingHrPct is the raw hourly rate as a percent; fundingAprPct annualizes it (hourly × 24 × 365). Lead with APR when comparing carry across assets; use the hourly figure for "what will I pay next hour".
4. funding-compare is the funding-arb screen — it annualizes each venue with its own interval (HL hourly, Binance/Bybit usually 4h) and reports hlVsBinancePct / hlVsBybitPct spreads. Default sort ranks by absolute HL-vs-Binance spread (widest dislocations first). A positive hlVsBinancePct means HL longs pay more than Binance longs.
5. book defaults to 10 levels per side — raise --depth (max 20) for more, or --n-sig-figs 2..5 to aggregate price levels. Compute the spread/mid from the top bid and ask.
6. candles pulls the most recent --limit candles of --interval (default 1h, 100 candles). Valid intervals: 1m 3m 5m 15m 30m 1h 2h 4h 8h 12h 1d 3d 1w 1M. Max 5000.
7. -f json for programmatic processing / feeding other skills; -f md or -f table for human-readable output.
8. NEVER call any write operation. This skill is read-only market data — no account reads, no order placement, modification, or cancellation, and no transfers. The plugin intentionally exposes no write endpoints.

Output format flag (-f)

Format	Flag	Best for
Table	-f table (default)	Human-readable terminal output
JSON	-f json	Programmatic processing, LLM context
YAML	-f yaml	Structured, readable
Markdown	-f md	Reports
CSV	-f csv	Spreadsheet export

Output columns

• markets — coin, markPx, midPx, oraclePx, change24hPct, fundingHrPct, fundingAprPct, openInterest, oiNotional, dayNtlVlm, premiumPct, maxLeverage
• spot-markets — pair, base, markPx, midPx, change24hPct, dayNtlVlm, circulatingSupply, marketCap, canonical
• mids — coin, mid
• book — side, level, px, sz, orders
• candles — time, open, high, low, close, volume, trades
• funding-history — coin, fundingRatePct, fundingAprPct, premiumPct, time
• funding-compare — coin, hlAprPct, binanceAprPct, bybitAprPct, hlVsBinancePct, hlVsBybitPct, nextHlFunding

---

Step 4: Present the Results

1. Lead with the headline number, then the table. For markets --coin BTC: state mark price, 24h change, funding APR, and open interest in prose first. For a full markets dump: lead with the count and the top movers / highest-funding names.
2. Frame funding in carry terms — e.g. "BTC perp funding is +10.9% APR (longs pay shorts)". Positive funding ⇒ longs pay shorts; negative ⇒ shorts pay longs.
3. For funding-compare, surface the widest dislocations first — name the coin, both venues' APRs, and the spread, and remember the spread is annualized; a real arb also pays exchange/withdrawal frictions, so present it as a screen, not a guaranteed edge.
4. For book, report the spread — best bid, best ask, mid, and spread in bps before (or instead of) dumping every level. Don't paste 20 levels unless asked.
5. For candles, describe the move — first/last close, high/low, and direction; only show the full OHLCV table when the user wants the series.
6. Filter aggressively before showing — markets has ~180 perps and mids ~700 markets; cap to top 15-20 by the relevant sort unless the user asks for the full list.
7. Cross-reference for trade decisions — Hyperliquid is the on-chain venue; for equities/options context pair it with the funda-data or tradingview-reader skills. For funding/basis trades, funding-compare plus markets (premium, OI) is the core view.

---

Step 5: Diagnostics

opencli hyperliquid markets --coin BTC

A successful BTC row confirms opencli, the plugin, and the public API are all reachable. If it errors with Unknown command: hyperliquid, reinstall the plugin (Step 1). A hyperliquid info 4xx/5xx is an upstream API issue — retry after a short wait.

---

Error Reference

Error	Cause	Fix
Unknown command: hyperliquid	Plugin not installed	opencli plugin install github:himself65/finance-skills/hyperliquid
hyperliquid info 429	Rate limited	Wait a few seconds, then retry
hyperliquid info 422/500	Malformed body or upstream issue	Re-check the coin/interval; retry after a wait
No perp market for coin "X"	Wrong/unlisted symbol	Run opencli hyperliquid markets (or mids) to find the exact symbol

---

Reference Files

• references/commands.md — Every command with all flags, output schemas, and analyst workflows (funding carry, basis/arb, spot snapshot)