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:

CODEBLOCK0

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

CODEBLOCK1

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

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

CODEBLOCK3

How to Run Commands

CODEBLOCK4

Command Reference

Account

Command	Description	Example
INLINECODE2	Account balance, account mode, positions, PnL (handles unified/portfolio margin accounts)	INLINECODE3
INLINECODE4

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
INLINECODE20	Current prices (supports HIP-3 dex prefix)	INLINECODE21
INLINECODE22

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
INLINECODE36	Comprehensive market analysis (prices, funding, OI, volume, book depth)	INLINECODE37
INLINECODE38

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
INLINECODE51	Set leverage for an asset (persists on Hyperliquid)	INLINECODE52
INLINECODE53

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 XAIAPIKEY)

Command	Description	Example
INLINECODE83	Grok web + X/Twitter sentiment analysis	INLINECODE84
INLINECODE85

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
INLINECODE99	Active Polymarket prediction markets	INLINECODE100

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

HIP-3 Trading

HIP-3 assets use a dex prefix: INLINECODE106

CODEBLOCK5

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

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:

CODEBLOCK7

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:

CODEBLOCK8

Proxy endpoints:

Endpoint	Description
INLINECODE120	Check proxy status and uptime
INLINECODE121

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
INLINECODE131	INLINECODE132	Upstream API
INLINECODE133

18731 | Proxy port |
| HL_CACHE_WARMUP | true | Pre-warm cache on startup |

Environment Variables

Variable	Required	Description
INLINECODE137	For trading/status	Hyperliquid wallet address
INLINECODE138

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