mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
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.
211 lines
6.8 KiB
Markdown
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.
|