mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-05-18 04:41:56 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

chore(skills/hyperliquid): tighten SKILL.md to modern format

Browse source 
- description shortened to <=60 chars
- platforms gated to [linux, macos, windows] (stdlib-only, all OK)
- author credits Hugo Sequier
- collapse redundant prerequisites/setup blocks
- terminal-tool-oriented procedure section
This commit is contained in:
teknium1 2026-05-10 22:04:37 -07:00 • committed by Teknium
parent f2e8ed2405
commit 1f899393dc
1 changed files with 87 additions and 170 deletions
Download patch file Download diff file Expand all files Collapse all files

257
optional-skills/blockchain/hyperliquid/SKILL.md
View file

@ -1,9 +1,10 @@
---
name: hyperliquid
description: Query Hyperliquid market and account data - perp dexs, perp/spot market contexts, candles, funding history, L2 books, perp state, spot balances, fills, historical orders, trade review, and normalized market-data export. Uses the public info endpoint only and needs no API key.
description: Hyperliquid market data, account history, trade review.
version: 0.1.0
author: Hermes Agent
author: Hugo Sequier (Hugo-SEQUIER), Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
hermes:
tags: [Hyperliquid, Blockchain, Crypto, Trading, Perpetuals, Spot, DeFi]
@ -12,134 +13,97 @@ metadata:
# Hyperliquid Skill
Query Hyperliquid market data and user account history through the public
`/info` endpoint.
Query Hyperliquid market and account data through the public `/info` endpoint.
Read-only — no API key, no signing, no order placement.
12 commands: dexs, perp markets, spot markets, candle history, funding history,
L2 books, perp state, spot balances, fills, historical orders, trade review,
and normalized market-data export.
No API key needed. Uses only Python standard library (`urllib`, `json`,
`argparse`).
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
- User wants historical candles for a Hyperliquid market
- User wants current funding, open interest, or 24h notional volume
- User wants to inspect an address's perp positions, spot balances, fills, or historical orders
- User wants a post-trade review using fills plus surrounding market context
- 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
The helper script uses only Python standard library.
No external packages or API keys are required.
It automatically reads `~/.hermes/.env` for `HYPERLIQUID_API_URL` and
`HYPERLIQUID_USER_ADDRESS`. A project `.env` in the current working directory
is treated as a dev fallback when present.
Stdlib only — no external packages, no API key.
Default API base:
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:
```bash
https://api.hyperliquid.xyz
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py <command> [args]
```
Optional testnet or custom override:
```bash
export HYPERLIQUID_API_URL="https://api.hyperliquid-testnet.xyz"
# or save it in ~/.hermes/.env
```
Optional default account address:
```bash
export HYPERLIQUID_USER_ADDRESS="0x0000000000000000000000000000000000000000"
# or save it in ~/.hermes/.env
```
Helper script path:
```bash
~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py
```
Add `--json` to any command for machine-readable output.
---
## Quick Reference
```bash
python3 hyperliquid_client.py dexs
python3 hyperliquid_client.py markets [--dex DEX] [--limit N] [--sort volume|oi|funding_abs|change_abs|name]
python3 hyperliquid_client.py spots [--limit N]
python3 hyperliquid_client.py candles <coin> [--interval 1h] [--hours 24] [--limit N]
python3 hyperliquid_client.py funding <coin> [--hours 72] [--limit N]
python3 hyperliquid_client.py l2 <coin> [--levels N]
python3 hyperliquid_client.py state [address] [--dex DEX]
python3 hyperliquid_client.py spot-balances [address] [--limit N]
python3 hyperliquid_client.py fills [address] [--hours N] [--limit N] [--aggregate-by-time]
python3 hyperliquid_client.py orders [address] [--limit N]
python3 hyperliquid_client.py review [address] [--coin COIN] [--hours N] [--fills N]
python3 hyperliquid_client.py export <coin> [--interval 1h] [--hours N] [--output PATH]
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]
```
Add `--json` to any command for structured output.
For `state`, `spot-balances`, `fills`, `orders`, and `review`, the address is optional if `HYPERLIQUID_USER_ADDRESS` is set.
For `state`, `spot-balances`, `fills`, `orders`, and `review`, the address is
optional when `HYPERLIQUID_USER_ADDRESS` is set in `~/.hermes/.env`.
---
## Procedure
### 0. Setup Check
```bash
python3 --version
# Optional: switch to testnet
export HYPERLIQUID_API_URL="https://api.hyperliquid-testnet.xyz"
# Optional: set a default address for account-level commands
export HYPERLIQUID_USER_ADDRESS="0x0000000000000000000000000000000000000000"
# Confirm connectivity by listing top perp markets
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
markets --limit 5
```
### 1. Discover DEXs and Markets
Use `dexs` to inspect the first perp dex plus any builder-deployed perp dexs.
Use `markets` to inspect mark price, change, funding, open interest, and 24h
notional volume. Use `spots` for spot pairs.
```bash
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 \
markets --dex mydex --limit 15
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
spots --limit 15
```
Tips:
- `--dex` is only for perp endpoints; omit it for the first perp dex.
- Spot pairs may appear as `PURR/USDC` or internal aliases like `@107`.
- For HIP-3 markets, coin strings may include a dex prefix such as `mydex:BTC`.
- `--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
Use `candles` for OHLCV snapshots and `funding` for historical funding data.
This is the best starting point for backtest prototypes and trade review.
```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
candles BTC --interval 1h --hours 72 --limit 48
@ -148,101 +112,63 @@ python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
funding BTC --hours 168 --limit 30
```
Notes:
- The info endpoint paginates time-range endpoints. If you need more than one
response window, repeat the query with a later `startTime`.
- This helper is for interactive inspection. If you later build a real
backtester, store the returned data in local files or a database.
Time-range endpoints paginate. For larger windows, repeat with a later
`startTime` or use `export` (below).
### 3. Inspect Live Microstructure
Use `l2` to inspect the current order book around a market.
### 3. Inspect Live Order Book
```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
l2 BTC --levels 10
```
This is useful when the user asks:
- whether the book looks thin
- where near-term liquidity sits
- whether a large order may move the market
Use when asked about book depth, near-term liquidity, or potential market
impact of a large order.
### 4. Review a User's Account State
Use `state` for perp positions and `spot-balances` for spot inventory.
### 4. Review an Account
```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
state 0x0000000000000000000000000000000000000000
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
state
state 0xabc...
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
spot-balances
```
Use these when the user asks:
- "How are my positions?"
- "What am I holding?"
- "How much is withdrawable?"
`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
Use `fills` and `orders` for recent execution history.
```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
fills 0x0000000000000000000000000000000000000000 --hours 72 --limit 25
fills 0xabc... --hours 72 --limit 25
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
orders --limit 25
```
### 6. Generate A Lightweight Trade Review
Use `review` to combine recent fills with candle and funding context for each
traded coin.
### 6. Generate a Trade Review
```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
review 0x0000000000000000000000000000000000000000 --hours 72 --fills 50
review 0xabc... --hours 72 --fills 50
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
review --coin BTC --hours 168
```
The review reports:
- realized PnL, fees, and net after fees
- win/loss counts
- coin-by-coin breakdowns
- market trend and average funding for each traded perp
- heuristics like fee drag, concentration, and counter-trend losses
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).
Use it as a first-pass reviewer, not a final judge. It works best when paired
with the raw `fills`, `orders`, `candles`, and `funding` commands.
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.
For deeper post-trade review:
1. Start with `review` to identify problem coins or windows.
2. Pull recent fills for the address.
3. Pull recent orders for the same period.
4. Pull `candles` and `funding` for each traded coin over the relevant window.
5. Judge decision quality separately from outcome quality.
Suggested review format:
- thesis at entry
- market context
- execution quality
- sizing quality
- exit quality
- what to repeat
- what to stop doing
### 7. Export A Reusable Market Dataset
Use `export` to write normalized candles plus funding history to a JSON file.
This is the clean handoff point for a future local backtester.
### 7. Export a Reusable Dataset
```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
@ -252,43 +178,34 @@ python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
export BTC --interval 15m --hours 72 --end-time-ms 1760000000000
```
The export file contains:
- schema version
- source metadata
- exact time window
- normalized candle rows
- normalized funding rows
- summary stats like price change and average funding
Use `--end-time-ms` when you want reproducible windows for comparisons,
debugging, or future backtests.
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 can require
multiple calls and may only return a capped window of rows.
- `fills --hours ...` uses `userFillsByTime`, which only exposes a recent
rolling history window.
- `historicalOrders` returns the most recent orders only; it is not a full
archive export.
- The `review` command is heuristic. It cannot reconstruct exact intent, order
placement quality, or true slippage from fills alone.
- The `export` command writes a normalized dataset contract, not a full
backtest engine. You still need your own fill/slippage model later.
- Spot aliases like `@107` are valid market identifiers even if the app UI
shows a friendlier name.
- Order-book data from `l2` is a point-in-time snapshot, not a time series.
- Candle/funding history is useful for review and prototyping, but it is not a
full execution simulator. Be conservative about slippage assumptions.
- 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
# Should print top Hyperliquid perp markets by 24h notional volume
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
markets --limit 5
```
Should print the top Hyperliquid perp markets by 24h notional volume.