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 {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):

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

How to Run Commands

{baseDir}/scripts/.venv/bin/python {baseDir}/scripts/hyperliquid_tools.py \x3Ccommand> [args]

Command Reference

Account

Market Data

Analysis

Trading

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)

Prediction Markets

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

HIP-3 Trading

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

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.

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 \x3Camount> --to-usdc (or swap \x3Camount> --token USDe --to-usdc).

Example workflow for km:US500:

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:

{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:

# 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:

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:

Environment Variables

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]).

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.