mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-05-25 05:52:34 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

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 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 version: 0.1.0
author: Hermes Agent author: Hugo Sequier (Hugo-SEQUIER), Hermes Agent
license: MIT license: MIT
platforms: [linux, macos, windows]
metadata: metadata:
hermes: hermes:
tags: [Hyperliquid, Blockchain, Crypto, Trading, Perpetuals, Spot, DeFi] tags: [Hyperliquid, Blockchain, Crypto, Trading, Perpetuals, Spot, DeFi]
@ -12,134 +13,97 @@ metadata:
# Hyperliquid Skill # Hyperliquid Skill
Query Hyperliquid market data and user account history through the public Query Hyperliquid market and account data through the public `/info` endpoint.
`/info` endpoint. Read-only — no API key, no signing, no order placement.
12 commands: dexs, perp markets, spot markets, candle history, funding history, 12 commands: `dexs`, `markets`, `spots`, `candles`, `funding`, `l2`, `state`,
L2 books, perp state, spot balances, fills, historical orders, trade review, `spot-balances`, `fills`, `orders`, `review`, `export`. Stdlib only
and normalized market-data export. (`urllib`, `json`, `argparse`).
No API key needed. Uses only Python standard library (`urllib`, `json`,
`argparse`).
--- ---
## When to Use ## When to Use
- User asks for Hyperliquid perp or spot market data - User asks for Hyperliquid perp or spot market data, candles, funding, or L2 book
- User wants historical candles for a Hyperliquid market - User wants to inspect a wallet's perp positions, spot balances, fills, or orders
- User wants current funding, open interest, or 24h notional volume - User wants a post-trade review combining recent fills with market context
- 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 wants to inspect builder-deployed perp dexs or HIP-3 markets - 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 ## Prerequisites
The helper script uses only Python standard library. Stdlib only — no external packages, no API key.
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.
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 ```bash
https://api.hyperliquid.xyz python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py <command> [args]
``` ```
Optional testnet or custom override: Add `--json` to any command for machine-readable output.
```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
```
--- ---
## Quick Reference ## Quick Reference
```bash ```bash
python3 hyperliquid_client.py dexs hyperliquid_client.py dexs
python3 hyperliquid_client.py markets [--dex DEX] [--limit N] [--sort volume|oi|funding_abs|change_abs|name] hyperliquid_client.py markets [--dex DEX] [--limit N] [--sort volume|oi|funding_abs|change_abs|name]
python3 hyperliquid_client.py spots [--limit N] hyperliquid_client.py spots [--limit N]
python3 hyperliquid_client.py candles <coin> [--interval 1h] [--hours 24] [--limit N] hyperliquid_client.py candles <coin> [--interval 1h] [--hours 24] [--limit N]
python3 hyperliquid_client.py funding <coin> [--hours 72] [--limit N] hyperliquid_client.py funding <coin> [--hours 72] [--limit N]
python3 hyperliquid_client.py l2 <coin> [--levels N] hyperliquid_client.py l2 <coin> [--levels N]
python3 hyperliquid_client.py state [address] [--dex DEX] hyperliquid_client.py state [address] [--dex DEX]
python3 hyperliquid_client.py spot-balances [address] [--limit N] hyperliquid_client.py spot-balances [address] [--limit N]
python3 hyperliquid_client.py fills [address] [--hours N] [--limit N] [--aggregate-by-time] hyperliquid_client.py fills [address] [--hours N] [--limit N] [--aggregate-by-time]
python3 hyperliquid_client.py orders [address] [--limit N] hyperliquid_client.py orders [address] [--limit N]
python3 hyperliquid_client.py review [address] [--coin COIN] [--hours N] [--fills N] 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 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
For `state`, `spot-balances`, `fills`, `orders`, and `review`, the address is optional if `HYPERLIQUID_USER_ADDRESS` is set. optional when `HYPERLIQUID_USER_ADDRESS` is set in `~/.hermes/.env`.
--- ---
## Procedure ## 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 ### 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 ```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py dexs python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py dexs
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
markets --limit 15 --sort volume 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 \ python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
spots --limit 15 spots --limit 15
``` ```
Tips: - `--dex` only applies to perp endpoints; omit for the first perp dex.
- `--dex` is only for perp endpoints; omit it for the first perp dex. - Spot pairs may show as `PURR/USDC` or aliases like `@107`.
- Spot pairs may appear as `PURR/USDC` or internal aliases like `@107`. - HIP-3 markets prefix the coin with the dex, e.g. `mydex:BTC`.
- For HIP-3 markets, coin strings may include a dex prefix such as `mydex:BTC`.
### 2. Pull Historical Market Data ### 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 ```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
candles BTC --interval 1h --hours 72 --limit 48 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 funding BTC --hours 168 --limit 30
``` ```
Notes: Time-range endpoints paginate. For larger windows, repeat with a later
- The info endpoint paginates time-range endpoints. If you need more than one `startTime` or use `export` (below).
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.
### 3. Inspect Live Microstructure ### 3. Inspect Live Order Book
Use `l2` to inspect the current order book around a market.
```bash ```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
l2 BTC --levels 10 l2 BTC --levels 10
``` ```
This is useful when the user asks: Use when asked about book depth, near-term liquidity, or potential market
- whether the book looks thin impact of a large order.
- where near-term liquidity sits
- whether a large order may move the market
### 4. Review a User's Account State ### 4. Review an Account
Use `state` for perp positions and `spot-balances` for spot inventory.
```bash ```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
state 0x0000000000000000000000000000000000000000 state 0xabc...
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
state
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
spot-balances spot-balances
``` ```
Use these when the user asks: `state` returns perp positions; `spot-balances` returns spot inventory.
- "How are my positions?" Use these for "how are my positions?", "what am I holding?", "how much is
- "What am I holding?" withdrawable?".
- "How much is withdrawable?"
### 5. Review Fills and Orders ### 5. Review Fills and Orders
Use `fills` and `orders` for recent execution history.
```bash ```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ 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 \ python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
orders --limit 25 orders --limit 25
``` ```
### 6. Generate A Lightweight Trade Review ### 6. Generate a Trade Review
Use `review` to combine recent fills with candle and funding context for each
traded coin.
```bash ```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ 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 \ python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
review --coin BTC --hours 168 review --coin BTC --hours 168
``` ```
The review reports: Reports realized PnL, fees, win/loss counts, coin breakdowns, market trend
- realized PnL, fees, and net after fees and average funding for each traded perp, plus heuristics (fee drag,
- win/loss counts concentration, counter-trend losses).
- coin-by-coin breakdowns
- market trend and average funding for each traded perp
- heuristics like fee drag, concentration, and counter-trend losses
Use it as a first-pass reviewer, not a final judge. It works best when paired For deeper post-trade analysis: start with `review` to find problem coins
with the raw `fills`, `orders`, `candles`, and `funding` commands. 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: ### 7. Export a Reusable Dataset
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.
```bash ```bash
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ 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 export BTC --interval 15m --hours 72 --end-time-ms 1760000000000
``` ```
The export file contains: Output JSON contains: schema version, source metadata, exact time window,
- schema version normalized candle rows, normalized funding rows, summary stats. Use
- source metadata `--end-time-ms` for reproducible windows.
- 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.
--- ---
## Pitfalls ## Pitfalls
- Public info endpoints are rate-limited. Large historical queries can require - Public info endpoints are rate-limited. Large historical queries may
multiple calls and may only return a capped window of rows. return capped windows; iterate with later `startTime` values.
- `fills --hours ...` uses `userFillsByTime`, which only exposes a recent - `fills --hours ...` uses `userFillsByTime`, which only exposes a
rolling history window. recent rolling window — not full archive history.
- `historicalOrders` returns the most recent orders only; it is not a full - `historicalOrders` returns recent orders only; not a full export.
archive export. - The `review` command is heuristic. It cannot reconstruct intent,
- The `review` command is heuristic. It cannot reconstruct exact intent, order order placement quality, or true slippage from fills alone.
placement quality, or true slippage from fills alone. - The `export` command writes a normalized dataset, not a backtest
- The `export` command writes a normalized dataset contract, not a full engine. You still need your own slippage/fill model.
backtest engine. You still need your own fill/slippage model later. - Spot aliases like `@107` are valid identifiers even when the UI shows
- Spot aliases like `@107` are valid market identifiers even if the app UI a friendlier name.
shows a friendlier name. - `l2` is a point-in-time snapshot, not a time series.
- 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.
--- ---
## Verification ## Verification
```bash ```bash
# Should print top Hyperliquid perp markets by 24h notional volume
python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
markets --limit 5 markets --limit 5
``` ```
Should print the top Hyperliquid perp markets by 24h notional volume.