@2oolkit/hyperliquid-cli

@2oolkit/hyperliquid-cli

Trade perpetuals and spot on Hyperliquid — a high-performance onchain order book DEX — from your terminal or AI agent.

One package, three interfaces:

Interface	Command	Use Case
CLI	hyperliquid-cli	Terminal trading, scripting, automation
MCP Server	hyperliquid-mcp	AI agents (Claude, Cursor, Windsurf, etc.)
OpenClaw Skill	skill/SKILL.md	AI agent ecosystem (OpenClaw, ClawdBot)

200+ perpetual instruments, spot tokens, TWAP orders, and full account management.

Installation

npm install -g @2oolkit/hyperliquid-cli

This installs both hyperliquid-cli (CLI) and hyperliquid-mcp (MCP server).

Prerequisites

• Node.js >= 20
• A Hyperliquid wallet with funds deposited
• Your wallet's private key (for signing transactions)

CLI Usage

Quick Start

# 1. Interactive setup (prompts for environment, private key)
hyperliquid-cli config init

# 2. Check a price (no auth needed)
hyperliquid-cli market ticker BTC

# 3. Place a limit buy
hyperliquid-cli order place -c BTC -s buy -p 60000 -z 0.001

# 4. View open orders
hyperliquid-cli order list

Configuration

Interactive setup (recommended):

hyperliquid-cli config init

Prompts for:

Prompt	Description
Environment	mainnet or testnet
Private key	Hex private key (input masked with *)

The wallet address is automatically derived from the private key.

Manual setup:

hyperliquid-cli config set --env mainnet --private-key <hex-key>

Environment variables (CI/CD, Docker):

export HYPERLIQUID_WALLET_PRIVATE_KEY=<your-private-key>
export HYPERLIQUID_WALLET_ADDRESS=<your-wallet-address>

View current config:

hyperliquid-cli config list
hyperliquid-cli config get env

Config is saved to ~/.hyperliquid-cli/config.json with 0600 permissions.

Command Reference

Market Data (no auth required)

hyperliquid-cli market meta                        # List all perpetual instruments
hyperliquid-cli market meta --spot                 # List spot instruments
hyperliquid-cli market all-mids                    # All mid prices
hyperliquid-cli market ticker BTC                  # Price, volume, funding, OI
hyperliquid-cli market ticker BTC --spot           # Spot ticker
hyperliquid-cli market orderbook BTC               # L2 order book
hyperliquid-cli market orderbook BTC -d 3          # 3 sig figs depth
hyperliquid-cli market candles BTC -i 1h -n 500    # OHLCV candles (default 500)
hyperliquid-cli market candles BTC -i 1h -n 5000   # Up to 5000 in one request
hyperliquid-cli market candles BTC -i 1h -n 10000 --paginate  # Auto-paginate for more
hyperliquid-cli market funding BTC --hours 24      # Funding rate history
hyperliquid-cli market funding BTC --predicted     # Predicted funding rates
hyperliquid-cli market trades BTC                  # Recent trades

Candles (OHLCV):

The candleSnapshot endpoint returns up to 5000 candles per request (rolling time window, no cursor). The CLI defaults to -n 500.

hyperliquid-cli market candles BTC -i 1h -n 5000 -o json    # Max in a single request
hyperliquid-cli market candles BTC -i 1h -n 10000 --paginate -o json  # Fetch more via auto-pagination
hyperliquid-cli market candles BTC -i 15m --start-time 1700000000000 --end-time 1700864000000 --paginate -o json

Option	Description	Default
-i, --interval <interval>	One of 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 3d, 1w, 1M	1h
-n, --count <number>	Number of candles to fetch	500
--paginate	Auto-paginate (walk backwards by time) to fetch more than 5000 candles	false
--start-time <ms>	Window start (Unix ms); overrides the count-based start	—
--end-time <ms>	Window end (Unix ms)	now

• If -n exceeds 5000 without --paginate, the count is clamped to 5000 with a warning.
• With --paginate, requests are repeated with endTime = (oldest candle).t − 1ms until the requested count is reached or history is exhausted; results are deduped and sorted ascending by time.

Orders (auth required)

# Place orders
hyperliquid-cli order place -c BTC -s buy -p 60000 -z 0.001              # Limit buy (Gtc)
hyperliquid-cli order place -c BTC -s sell -p 80000 -z 0.001             # Limit sell
hyperliquid-cli order place -c BTC -s buy -p 70000 -z 0.001 --tif Ioc   # Immediate-or-cancel
hyperliquid-cli order place -c BTC -s buy -p 70000 -z 0.001 --tif Alo   # Post-only (add liquidity)
hyperliquid-cli order place -c BTC -s sell -z 0.001 --trigger-px 65000 --tpsl sl  # Stop-loss
hyperliquid-cli order place -c BTC -s sell -z 0.001 --reduce-only -p 80000        # Reduce-only

# Manage orders
hyperliquid-cli order list                                    # Open orders
hyperliquid-cli order get <oid>                               # Order status by ID
hyperliquid-cli order cancel -c BTC --oid <oid>               # Cancel one
hyperliquid-cli order cancel-all                              # Cancel all open orders
hyperliquid-cli order cancel-all -c BTC                       # Cancel all BTC orders only
hyperliquid-cli order modify --oid <oid> -c BTC -s buy -p 61000 -z 0.002  # Modify order

# History
hyperliquid-cli order history                                 # Order history
hyperliquid-cli order fills                                   # Recent fills
hyperliquid-cli order fills --hours 48                        # Fills from last 48h

# TWAP
hyperliquid-cli order twap -c BTC -s buy -z 0.1 -m 30        # TWAP over 30 minutes
hyperliquid-cli order twap-cancel -c BTC --twap-id <id>       # Cancel TWAP

# Dead man switch
hyperliquid-cli order schedule-cancel --delay 60              # Cancel all orders in 60s

Order place options:

Option	Required	Description	Default
-c, --coin <coin>	Yes	Coin name (e.g., BTC, ETH)	—
-s, --side <side>	Yes	buy or sell	—
-z, --size <size>	Yes	Order size	—
-p, --price <price>	Yes	Order price	—
--tif <tif>	No	Gtc, Alo (post-only), Ioc	Gtc
--reduce-only	No	Reduce only	false
--trigger-px <price>	No	Trigger price (stop/TP)	—
--tpsl <type>	No	tp or sl	sl
--cloid <id>	No	Client order ID (128-bit hex)	—

Positions

hyperliquid-cli position list                                 # All open positions + margin
hyperliquid-cli position leverage -c BTC -l 10                # Set 10x cross leverage
hyperliquid-cli position leverage -c BTC -l 5 --isolated      # Set 5x isolated
hyperliquid-cli position margin -c BTC -s buy -a 100          # Add $100 isolated margin

Account

hyperliquid-cli account state                     # Clearinghouse state (positions + margin)
hyperliquid-cli account spot                      # Spot token balances
hyperliquid-cli account portfolio                 # Portfolio summary
hyperliquid-cli account fees                      # Fee schedule
hyperliquid-cli account rate-limit                # Rate limit status
hyperliquid-cli account sub-accounts              # Sub-accounts
hyperliquid-cli account referral                  # Referral info
hyperliquid-cli account role                      # User role

Transfers (auth required)

hyperliquid-cli transfer usd-send -d <address> -a 100          # Send USDC on Hyperliquid
hyperliquid-cli transfer spot-send -d <address> -t <token> -a 10  # Send spot token
hyperliquid-cli transfer withdraw -d <address> -a 100           # Withdraw to Arbitrum (~5 min, $1 fee)
hyperliquid-cli transfer spot-to-perp -a 100                    # Spot → Perp
hyperliquid-cli transfer perp-to-spot -a 100                    # Perp → Spot
hyperliquid-cli transfer vault-deposit -v <vault> -a 100        # Vault deposit
hyperliquid-cli transfer vault-withdraw -v <vault> -a 100       # Vault withdraw
hyperliquid-cli transfer approve-agent -a <address>             # Approve API agent

Output Formats

All commands support -o json for scripting and piping:

hyperliquid-cli market ticker BTC -o json
hyperliquid-cli order list -o json | jq '.[].oid'

MCP Server

The MCP (Model Context Protocol) server exposes all Hyperliquid functionality as tools for AI agents. Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

Setup for Claude Code

claude mcp add hyperliquid-mcp -- hyperliquid-mcp

Setup for Claude Desktop / Cursor / Windsurf

Add to your MCP config file:

{
  "mcpServers": {
    "hyperliquid": {
      "command": "hyperliquid-mcp"
    }
  }
}

Or without global install:

{
  "mcpServers": {
    "hyperliquid": {
      "command": "npx",
      "args": ["-y", "-p", "@2oolkit/hyperliquid-cli", "hyperliquid-mcp"]
    }
  }
}

Available Tools (25)

Category	Tools	Auth
Market	get_all_mids, get_meta, get_ticker, get_orderbook, get_candles, get_funding, get_recent_trades	No
Orders	place_order, cancel_order, list_open_orders, get_order_status, get_order_history, get_user_fills	Yes
Positions	list_positions, update_leverage	Yes
Account	get_account_state, get_spot_balances, get_portfolio, get_user_fees, get_rate_limit, get_sub_accounts	Yes
Transfers	usd_send, spot_send, withdraw, usd_class_transfer	Yes

MCP Configuration

Option 1: CLI setup (recommended)

hyperliquid-cli config init

The MCP server reads the same config as the CLI (~/.hyperliquid-cli/).

Option 2: Environment variables in MCP config

Pass credentials directly in your MCP config file — no CLI setup needed:

{
  "mcpServers": {
    "hyperliquid": {
      "command": "hyperliquid-mcp",
      "env": {
        "HYPERLIQUID_WALLET_PRIVATE_KEY": "0x..."
      }
    }
  }
}

OpenClaw Skill

This package includes an OpenClaw skill definition for AI agent ecosystems. The skill file is located at skill/SKILL.md with detailed reference docs in skill/references/.

Compatible with OpenClaw, ClawdBot, and other agent skill platforms.

Asset Naming

Hyperliquid uses short coin names (not trading pairs):

Coin	Description
BTC	Bitcoin perpetual
ETH	Ethereum perpetual
SOL	Solana perpetual
ARB	Arbitrum perpetual
DOGE	Dogecoin perpetual

Use hyperliquid-cli market meta -o json for the full list with size decimals and max leverage.

Spot tokens use the same names. Add --spot flag for spot-specific commands.

Common Workflows

Close a Position

# Long position → sell reduce-only at market
hyperliquid-cli order place -c BTC -s sell -z 0.001 -p 100000 --tif Ioc --reduce-only

# Short position → buy reduce-only at market
hyperliquid-cli order place -c ETH -s buy -z 0.01 -p 1 --tif Ioc --reduce-only

Bracket Order (Entry + Take-Profit)

hyperliquid-cli order place -c BTC -s buy -z 0.01 -p 68000
hyperliquid-cli order place -c BTC -s sell -z 0.01 -p 75000 --reduce-only

Cancel Everything

hyperliquid-cli order cancel-all
hyperliquid-cli position list -o json
# For each position, create opposite reduce-only order

Portfolio Health Check

hyperliquid-cli account state -o json
hyperliquid-cli position list -o json
hyperliquid-cli order list -o json

Error Handling

Errors include actionable recovery instructions:

Error: Private key is not configured.

Try: hyperliquid-cli config init

Error	Recovery
Private key is not configured	hyperliquid-cli config init
Asset "XXX" not found	Check with hyperliquid-cli market meta
Invalid leverage	Use a valid integer
Exchange API error	Check the error message for details

Safety

• Use --reduce-only for exit orders — prevents accidental position flips
• Check instrument specs — hyperliquid-cli market meta -o json for size decimals and max leverage
• Start with small sizes when testing
• Never expose your private key — config file uses 0600 permissions, key is masked in output
• Use testnet first — hyperliquid-cli config set --env testnet

Configuration Files

File	Path	Description
Config	~/.hyperliquid-cli/config.json	Environment, private key, wallet address

Config uses 0600 permissions (owner read/write only). Private key is masked when displayed.

Environment Variables

Variable	Description
HYPERLIQUID_WALLET_PRIVATE_KEY	Private key (overrides config file)
HYPERLIQUID_WALLET_ADDRESS	Wallet address (overrides config file)
HYPERLIQUID_ENV	mainnet or testnet (default: mainnet)

Resources

• Hyperliquid: https://hyperliquid.xyz
• npm Package: https://www.npmjs.com/package/@2oolkit/hyperliquid-cli
• GitHub: https://github.com/haeminmoon/hyperliquid-cli
• Hyperliquid API Docs: https://hyperliquid.gitbook.io/hyperliquid-docs

License

MIT