hyperliquid-trading

Hyperliquid Trading

Hyperliquid is a high-performance L1 with a fully on-chain order book. Trade perpetuals with up to 50x leverage and spot markets with deep liquidity.

Key features:

• On-chain order book — All orders are on-chain, not just settlements
• Low fees — 0.01% maker / 0.035% taker for perpetuals
• 50+ perpetual markets — BTC, ETH, SOL, and many more
• Spot markets — Trade tokens directly

Installation

Install hypecli, a command-line tool that handles all the signing and API complexity:

curl -fsSL https://raw.githubusercontent.com/infinitefield/hypersdk/main/hypecli/install.sh | sh

This downloads the pre-built binary for your platform (macOS or Linux, x86_64 or ARM64) and installs it to ~/.local/bin (macOS) or /usr/local/bin (Linux).

For detailed documentation on all available commands:

hypecli --agent-help

Wallet Setup

Create an encrypted keystore to securely store your wallet:

# Create a new wallet with encrypted keystore
hypecli account create --name default --password yourpassword

# List available keystores
hypecli account list

Keystores are stored encrypted in ~/.foundry/keystores/.

Listing Markets

Before trading, check available markets:

# List all perpetual markets on Hyperliquid
hypecli perps

# List all spot markets
hypecli spot

# List available HIP-3 DEXes (third-party perpetual exchanges on Hyperliquid)
hypecli dexes

# List perpetual markets on a specific HIP-3 DEX
hypecli perps --dex xyz

HIP-3 DEXes are third-party perpetual exchanges deployed on Hyperliquid. Each DEX can list its own markets with different assets or configurations.

Asset Name Formats

Orders use human-readable asset names:

To trade on a HIP-3 DEX, prefix the asset with the DEX name and a colon (e.g., xyz:BTC).

Placing Orders

Limit Orders

Place a limit order that sits on the order book until filled or canceled:

# Buy 0.1 BTC at $50,000
hypecli order limit \
  --keystore default --password yourpassword \
  --asset BTC \
  --side buy \
  --price 50000 \
  --size 0.1

# Sell 1 ETH at $3,500 (maker-only)
hypecli order limit \
  --keystore default --password yourpassword \
  --asset ETH \
  --side sell \
  --price 3500 \
  --size 1 \
  --tif alo

Time-in-force options:

• gtc (default) — Good Till Cancel, remains until filled or canceled
• alo — Add Liquidity Only, rejected if it would take liquidity (maker-only)
• ioc — Immediate or Cancel, fill immediately or cancel unfilled portion

Additional flags:

• --reduce-only — Only reduce an existing position, won't open new positions
• --cloid <HEX> — Custom client order ID (16 bytes hex) for tracking

Market Orders

Execute immediately at the best available price:

# Market buy 0.1 BTC with slippage protection
hypecli order market \
  --keystore default --password yourpassword \
  --asset BTC \
  --side buy \
  --size 0.1 \
  --slippage-price 51000

# Market sell 1 ETH
hypecli order market \
  --keystore default --password yourpassword \
  --asset ETH \
  --side sell \
  --size 1 \
  --slippage-price 3400

The --slippage-price is the worst acceptable fill price. For buys, set it above current price. For sells, set it below.

Spot Trading

Trade spot markets using the BASE/QUOTE format:

# Buy PURR with USDC
hypecli order limit \
  --keystore default --password yourpassword \
  --asset PURR/USDC \
  --side buy \
  --price 0.05 \
  --size 1000

Canceling Orders

Cancel orders using the order ID (OID) returned when placing, or your custom client order ID (CLOID):

# Cancel by OID (exchange-assigned)
hypecli order cancel \
  --keystore default --password yourpassword \
  --asset BTC \
  --oid 123456789

# Cancel by CLOID (client-assigned)
hypecli order cancel \
  --keystore default --password yourpassword \
  --asset BTC \
  --cloid 0x0123456789abcdef0123456789abcdef

Checking Positions and Balances

View your current positions, margin, and balances:

# Check balances and positions
hypecli balance 0xYourAddress

# JSON output for parsing
hypecli balance 0xYourAddress --format json

This shows:

• Spot balances — Token holdings
• Perp account — Account value, margin used, withdrawable funds
• Positions — Open perpetual positions with entry price, size, unrealized PnL

Example Workflows

Workflow 1: Open a Long Position

# 1. Check current BTC price by looking at markets
hypecli perps

# 2. Place a limit buy order
hypecli order limit \
  --keystore default --password yourpassword \
  --asset BTC \
  --side buy \
  --price 48000 \
  --size 0.1

# 3. Check if order filled and view position
hypecli balance 0xYourAddress

Workflow 2: Close a Position

# Close a long position by selling (reduce-only ensures you don't flip short)
hypecli order market \
  --keystore default --password yourpassword \
  --asset BTC \
  --side sell \
  --size 0.1 \
  --slippage-price 47000 \
  --reduce-only

Workflow 3: Place and Cancel

# Place order with custom CLOID for tracking
hypecli order limit \
  --keystore default --password yourpassword \
  --asset ETH \
  --side buy \
  --price 3000 \
  --size 1 \
  --cloid 0xdeadbeef00000000deadbeef00000000

# Cancel using the CLOID
hypecli order cancel \
  --keystore default --password yourpassword \
  --asset ETH \
  --cloid 0xdeadbeef00000000deadbeef00000000

Quick Reference

Links

• Hyperliquid docs: https://hyperliquid.gitbook.io/hyperliquid-docs/
• hypecli source: https://github.com/infinitefield/hypersdk
• Trading interface: https://app.hyperliquid.xyz
• API reference: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api