Hyperliquid Supurr Skill — Complete Command Reference

For LLMs: This is the authoritative reference. Use exact syntax. Config files are in ~/.supurr/configs/.

Quick Reference

Global Options

supurr --help              # Show all commands
supurr --version, -V       # Show CLI version
supurr -d, --debug         # Enable debug logging (any command)

1. supurr init — Credential Setup

# Interactive
supurr init

# Non-interactive
supurr init --address 0x... --api-wallet 0x...

# Overwrite existing
supurr init --force

2. supurr whoami — Show Identity

supurr whoami    # Shows: Address + masked key

3. supurr new <strategy> — Config Generator

Supports three strategies: grid, arb, dca.

supurr new grid [options]   # Grid trading
supurr new arb [options]    # Spot-perp arbitrage
supurr new dca [options]    # Dollar-cost averaging

3a. supurr new grid — Grid Strategy

Market Types

Grid Options

Grid Examples

# Native Perp (BTC-USDC)
supurr new grid --asset BTC --levels 4 --start-price 88000 --end-price 92000 --investment 100 --leverage 20

# USDC Spot (HYPE/USDC)
supurr new grid --asset HYPE --type spot --quote USDC --levels 3 --start-price 29 --end-price 32 --investment 100

# Non-USDC Spot (HYPE/USDH)
supurr new grid --asset HYPE --type spot --quote USDH --levels 3 --start-price 29 --end-price 32 --investment 100

# HIP-3 (hyna:BTC)
supurr new grid --asset BTC --type hip3 --dex hyna --levels 4 --start-price 88000 --end-price 92000 --investment 100 --leverage 20

HIP-3 DEXes

3b. supurr new arb — Spot-Perp Arbitrage Strategy

Generates a config that simultaneously trades the spot and perp legs of the same asset, capturing spread differentials.

Market Constraint: Only assets that have both a spot token AND a perp market on Hyperliquid are eligible. The CLI auto-resolves the spot counterpart.

Spot Resolution Logic

Resolution order: try U{ASSET} first (e.g., BTC → UBTC) → fallback to exact name (e.g., HYPE, TRUMP) → error if neither exists.

⚠️ Always pass the perp ticker (e.g., BTC, not UBTC). See full table → references/arb-spot-resolution.md

Arb Options

Arb Examples

# BTC spot-perp arb (default $100/leg)
supurr new arb --asset BTC

# HYPE arb with $50 per leg, 2x leverage on perp
supurr new arb --asset HYPE --amount 50 --leverage 2

# ETH arb with tighter spreads
supurr new arb --asset ETH --open-spread 0.002 --close-spread -0.0005 --slippage 0.0005

# SOL arb on testnet
supurr new arb --asset SOL --testnet

Balance Requirement: Arb bots require USDC balance in both Spot and Perps wallets on Hyperliquid, since the bot trades on both sides simultaneously.

3c. supurr new dca — DCA Strategy

Generates a Dollar-Cost Averaging config that opens positions in steps when price deviates, then takes profit on the averaged entry.

DCA Options

DCA Examples

# BTC DCA long, trigger at $95k
supurr new dca --asset BTC --trigger-price 95000

# ETH DCA short with custom deviation
supurr new dca --asset ETH --mode short --deviation 0.02

# HYPE DCA with auto-restart
supurr new dca --asset HYPE --restart --cooldown 120 --take-profit 0.03

# DCA on spot market
supurr new dca --asset HYPE --type spot --quote USDC --trigger-price 25

4. supurr configs — List Saved Configs

supurr configs    # Lists all configs in ~/.supurr/configs/

Output:

📁 Configs (/Users/you/.supurr/configs):
  btc-grid.json         grid     BTC-USDC
  hype-usdc-spot.json   grid     HYPE-USDC
  hyna-btc.json         grid     BTC-USDE

5. supurr config <name> — View Config

supurr config btc-grid        # View btc-grid.json
supurr config btc-grid.json   # Same

6. supurr backtest — Run Backtest

Syntax

supurr backtest -c <config> [options]

Supported strategies: Grid, DCA, and custom strategies. Arb (spot-perp arbitrage) backtesting is not supported — arb requires simultaneous dual-market execution that cannot be accurately simulated from single-asset price feeds.

⚠️ IMPORTANT — Asset ID Required: Bot configs require a market_index (Hyperliquid's internal asset index, e.g. 3 for BTC). You must know this value beforehand. It is not auto-resolved by the CLI. To find it, query the Hyperliquid Info API: POST https://api.hyperliquid.xyz/info with {"type": "meta"} — the response universe array contains all assets with their indices. Alternatively, check the Hyperliquid Info API reference for the exact endpoint.

Options

Examples

# By config name (looks in ~/.supurr/configs/)
supurr backtest -c btc-grid.json -s 2026-01-28 -e 2026-02-01

# By full path
supurr backtest -c ~/.supurr/configs/btc-grid.json -s 2026-01-28 -e 2026-02-01

# Save results
supurr backtest -c btc-grid.json -s 2026-01-28 -e 2026-02-01 -o results.json

Archive Data Availability

Note: Archive data available from 2026-01-28 onwards.

Important: Backtests use Supurr's price archive (tick-level) or a user-provided prices file (-p). Do not use Hyperliquid Info API mids/candles for backtests; they don't provide tick-level historical data and will produce inaccurate results.

6a. supurr paper — Paper Trading

Run any strategy with real market quotes but simulated fills. No real orders are placed on the exchange.

Uses the same isolated-margin simulation engine as supurr backtest, including:

• Per-position margin reservation and liquidation detection
• Configurable leverage, fee rates, and starting balance
• Real-time equity, unrealized PnL, and position tracking

Syntax

supurr paper -c <config> [--debug]

Options

Examples

# By config name (looks in ~/.supurr/configs/)
supurr paper -c my-grid-bot

# By file path
supurr paper -c ./config-v2-grid-perp.json

# With debug logging
supurr paper -c my-grid-bot --debug

Simulation Config (optional)

Add a top-level simulation block to your config JSON to control paper trading assumptions:

{
  "simulation": {
    "starting_balance_usdc": "10000",
    "fee_rate": "0.00025"
  }
}

Ctrl+C to stop paper trading cleanly. The engine cancels all open orders on shutdown.

6b. supurr dev — Custom Strategy Development

Development commands for building and testing custom strategies locally.

supurr dev init              # Clone/update bot source to ~/.supurr/bot-source/
supurr dev build             # Build from source (cargo build --release)
supurr dev run -c <config>   # Run locally-built bot
supurr dev backtest -c <config> [options]  # Backtest with dev-built engine

supurr dev backtest

Identical to supurr backtest but uses the dev-built engine at ~/.supurr/bot-source/target/release/bot instead of the installed binary. This lets you backtest custom strategies that you've added to the bot source.

# Backtest your custom strategy
supurr dev backtest -c config-mystrategy.json -s 2026-01-28 -e 2026-02-01

# With local prices
supurr dev backtest -c config-mystrategy.json -p prices.json

All options from supurr backtest apply (-s, -e, -p, --no-cache, -o).

Prerequisite: Run supurr dev build first to compile your custom strategy into the dev binary.

Full Custom Strategy Workflow

# 1. Clone the bot source
supurr dev init

# 2. Add your strategy crate (see STRATEGY_API.md)
# 3. Build with your strategy
supurr dev build

# 4. Backtest it
supurr dev backtest -c config-mystrategy.json -s 2026-01-28 -e 2026-02-01

# 5. Run live (paper or real)
supurr dev run -c config-mystrategy.json

7. supurr deploy — Deploy Bot

supurr deploy -c <config> [-s <address> | -v <address>]

Subaccount vs Vault:

• Subaccount = personal trading account under your master wallet. Verified via subAccounts API (checks master field).
• Vault = shared investment pool you manage. Verified via vaultDetails API (checks leader field).
• Both set vault_address in the bot config on success.
• Cannot use both --subaccount and --vault simultaneously.

Examples

# Deploy from main wallet
supurr deploy -c btc-grid.json

# Deploy from subaccount
supurr deploy -c btc-grid.json -s 0x804e57d7baeca937d4b30d3cbe017f8d73c21f1b

# Deploy from vault (you must be the vault leader)
supurr deploy -c config.json --vault 0xdc89f67e74098dd93a1476f7da79747f71ccb5d9

# HL: prefix is auto-stripped (copy-paste from Hyperliquid UI)
supurr deploy -c config.json -s HL:0x804e57d7baeca937d4b30d3cbe017f8d73c21f1b

Output:

✔ Loaded config for grid strategy
✔ Subaccount verified: 0x804e57d7...
✔ Bot deployed successfully!
📦 Deployment Details
  Bot ID:       217
  Pod Name:     bot-217
  Bot Type:     grid
  Market:       BTC-USDC

Gotchas: HL: prefix is auto-stripped from addresses. Subaccount requires master to match your supurr whoami address. Only the vault leader can deploy.

8. supurr monitor — View User's Bots

Updated in v0.2.8: Now shows only the user's bots by default (requires supurr init). Use --history to include stopped bots.

Syntax

supurr monitor [options]

Options

Examples

supurr monitor                 # Show only active bots for current user
supurr monitor --history       # Show all bots (active + stopped)
supurr monitor --watch         # Live monitoring (Ctrl+C to exit)
supurr monitor --watch --history  # Live monitoring with history
supurr monitor -w 0x1234...    # Filter by wallet

Behavior

• User-Specific: Fetches bots for the address in ~/.supurr/credentials.json (from supurr init)
• Default: Shows only active bots (status = "running" or "starting")
• With --history: Shows all bots including stopped ones
• Header: Displays user address and sync delay: 🤖 Active Bots │ User: 0x0ecba... │ Sync delay: 0s
• Trading Link: Shows clickable visualization link at the end with correct market format:
  • Spot: KNTQ_USDH (underscore separator)
  • Perp: BTC-USDC (hyphen separator)
  • HIP-3: vntl:ANTHROPIC (dex:base format)

Output Columns: ID, Type, Market, Position (size+direction), PnL. Includes a clickable trading visualization link.

9. supurr history — View Bot History

supurr history             # Show last 20 bot sessions
supurr history -n 50       # Show last 50 bot sessions

Output Columns: ID, Market, Type, PnL, Stop Reason.

10. supurr stop — Stop Bot (Signature Auth)

Signs Stop <bot-id> with your API wallet private key (EIP-191 personal_sign) and sends the signature to the bot API.

supurr stop              # Interactive - select from list
supurr stop --id 217     # Stop specific bot by ID

Crypto: Uses @noble/curves/secp256k1 + @noble/hashes/sha3 (pure JS, no native deps). Signature format: 0x{r}{s}{v} (65 bytes).

11. supurr prices — Debug Price Data

supurr prices -a BTC                     # Fetch BTC prices (7 days)
supurr prices -a hyna:BTC --dex hyna     # HIP-3 prices
supurr prices -a HYPE -s 2026-01-28      # From specific date

12. supurr update — Update All Components

supurr update    # Updates CLI, AI skill, and bot source

Runs three independent steps (one failing won't block others):

More Info

• Workflows: See → references/workflows.md
• Config storage: ~/.supurr/ contains credentials.json, configs/, and cache/
• Troubleshooting: See → references/troubleshooting.md

References

CLI & Exchange References

Strategy Authoring References

For LLMs: To build a custom trading strategy, read STRATEGY_API.md first — it has the full contract, 3-file pattern, and E2E build instructions. For indicator-based strategies (RSI, MACD, Bollinger, EMA crossover, etc.), also read indicator-strategies.md for the 3-layer pattern (BarBuilder → Indicator → Phase Machine) and the strategy-rsi reference implementation. Then use the API references below for exact signatures.

Tutorials

• Grid Bot Tutorial — Range trading with buy/sell grids
• Arb Bot Tutorial — Market-neutral spot-perp arbitrage
• DCA Bot Tutorial — Dollar-cost averaging with auto-restart
• Prediction Markets — Trade binary outcomes on testnet ⚠️
• Build Your Own Strategy — Custom strategy from scratch