home / skills / openclaw / skills / hyperliquid

hyperliquid skill

safe

This skill fetches Hyperliquid market data via the Info endpoint and formats quotes, movers, funding, orders, and candles for chat.

npx playbooks add skill openclaw/skills --skill hyperliquid

Review the files below or copy the command above to add this skill to your agents.

Files (7)

SKILL.md

3.1 KB

---
name: hyperliquid
description: Read-only Hyperliquid market data assistant (perps + spot optional) with support for natural-language requests and deterministic command parsing (terminal-style `hl ...` and slash-style `/hl ...`). Use to fetch quotes (mark/mid/oracle/funding/OI/volume), top movers, funding rankings, L2 order book, and candle snapshots via https://api.hyperliquid.xyz/info, and to format results for chat.
---

# Hyperliquid (read-only)

Implement read-only market-data queries for Hyperliquid using the **Info** HTTP endpoint:

- `POST https://api.hyperliquid.xyz/info`
- `Content-Type: application/json`

Prefer **HTTP snapshot** flows for v1. WebSocket streaming can be added later.

## Supported user input styles

Treat these as equivalent:

- Natural language: “Hyperliquid quote BTC”, “top movers 24h”, “book ETH”, “1h candles for SOL last 48”
- Terminal style: `hl quote BTC`, `hl movers --top 10 --window 24h`
- Slash style: `/hl quote BTC`, `/hl overview`

Parse `/hl` and `hl` first (deterministic). If no prefix, fall back to intent extraction from natural language.

## Canonical commands (v1)

Market data:
- `quote <coin>`: show mark/mid/oracle, 24h change (prevDayPx), 24h notional volume, open interest (perps), funding (perps), premium, impact prices
- `movers [--window 24h] [--top N]`: rank by 24h % change (markPx vs prevDayPx)
- `funding-top|funding-bottom [--n N]`: rank by funding (perps only)
- `book <coin>`: show top 20 levels per side (and spread)
- `candles <coin> --interval <1m|...|1M> (--last N | --start <ms> --end <ms>)`
- `overview`: concise dashboard: top movers, top funding, top OI, top volume

Account (read-only):
- `positions <HL:0x..|0x..|label>`: show perp positions + margin summary
- `balances <HL:0x..|0x..|label>`: show spot balances
- `orders <HL:0x..|0x..|label>`: show open orders
- `fills <HL:0x..|0x..|label> [--n N]`: show recent fills

Saved account aliases (stored locally in `~/.clawdbot/hyperliquid/config.json`):
- `account list`
- `account add "sub account 1" HL:0x... [--default]`
- `account remove "sub account 1"`
- `account default "sub account 1"`

Natural language equivalents should work too:
- “store this address HL:0x... as sub account 1”
- “show me positions of sub account 1”

## Data sources

Perpetuals:
- `metaAndAssetCtxs` (preferred): universe + asset contexts for all perps
- `l2Book`
- `candleSnapshot`

Spot (optional later):
- `spotMetaAndAssetCtxs`, `spotMeta`

See `references/hyperliquid-api.md` for request bodies and field meanings.

## Implementation guidance

Use the bundled scripts:

- `scripts/hyperliquid_api.mjs`: thin HTTP client + helpers (safe defaults, timeouts)
- `scripts/hyperliquid_chat.mjs`: parses user text into an intent + args, calls API helpers, and prints a compact chat-friendly response

When responding:
- Prefer short bullet output.
- Show units and timeframes.
- Handle missing fields gracefully (e.g., midPx sometimes null).

## Quick manual test

Run locally:

```bash
node skills/hyperliquid/scripts/hyperliquid_chat.mjs "hl quote BTC"
node skills/hyperliquid/scripts/hyperliquid_chat.mjs "/hl movers --top 5"
```

Overview

This skill provides a read-only Hyperliquid market-data assistant that answers natural-language and deterministic terminal/slash commands. It fetches perp (and optional spot) data from the Hyperliquid Info HTTP endpoint and formats compact, chat-friendly summaries for quotes, movers, funding, order books, candles, and account reads. Use it for fast market checks, dashboards, and reproducible command-line queries.

How this skill works

The skill sends JSON POST requests to https://api.hyperliquid.xyz/info and consumes endpoints such as metaAndAssetCtxs, l2Book, and candleSnapshot. It supports three input styles: deterministic prefixes (hl or /hl), terminal-style commands, and natural-language fallbacks. Responses are parsed and formatted into short bullet lists with units and timeframes, handling missing fields gracefully (e.g., null midPx).

When to use it

Quickly fetch a mark/mid/oracle quote for a perp or spot symbol
Rank markets by 24h movers, funding rates, open interest, or volume
Inspect L2 order book top levels and spread before placing trades
Grab candle snapshots for charting or back-of-envelope analysis
Generate concise dashboards (overview) for market monitoring

Best practices

Prefer deterministic commands (hl or /hl) for reproducible results
Use the HTTP snapshot flow for v1 rather than streaming WebSocket
Include --interval and --last or start/end for precise candle queries
Request top-N or window flags to limit results and reduce payload
Interpret null or missing fields conservatively and show fallbacks

Example use cases

hl quote BTC — get mark/mid/oracle, 24h change, funding, OI and volume
hl movers --window 24h --top 10 — identify top 24h % winners and losers
hl book ETH — view top 20 levels per side and current spread
hl candles SOL --interval 1h --last 48 — fetch last 48 hourly candle snapshots
hl overview — compact dashboard: top movers, funding leaders, top OI and volume

FAQ

Which endpoint does the skill use to fetch data?

It posts JSON to https://api.hyperliquid.xyz/info and queries metaAndAssetCtxs, l2Book, and candleSnapshot as needed.

Can I use natural language instead of hl commands?

Yes. The skill prioritizes hl or /hl prefixes deterministically, then falls back to intent extraction from natural-language requests.