hermes-agent/optional-skills/blockchain/hyperliquid/SKILL.md
Teknium 4a2198bf51
fix: Windows MCP PATHEXT resolution + python3 -> python in cross-platform skills (#84429)
Two Windows agent-loop friction fixes:

1. tools/mcp_tool.py (#56536): shutil.which(cmd, path=env_path) reads
   executable extensions from the PARENT process PATHEXT, not the MCP
   subprocess env — a stdio MCP config supplying both PATH and PATHEXT
   could fail to resolve a command its own env can locate, and startup
   then got a bare command name. On Windows, when the first which() call
   misses and the config env carries PATHEXT (any key casing), retry the
   resolution with the config's PATHEXT temporarily applied.

2. skills/ + optional-skills/ (#50606): 42 SKILL.md files that declare
   platforms: [.., windows] used python3 in their command examples.
   python3 does not exist on native Windows (the toolchain probe in the
   system prompt reports python3=missing), so every copy-pasted example
   burned a failed agent turn before self-correction. Replaced the
   command word python3 -> python (python3-config / python3.x version
   strings untouched). python is the spelling that exists in every
   Hermes-managed environment (Windows native, uv-managed venvs on all
   three OSes); agents on POSIX hosts additionally see the probed
   toolchain line and adapt either way.
2026-08-12 02:43:28 -07:00

211 lines
6.8 KiB
Markdown

---
name: hyperliquid
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 <command> [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 <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
```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.