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

---

Step 2: Identify What the User Needs

---

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)

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

---

Reference Files

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

hyperliquid-reader

Read-only Hyperliquid market-data reader via opencli + the `hyperliquid` opencli plugin shipped alongside this skill.

What it does

Reads Hyperliquid's public info API — no API key, no wallet, no login, no scraping. Capabilities:

• Perp markets — mark/oracle/mid price, 24h change, hourly funding + annualized APR, open interest (coins + notional), and 24h volume for every perpetual
• Spot markets — pair price, 24h change, volume, circulating supply, market cap
• Mids — current mid price for every perp + spot market in one call
• Order book — L2 snapshot, top N levels per side, with spread
• Candles — OHLCV history for any interval (1m … 1M)
• Funding history — historical hourly funding (rate, APR, premium) per coin
• Funding compare — cross-venue predicted funding (Hyperliquid vs Binance vs Bybit), annualized, with spreads — a funding-arbitrage screen

This skill is read-only and market-data only. It does NOT read individual accounts, place/modify/cancel orders, or move funds.

Authentication

None. Hyperliquid's info market-data endpoints are fully public — nothing to authenticate.

Triggers

• "Hyperliquid funding for X", "what's the funding on BTC perp", "HL open interest"
• "Hyperliquid order book for ETH", "HL perp markets", "Hyperliquid spot markets"
• "funding arb Hyperliquid vs Binance", "Hyperliquid candles for SOL"
• "PURR price on Hyperliquid", "Hyperliquid mid prices"
• Any mention of Hyperliquid / app.hyperliquid.xyz / HL DEX in context of reading market data or funding

Platform

Works on Claude Code and other CLI-based agents (any OS with Node ≥ 22). Does not work on Claude.ai — the sandbox restricts the network access opencli needs. Unlike the TradingView reader, there is no desktop-app or macOS dependency — it's a plain HTTP API.

Setup

# As a plugin (recommended — installs all skills in this group)
npx plugins add himself65/finance-skills --plugin finance-data-providers

# Or install just this skill
npx skills add himself65/finance-skills --skill hyperliquid-reader

See the main README for more installation options.

Prerequisites

• Node.js >= 22 — for npm install -g @jackwener/opencli and the plugin's built-in fetch
• The hyperliquid opencli plugin: opencli plugin install github:himself65/finance-skills/hyperliquid (installs from this repo's monorepo subpath)

No API key, no wallet, no launch step.

Reference files

• references/commands.md — Complete market-data command reference with all flags, output schemas, and analyst workflows

Hyperliquid Reader — Command Reference

Every command issues a single POST https://api.hyperliquid.xyz/info and prints normalized rows. All are read-only market data, need no auth, and accept -f json|yaml|md|csv|table.

Symbols: perps are bare names (BTC, ETH, HYPE); spot pairs are BASE/USDC (PURR/USDC). book and candles accept either.

---

Market data

markets — perpetual markets table

metaAndAssetCtxs → one row per perp.

Columns: coin, markPx, midPx, oraclePx, change24hPct, fundingHrPct, fundingAprPct, openInterest, oiNotional, dayNtlVlm, premiumPct, maxLeverage.

• fundingHrPct — raw hourly funding rate as a percent.
• fundingAprPct — hourly × 24 × 365 (annualized).
• openInterest — in coins; oiNotional — openInterest × markPx (USD).
• premiumPct — perp premium/discount vs oracle (mark-implied).

opencli hyperliquid markets --sort dayNtlVlm --limit 15
opencli hyperliquid markets --coin HYPE -f json
opencli hyperliquid markets --sort fundingAprPct --limit 20   # highest carry

spot-markets — spot pairs table

spotMetaAndAssetCtxs → one row per spot pair.

Columns: pair, base, markPx, midPx, change24hPct, dayNtlVlm, circulatingSupply, marketCap, canonical.

opencli hyperliquid spot-markets --canonical-only --sort dayNtlVlm --limit 20
opencli hyperliquid spot-markets --pair PURR -f json

mids — all mid prices

allMids (+ spotMeta to resolve names) → coin, mid for every market.

Non-canonical spot keys (@<index>) resolve to BASE/QUOTE; perp names and canonical pairs pass through; builder perp-dex keys (#<n>) are shown as-is.

opencli hyperliquid mids --coin BTC      # BTC, plus any pair containing "BTC"
opencli hyperliquid mids -f json | jq '.[] | select(.coin=="ETH")'

book — L2 order book snapshot

l2Book → up to --depth levels per side, bids first then asks.

Columns: side (bid/ask), level, px, sz, orders.

Spread = best ask − best bid; mid = their average. Top-of-book is level: 1 on each side.

opencli hyperliquid book --coin ETH --depth 5
opencli hyperliquid book --coin BTC --n-sig-figs 3 -f json

candles — OHLCV history

candleSnapshot → most recent --limit candles of --interval.

Columns: time (ISO, candle open), open, high, low, close, volume, trades.

opencli hyperliquid candles --coin BTC --interval 4h --limit 60
opencli hyperliquid candles --coin SOL --interval 1d --limit 30 -f csv

funding-history — historical funding for a coin

fundingHistory → hourly prints within the lookback window, newest first.

Columns: coin, fundingRatePct, fundingAprPct, premiumPct, time.

opencli hyperliquid funding-history --coin BTC --hours 72
opencli hyperliquid funding-history --coin ETH --hours 168 --limit 24 -f json

funding-compare — cross-venue funding (arb screen)

predictedFundings → per coin, each venue's predicted funding annualized to APR, plus HL-vs-venue spreads.

Columns: coin, hlAprPct, binanceAprPct, bybitAprPct, hlVsBinancePct, hlVsBybitPct, nextHlFunding.

Each venue is annualized with its own interval (HL hourly, Binance/Bybit usually 4h). hlVsBinancePct = hlAprPct − binanceAprPct; positive ⇒ HL longs pay more. Default sort surfaces the widest dislocations first. Treat as a screen — a real arb also pays exchange and transfer frictions.

opencli hyperliquid funding-compare --limit 20            # widest HL/Binance gaps
opencli hyperliquid funding-compare --coin BTC -f json
opencli hyperliquid funding-compare --sort hlAprPct --limit 15   # highest HL carry

---

Analyst workflows

Funding carry scan

1. markets --sort fundingAprPct --limit 20 — highest (and, reversed mentally, lowest) annualized funding. 2. funding-history --coin <X> --hours 168 — confirm the rate is persistent, not a one-hour spike. 3. markets --coin <X> — check open interest and premium to size whether the carry is tradeable.

Cross-venue funding arbitrage

1. funding-compare --limit 25 — widest HL-vs-Binance/Bybit dislocations. 2. For a candidate <X>: funding-compare --coin <X> for all three venues' APRs and the next HL funding time. 3. book --coin <X> and markets --coin <X> — verify depth and OI can support the size before treating the spread as real (it's annualized and ignores frictions).

Basis / premium check

1. markets --coin <X> — premiumPct shows perp rich/cheap vs oracle; markPx vs oraclePx is the absolute basis. 2. candles --coin <X> --interval 1h — recent price action around the basis.

Spot token snapshot

1. spot-markets --canonical-only --sort dayNtlVlm — most active named pairs. 2. spot-markets --pair <BASE> — price, 24h change, market cap for one token. 3. book --coin <BASE>/USDC — liquidity at top of book.