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/.env
for two optional defaults:
HYPERLIQUID_API_URL
— defaults to https://api.hyperliquid.xyz
. Set to
https://api.hyperliquid-testnet.xyz
for testnet.HYPERLIQUID_USER_ADDRESS
— default address for state
, spot-balances
,
fills
, orders
, and review
. 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:
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py <command> [args]
Add
--json
to any command for machine-readable output.
Quick Reference
hyperliquid_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/.env
.
Procedure
1. Discover DEXs and Markets
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py dexs
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
markets --limit 15 --sort volume
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
spots --limit 15
--dex
only applies to perp endpoints; omit for the first perp dex.- Spot pairs may show as
PURR/USDC
or aliases like @107
.
- HIP-3 markets prefix the coin with the dex, e.g.
mydex:BTC
.
2. Pull Historical Market Data
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
candles BTC --interval 1h --hours 72 --limit 48
python3 ~/.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
python3 ~/.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
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
state 0xabc...
python3 ~/.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
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
fills 0xabc... --hours 72 --limit 25
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
orders --limit 25
6. Generate a Trade Review
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
review 0xabc... --hours 72 --fills 50
python3 ~/.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
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
export BTC --interval 1h --hours 168 --output ./btc-1h-7d.json
python3 ~/.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
startTime
values.
fills --hours ...
uses userFillsByTime
, which only exposes a
recent rolling window — not full archive history.historicalOrders
returns recent orders only; not a full export.- The
review
command is heuristic. It cannot reconstruct intent,
order placement quality, or true slippage from fills alone.
- The
export
command writes a normalized dataset, not a backtest
engine. You still need your own slippage/fill model.
- Spot aliases like
@107
are valid identifiers even when the UI shows
a friendlier name.
l2
is a point-in-time snapshot, not a time series.
Verification
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
markets --limit 5
Should print the top Hyperliquid perp markets by 24h notional volume.
