--- name: hyperliquid-34a8fbb3da27 description: Hyperliquid market data, account history, trade review. version: 0.1.0 author: Hugo Sequier (Hugo-SEQUIER), Hermes Agent license: MIT platforms: [linux, macos, windows] metadata: hermes: tags: [Hyperliquid, Blockchain, Crypto, Trading, Perpetuals, Spot, DeFi] related_skills: [] --- # 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 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: ```bash python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py [args] ``` Add `--json` to any command for machine-readable output. --- ## Quick Reference ```bash 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 [--interval 1h] [--hours 24] [--limit N] hyperliquid_client.py funding [--hours 72] [--limit N] hyperliquid_client.py l2 [--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 [--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 ```bash 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 ``` - `--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 ```bash 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` (below). ### 3. Inspect Live Order Book ```bash python ~/.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 ```bash python ~/.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 ```bash 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 ```bash 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 ``` 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 ```bash 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 ``` 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 ```bash python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ markets --limit 5 ``` Should print the top Hyperliquid perp markets by 24h notional volume. --- Source attribution: NousResearch Original project: https://github.com/NousResearch/hermes-agent License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Gabriel Moreira Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: NousResearch Original project: https://github.com/NousResearch/hermes-agent Attribution basis: Upstream repository explicitly recorded in package mirror path Fields of work: Data & Analytics, Development & Engineering, Finance & Accounting, Marketing, Sales Roles: Business Development, Data Analyst, Financial Analyst, Growth Marketer, ML / AI Engineer Specialties: API, Backend, DevOps, Frontend, Notion, Testing Tools: Hyperliquid Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 0539d6ae5e296e4d1ab9b263a69f386f6d3f33188b71acfc932e8b6ee85b30c5