Hyperliquid Market Data and Trade Review with Hermes Agent

The Hyperliquid skill for Hermes Agent turns the agent into a read-only client for Hyperliquid's public /info endpoint. You can pull market data, inspect account positions and history, and generate a heuristic post-trade review, all without an API key or signing anything. It is a natural fit for anyone who wants to answer questions like "what's the funding rate on BTC?" or "how did my fills look over the last three days?" without leaving the agent runtime.

What it does

This skill gives you 12 commands that cover the full read side of Hyperliquid: dexs, markets, spots, candles, funding, l2, state, spot-balances, fills, orders, review, and export. Everything runs on the Python standard library (urllib, json, argparse), so there are no external packages to install and no credentials to manage. The script is read-only by design: it never places orders, never signs transactions, and never touches your private keys.

You can use it to discover which perp DEXs and spot markets exist, pull historical candles and funding rates, inspect a live order book, review a wallet's positions and balances, list recent fills and open orders, generate a structured trade review, and export a normalized dataset for backtesting prep. The --json flag on any command gives you machine-readable output, which makes it easy to pipe into other tools or feed back into the agent's reasoning.

Before you start

The skill is optional and installed on demand. It lives at optional-skills/blockchain/hyperliquid and is version 0.1.0, authored by Hugo Sequier (Hugo-SEQUIER) for Hermes Agent, under the MIT license. It runs on Linux, macOS, and Windows.

There are no external dependencies and no API key. The script reads ${HERMES_HOME:-~/.hermes}/.env for two optional defaults:

• HYPERLIQUID_API_URL defaults to https://api.hyperliquid.xyz. Set it to https://api.hyperliquid-testnet.xyz to point at the testnet.
• HYPERLIQUID_USER_ADDRESS is the default address for state, spot-balances, fills, orders, and review. If it is not set, you pass the address as the first positional argument to those commands.

A project .env in the current working directory is also honored as a development fallback. The helper script itself is at ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py.

How to run

Invoke the script through the terminal tool. The general form is:

python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py <command> [args]

Add --json to any command for machine-readable output.

Here is the full 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_HOME:-~/.hermes}/.env.

Working with the commands

1. Discover DEXs and markets

Start by seeing what is available. The dexs command lists builder-deployed perp DEXs. markets shows perp markets, and spots shows spot pairs. You can sort and limit the output to keep it manageable.

python ~/.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

A few things to keep in mind. The --dex flag only applies to perp endpoints; if you omit it, you get the first perp DEX. Spot pairs may show as PURR/USDC or as aliases like @107. HIP-3 markets prefix the coin with the DEX, for example mydex:BTC.

2. Pull historical market data

For candles and funding rates, use candles and funding. These are useful for understanding recent price action or funding trends before making a decision.

python ~/.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 (see below).

3. Inspect the live order book

When you need to know the current depth or near-term liquidity, l2 gives you a point-in-time snapshot of the order book.

python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
  l2 BTC --levels 10

Use this when asked about book depth, near-term liquidity, or the potential market impact of a large order.

4. Review an account

To see what a wallet holds, use state for perp positions and spot-balances for spot inventory. These answer questions like "how are my positions?", "what am I holding?", and "how much is withdrawable?".

python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
  state 0xabc...

python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
  spot-balances

5. Review fills and orders

For recent activity, fills lists executed trades and orders shows open or recent orders. Both accept an address and a limit.

python ~/.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

The review command combines recent fills with market context to produce a structured report. It includes realized PnL, fees, win/loss counts, coin breakdowns, market trend and average funding for each traded perp, plus heuristics like fee drag, concentration, and counter-trend losses.

python ~/.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

For deeper post-trade analysis, the source suggests a workflow: start with review to find problem coins or windows, then pull fills and orders for that period, then pull candles and funding for each traded coin, and finally judge decision quality separately from outcome quality.

7. Export a reusable dataset

When you want a normalized dataset for backtesting or analysis, export writes candles and funding to a JSON file. The output includes a schema version, source metadata, the exact time window, normalized candle rows, normalized funding rows, and summary stats.

python ~/.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

Use --end-time-ms to create reproducible windows.

When not to use it

This skill is read-only. If you need to place orders, cancel orders, or manage positions, you need a different tool that can sign transactions. It is also not a backtesting engine; the export command gives you data, not a simulation.

Limits and gotchas

The source lists several caveats worth knowing before you rely on this skill for serious analysis.

• 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

To confirm the skill is working, run a quick market query:

python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
  markets --limit 5

This should print the top Hyperliquid perp markets by 24h notional volume.

What pairs with this

This skill is part of the Hermes Agent optional blockchain skillset. It pairs naturally with other skills that handle data analysis or visualization, since the --json output can feed directly into those tools. For a complete workflow, combine it with skills that handle file I/O or data processing to turn the exported datasets into charts or further analysis.