Hyperliquid Skill
Query Hyperliquid market and account data through the public /info endpoint.
Read-only — no API key, no signing, no order placement.
12 commands: dexs, markets, spots, candles, funding, l2, state,
spot-balances, fills, orders, review, export. Stdlib only
(urllib, json, argparse).
When to Use
- User asks for Hyperliquid perp or spot market data, candles, funding, or L2 book
- User wants to inspect a wallet's perp positions, spot balances, fills, or orders
- User wants a post-trade review combining recent fills with market context
- User wants to inspect builder-deployed perp dexs or HIP-3 markets
- User wants a normalized JSON export of candles + funding for backtesting prep
Prerequisites
Stdlib only — no external packages, no API key.
The script reads ${HERMES_HOME:-~/.hermes}/.env for two optional defaults:
HYPERLIQUID_API_URL— defaults tohttps://api.hyperliquid.xyz. Set tohttps://api.hyperliquid-testnet.xyzfor testnet.HYPERLIQUID_USER_ADDRESS— default address forstate,spot-balances,fills,orders, andreview. If unset, pass the address as the first positional argument.
A project .env in the current working directory is honored as a dev fallback.
Helper script: ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py
How to Run
Invoke through the terminal tool:
bashpython ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py <command> [args]
Add --json to any command for machine-readable output.
Quick Reference
bashhyperliquid_client.py dexs hyperliquid_client.py markets [--dex DEX] [--limit N] [--sort volume|oi|funding_abs|change_abs|name] hyperliquid_client.py spots [--limit N] hyperliquid_client.py candles <coin> [--interval 1h] [--hours 24] [--limit N] hyperliquid_client.py funding <coin> [--hours 72] [--limit N] hyperliquid_client.py l2 <coin> [--levels N] hyperliquid_client.py state [address] [--dex DEX] hyperliquid_client.py spot-balances [address] [--limit N] hyperliquid_client.py fills [address] [--hours N] [--limit N] [--aggregate-by-time] hyperliquid_client.py orders [address] [--limit N] hyperliquid_client.py review [address] [--coin COIN] [--hours N] [--fills N] hyperliquid_client.py export <coin> [--interval 1h] [--hours N] [--output PATH]
For state, spot-balances, fills, orders, and review, the address is
optional when HYPERLIQUID_USER_ADDRESS is set in ${HERMES_HOME:-~/.hermes}/.env.
Procedure
1. Discover DEXs and Markets
bashpython ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py dexs python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ markets --limit 15 --sort volume python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ spots --limit 15
--dexonly applies to perp endpoints; omit for the first perp dex.- Spot pairs may show as
PURR/USDCor aliases like@107. - HIP-3 markets prefix the coin with the dex, e.g.
mydex:BTC.
2. Pull Historical Market Data
bashpython ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ candles BTC --interval 1h --hours 72 --limit 48 python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ funding BTC --hours 168 --limit 30
Time-range endpoints paginate. For larger windows, repeat with a later
startTime or use export (below).
3. Inspect Live Order Book
bashpython ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ l2 BTC --levels 10
Use when asked about book depth, near-term liquidity, or potential market impact of a large order.
4. Review an Account
bashpython ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ state 0xabc... python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ spot-balances
state returns perp positions; spot-balances returns spot inventory.
Use these for "how are my positions?", "what am I holding?", "how much is
withdrawable?".
5. Review Fills and Orders
bashpython ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ fills 0xabc... --hours 72 --limit 25 python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ orders --limit 25
6. Generate a Trade Review
bashpython ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ review 0xabc... --hours 72 --fills 50 python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ review --coin BTC --hours 168
Reports realized PnL, fees, win/loss counts, coin breakdowns, market trend and average funding for each traded perp, plus heuristics (fee drag, concentration, counter-trend losses).
For deeper post-trade analysis: start with review to find problem coins
or windows → pull fills and orders for that period → pull candles
and funding for each traded coin → judge decision quality separately
from outcome quality.
7. Export a Reusable Dataset
bashpython ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ export BTC --interval 1h --hours 168 --output ./btc-1h-7d.json python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ export BTC --interval 15m --hours 72 --end-time-ms 1760000000000
Output JSON contains: schema version, source metadata, exact time window,
normalized candle rows, normalized funding rows, summary stats. Use
--end-time-ms for reproducible windows.
Pitfalls
- Public info endpoints are rate-limited. Large historical queries may
return capped windows; iterate with later
startTimevalues. fills --hours ...usesuserFillsByTime, which only exposes a recent rolling window — not full archive history.historicalOrdersreturns recent orders only; not a full export.- The
reviewcommand is heuristic. It cannot reconstruct intent, order placement quality, or true slippage from fills alone. - The
exportcommand writes a normalized dataset, not a backtest engine. You still need your own slippage/fill model. - Spot aliases like
@107are valid identifiers even when the UI shows a friendlier name. l2is a point-in-time snapshot, not a time series.
Verification
bashpython ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ markets --limit 5
Should print the top Hyperliquid perp markets by 24h notional volume.
