HyperClaw

SKILL.md

---
name: hyperclaw
description: Trade on Hyperliquid. Supports 228+ perps, HIP-3 equity/commodity perps (TSLA, GOLD), market scanning, sentiment analysis, Grok web/X search, and prediction market data. Commands for account status, market data, funding rates, order book, trading, and intelligence gathering.
user-invocable: true
metadata:
  openclaw:
    requires:
      env:
        - HL_ACCOUNT_ADDRESS
        - HL_SECRET_KEY
---

# HyperClaw - Hyperliquid Trading Skill

Trade on Hyperliquid via CLI. Covers native crypto perps (BTC, ETH, SOL, etc.), HIP-3 builder-deployed perps (equities, commodities, forex), market scanning, and intelligence tools.

## Setup

Run the setup script once to create a virtual environment and install dependencies:

```bash
bash {baseDir}/scripts/setup.sh
```

Then configure `.env` in the skill root directory with your Hyperliquid API credentials:

```
HL_ACCOUNT_ADDRESS=0x_your_wallet_address
HL_SECRET_KEY=0x_your_api_wallet_private_key
HL_TESTNET=false
```

Get API keys from: https://app.hyperliquid.xyz/API — use a separate API wallet, not your main wallet private key.

Optional for intelligence commands (sentiment, unlocks, devcheck, ask, search):
```
XAI_API_KEY=xai-...
```

After configuring `.env`, start the caching proxy (prevents rate limiting):

```bash
{baseDir}/scripts/.venv/bin/python {baseDir}/scripts/server.py &
```

## How to Run Commands

```bash
{baseDir}/scripts/.venv/bin/python {baseDir}/scripts/hyperliquid_tools.py <command> [args]
```

## Command Reference

### Account

| Command | Description | Example |
|---------|-------------|---------|
| `status` | Account balance, account mode, positions, PnL (handles unified/portfolio margin accounts) | `hyperliquid_tools.py status` |
| `positions` | Detailed position info (leverage, liquidation) | `hyperliquid_tools.py positions` |
| `orders` | Open orders | `hyperliquid_tools.py orders` |
| `check` | Position health check (book ratio, funding, PnL, leverage, liquidation warnings) | `hyperliquid_tools.py check` or `check --address 0x...` |
| `user-funding` | Your funding payments received/paid | `hyperliquid_tools.py user-funding --lookback 7d` |
| `portfolio` | Portfolio performance (PnL, volume by period) | `hyperliquid_tools.py portfolio` or `portfolio --address 0x...` |
| `swap` | Swap USDC ↔ HIP-3 dex collateral (USDH, USDe, USDT0, USDXL) | `hyperliquid_tools.py swap 20` or `swap 20 --token USDe` or `swap 10 --to-usdc` |

### Market Data

| Command | Description | Example |
|---------|-------------|---------|
| `price [COINS...]` | Current prices (supports HIP-3 dex prefix) | `hyperliquid_tools.py price BTC ETH xyz:TSLA` |
| `funding [COINS...]` | Funding rates (hourly + APR + signal). `--predicted` shows the estimated rate for the next hourly settlement (can still shift as mark/oracle prices move before the hour closes), with Binance/Bybit comparison (APR-normalized across different intervals). Use predicted to preview upcoming charges and confirm a funding edge isn't HL-specific. | `hyperliquid_tools.py funding BTC SOL DOGE` or `funding BTC --predicted` |
| `book COIN` | L2 order book with spread | `hyperliquid_tools.py book SOL` |
| `candles COIN` | OHLCV candlestick data with SMA | `hyperliquid_tools.py candles BTC --interval 1h --lookback 7d` |
| `funding-history COIN` | Historical funding rates with summary | `hyperliquid_tools.py funding-history BTC --lookback 24h` |
| `trades COIN` | Recent trade tape with buy/sell bias | `hyperliquid_tools.py trades BTC --limit 20` |
| `raw COIN` | Raw JSON data dump for processing | `hyperliquid_tools.py raw BTC` |

### Analysis

| Command | Description | Example |
|---------|-------------|---------|
| `analyze [COINS...]` | Comprehensive market analysis (prices, funding, OI, volume, book depth) | `hyperliquid_tools.py analyze BTC ETH SOL` |
| `scan` | Scan all perps for funding opportunities. `--sort {funding\|volume\|oi\|price-change}` outputs a single flat table sorted by the chosen metric (default: multi-section view). `--reverse` reverses sort direction. | `hyperliquid_tools.py scan --top 20 --min-volume 100000` or `scan --sort volume --top 10 --reverse` |
| `hip3 [COIN]` | HIP-3 perp data (price, spread, funding) | `hyperliquid_tools.py hip3 TSLA` |
| `hip3` | All HIP-3 dex assets | `hyperliquid_tools.py hip3` |
| `dexes` | List all HIP-3 dexes and their assets | `hyperliquid_tools.py dexes` |
| `history` | Trade history from API | `hyperliquid_tools.py history --limit 20` |

### Trading

| Command | Description | Example |
|---------|-------------|---------|
| `leverage COIN LEV` | Set leverage for an asset (persists on Hyperliquid) | `hyperliquid_tools.py leverage SOL 5` |
| `leverage COIN LEV --isolated` | Set leverage with isolated margin | `hyperliquid_tools.py leverage xyz:TSLA 3 --isolated` |
| `buy COIN SIZE` | Market buy (long) | `hyperliquid_tools.py buy SOL 0.5` |
| `buy COIN SIZE --leverage LEV` | Market buy with leverage set first | `hyperliquid_tools.py buy SOL 0.5 --leverage 5` |
| `sell COIN SIZE` | Market sell (short) | `hyperliquid_tools.py sell SOL 0.5` |
| `sell COIN SIZE --leverage LEV` | Market sell with leverage set first | `hyperliquid_tools.py sell SOL 0.5 --leverage 5` |
| `limit-buy COIN SIZE PRICE` | Limit buy order (GTC) | `hyperliquid_tools.py limit-buy SOL 1 120` |
| `limit-sell COIN SIZE PRICE` | Limit sell order (GTC) | `hyperliquid_tools.py limit-sell SOL 1 140` |
| `stop-loss COIN SIZE TRIGGER` | Stop-loss trigger (market, reduce-only) | `hyperliquid_tools.py stop-loss SOL 0.5 115` |
| `take-profit COIN SIZE TRIGGER` | Take-profit trigger (market, reduce-only) | `hyperliquid_tools.py take-profit SOL 0.5 150` |
| `close COIN` | Close entire position (supports HIP-3) | `hyperliquid_tools.py close SOL` |
| `cancel OID` | Cancel specific order | `hyperliquid_tools.py cancel 12345` |
| `cancel-all` | Cancel all open orders | `hyperliquid_tools.py cancel-all` |
| `modify-order OID PRICE` | Modify existing order price/size | `hyperliquid_tools.py modify-order 12345 130.5 --size 2` |

**Leverage:** Leverage is set per-asset on your Hyperliquid account and persists until changed. Each asset has a max leverage (e.g., BTC=40x, ETH=25x, SOL=20x). The `leverage` command and `--leverage` flag show the max and block if exceeded. Use `positions` to see current leverage on open positions. HIP-3 assets require isolated margin (`--isolated`).

### Intelligence (requires XAI_API_KEY)

| Command | Description | Example |
|---------|-------------|---------|
| `sentiment COIN` | Grok web + X/Twitter sentiment analysis | `hyperliquid_tools.py sentiment BTC` |
| `unlocks [COINS...]` | Token unlock schedules (defaults to current positions) | `hyperliquid_tools.py unlocks SOL HYPE` |
| `devcheck COIN` | Developer sentiment and exodus signals | `hyperliquid_tools.py devcheck SOL` |
| `ask QUERY` | Ask Grok a question — single API call with web + X tools, returns one blended answer. `--web` for web only, `--x` for X only. | `hyperliquid_tools.py ask "what's driving ETH price today?"` or `ask "BTC whale activity" --x` |
| `search QUERY` | Search web and X/Twitter via Grok — separate API calls per source, prints results in distinct sections for more exhaustive coverage. `--web` for web only, `--x` for X only. | `hyperliquid_tools.py search "Hyperliquid token unlock schedule"` or `search "SOL news" --web` |

### Prediction Markets

| Command | Description | Example |
|---------|-------------|---------|
| `polymarket [CATEGORY]` | Active Polymarket prediction markets | `hyperliquid_tools.py polymarket crypto` |

Categories: `crypto` (default), `btc`, `eth`, `trending`, `macro`

### HIP-3 Trading

HIP-3 assets use a dex prefix: `dex:SYMBOL`

```bash
hyperliquid_tools.py buy xyz:TSLA 1          # Buy TSLA on xyz dex
hyperliquid_tools.py sell vntl:ANTHROPIC 1   # Sell ANTHROPIC on vntl dex
hyperliquid_tools.py close xyz:GOLD          # Close GOLD position
hyperliquid_tools.py funding xyz:TSLA vntl:SPACEX km:US500
```

**Known HIP-3 dexes:** xyz (equities, commodities), vntl (private companies), flx (crypto/commodities), hyna (crypto), km (indices), abcd, cash. Use `dexes` command to discover all available dexes dynamically.

**HIP-3 differences from native perps:**
- Isolated margin only (no cross margin)
- Per-position liquidation prices
- Higher fees (2x normal)
- Thinner order books (wider spreads)
- Max leverage varies by asset (10x for most equities, 20x for commodities/metals)
- Some dexes require non-USDC collateral — swap first (see below)

**HIP-3 Collateral:** Some dexes use stablecoin collateral other than USDC (e.g. USDH, USDe, USDT0). You must swap USDC to the required collateral before trading on these dexes. Use `dexes` to check current collateral requirements — they can change.

| Collateral | Swap command |
|-----------|--------------|
| USDC | No swap needed |
| USDH | `swap <amount>` (default) |
| USDe | `swap <amount> --token USDe` |
| USDT0 | `swap <amount> --token USDT0` |
| USDXL | `swap <amount> --token USDXL` |

**Note on USDXL:** USDXL (Last USD) is not on Hyperliquid's strict list and has lower liquidity than other collateral tokens. Expect wider spreads when swapping. No HIP-3 dex currently uses USDXL as collateral, but the swap is available if needed.

To swap collateral back to USDC: `swap <amount> --to-usdc` (or `swap <amount> --token USDe --to-usdc`).

Example workflow for km:US500:
```bash
hyperliquid_tools.py swap 20                          # Swap 20 USDC → USDH
hyperliquid_tools.py leverage km:US500 10 --isolated  # Set leverage
hyperliquid_tools.py buy km:US500 0.02                # Trade
hyperliquid_tools.py close km:US500                   # Close when done
hyperliquid_tools.py swap 20 --to-usdc                # Swap USDH back to USDC
```

## Caching Proxy (Default — Start First)

Each CLI invocation cold-starts the SDK and burns ~40 API weight units just to initialize. With a 1200 weight/min IP limit, agents hit rate limits after ~30 commands. **Always start the proxy before running commands.**

**Start the proxy:**

```bash
{baseDir}/scripts/.venv/bin/python {baseDir}/scripts/server.py &
```

The `.env` file includes `HL_PROXY_URL=http://localhost:18731` by default. All read commands will route through the proxy automatically. To disable the proxy (not recommended), comment out or remove `HL_PROXY_URL` from `.env`.

**Restart the proxy** after installing or updating the skill (e.g. `git pull`, dependency changes). The proxy runs in-memory — it won't pick up code or config changes until restarted:

```bash
# Find and kill existing proxy, then restart
kill $(lsof -ti:18731) 2>/dev/null; {baseDir}/scripts/.venv/bin/python {baseDir}/scripts/server.py &
```

**Proxy endpoints:**

| Endpoint | Description |
|----------|-------------|
| `GET /health` | Check proxy status and uptime |
| `GET /cache/stats` | Cache hit/miss rates per type |
| `POST /cache/clear` | Clear cache (optional body: `{"type":"..."}` or `{"user":"0x..."}`) |

The proxy caches `/info` read responses (metadata 300s, prices 5s, user state 2s). Trading commands (`buy`, `sell`, `close`, etc.) always go directly to the real Hyperliquid API — they bypass the proxy entirely because the SDK requires the real URL for transaction signing. The proxy is a **read cache only**. Responses include `X-Cache: HIT` or `X-Cache: MISS` headers.

**Proxy env vars:**

| Variable | Default | Description |
|----------|---------|-------------|
| `HL_UPSTREAM_URL` | `https://api.hyperliquid.xyz` | Upstream API |
| `HL_PROXY_PORT` | `18731` | Proxy port |
| `HL_CACHE_WARMUP` | `true` | Pre-warm cache on startup |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `HL_ACCOUNT_ADDRESS` | For trading/status | Hyperliquid wallet address |
| `HL_SECRET_KEY` | For trading | API wallet private key |
| `HL_TESTNET` | No | `false` for mainnet (default), `true` for testnet |
| `HL_PROXY_URL` | Recommended | Caching proxy URL (default: `http://localhost:18731`) |
| `HL_ENV_FILE` | No | Override `.env` file path. When set, loads env vars from this file instead of default `.env` discovery. Useful for wrapper scripts that route to hyperclaw from other projects. |
| `XAI_API_KEY` | For intelligence | Grok API key for sentiment/unlocks/devcheck/ask/search |

**Read-only commands** (`price`, `funding`, `book`, `scan`, `hip3`, `dexes`, `raw`, `polymarket`) work without credentials. Trading and account commands require `HL_ACCOUNT_ADDRESS` and `HL_SECRET_KEY`.

## Account Abstraction Modes

**Unified mode is recommended for API wallet trading.** In standard mode, funds are split between spot and perp clearinghouses, and API wallets cannot transfer between them. Unified mode pools all funds into a single balance, so cross-margin perps can access your full balance without manual transfers. HIP-3 dexes that require non-USDC collateral work in both modes — just use the `swap` command to convert USDC to the required collateral.

Hyperliquid accounts operate in one of several modes that affect where balances live. The `status` command auto-detects the mode and shows it as a badge (`[unified]`, `[portfolio margin]`, or `[standard]`).

| Mode | Badge | How balances work |
|------|-------|-------------------|
| **Unified** (default) | `[unified]` | Single balance per asset across all DEXes. Spot and perp share collateral. All balances appear in the spot clearinghouse. |
| **Portfolio Margin** | `[portfolio margin]` | All eligible assets (HYPE, BTC, USDH, USDC) unified into one margin calculation. Most capital-efficient. Pre-alpha. |
| **Standard** | `[standard]` | Separate balances for perps and spot on each DEX. No cross-collateralization. |
| **DEX Abstraction** | `[unified]` | Deprecated. USDC defaults to perps balance, other collateral to spot. Shown as `[unified]` since behavior is similar. |

**For position sizing, always use "Portfolio Value"** from `status`. In standard mode this equals the perp account value. In unified/portfolio margin mode it equals `perp accountValue + spot balances`, since funds can live in either clearinghouse. The "Perp Margin" sub-line (only shown for non-standard modes) is just the perp clearinghouse portion — don't use it for sizing.