hyperliquid-reader

# Hyperliquid Reader (Read-Only) Reads [Hyperliquid](https://app.hyperliquid.xyz) — the on-chain perps/spot DEX — for market data via [opencli](https://github.com/jackwener/opencli) and the `hyperliquid` plugin in this repo's [`opencli-plugins/hyperliquid`](https://github.com/himself65/finance-skills/tree/main/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 ```bash npm install -g @jackwener/opencli ``` Requires Node.js >= 24 — the `hyperliquid` plugin declares `engines.node >= 24`. ### SETUP_NEEDED — Install the Hyperliquid plugin The Hyperliquid adapter is **not** built into opencli — it's a separate plugin: ```bash 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 ≥ 24) | | `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 ```bash # 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. **Read-only market data.** No account reads, no order placement, modification, or cancellation, and no transfers — the plugin intentionally exposes no write endpoints, so don't look for workarounds. ### 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 `tradingview-reader` skill. For funding/basis trades, `funding-compare` plus `markets` (premium, OI) is the core view. --- ## Step 5: Diagnostics ```bash 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)