Supurr CLI — 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

Hyperliquid spot tokens for major assets use a U-prefix naming convention:

Resolution order: try U{ASSET} first → fallback to exact name → fail if neither exists.

⚠️ U-prefix Hazard: Do NOT pass asset names that already start with U (e.g., UNIT). The CLI will prepend another U and look for UUNIT, which doesn't exist. Always use the perp ticker name (e.g., BTC, not UBTC).

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]

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.

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

8. supurr monitor — View Active Bots

Syntax

supurr monitor [options]

Options

Examples

supurr monitor                 # List all active bots
supurr monitor --watch         # Live monitoring (Ctrl+C to exit)
supurr monitor -w 0x1234...    # Filter by wallet

Output Columns:

• ID — Bot identifier
• Type — Strategy (grid, dca, mm, arb)
• Market — Trading pair (BTC-USDC, HYPE-USDH)
• Position — Size + direction (L=Long, S=Short)
• PnL — Total profit/loss

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 — Bot identifier
• Market — Trading pair (from config.markets[0])
• Type — Strategy (grid, dca, mm, arb)
• PnL — Total profit/loss (realized + unrealized)
• Stop Reason — Why the bot stopped (shutdown:graceful → "User stopped the bot Successfully")

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 — Self-Update

supurr update    # Check and install latest version

Complete Workflows

Workflow 1: Grid — Backtest → Deploy → Monitor

# 1. Initialize (first time only)
supurr init --address 0x... --api-wallet 0x...

# 2. Create config
supurr new grid --asset BTC --levels 4 --start-price 88000 --end-price 92000 --investment 100 --leverage 20 --output btc-grid.json

# 3. Backtest
supurr backtest -c btc-grid.json -s 2026-01-28 -e 2026-02-01

# 4. Deploy
supurr deploy -c btc-grid.json

# 5. Monitor
supurr monitor --watch

# 6. Stop when done
supurr stop --id <bot_id>

Workflow 2: Arb — Setup → Deploy → Monitor

# 1. Initialize
supurr init --address 0x... --api-wallet 0x...

# 2. Generate arb config (auto-resolves spot counterpart)
supurr new arb --asset BTC --amount 200 --leverage 1 --output btc-arb.json

# 3. Review the generated config
supurr config btc-arb

# 4. Ensure USDC balance in BOTH Spot and Perps wallets on Hyperliquid

# 5. Deploy
supurr deploy -c btc-arb.json

# 6. Monitor
supurr monitor --watch

Workflow 3: DCA — Configure → Deploy

# 1. Create DCA config
supurr new dca --asset BTC --trigger-price 95000 --base-order 0.001 --max-orders 5 --take-profit 0.02 --output btc-dca.json

# 2. Deploy
supurr deploy -c btc-dca.json

# 3. Monitor
supurr monitor --watch

Workflow 4: Test All Market Types

# Native Perp
supurr new grid --asset BTC --output native-btc.json
supurr backtest -c native-btc.json -s 2026-01-28 -e 2026-02-01

# USDC Spot
supurr new grid --asset HYPE --type spot --quote USDC --output hype-usdc.json
supurr backtest -c hype-usdc.json -s 2026-01-30 -e 2026-01-31

# Non-USDC Spot
supurr new grid --asset HYPE --type spot --quote USDH --output hype-usdh.json
supurr backtest -c hype-usdh.json -s 2026-01-30 -e 2026-01-31

# HIP-3
supurr new grid --asset BTC --type hip3 --dex hyna --output hyna-btc.json
supurr backtest -c hyna-btc.json -s 2026-01-28 -e 2026-02-01

Config Storage

~/.supurr/
├── credentials.json      # { address, private_key }
├── configs/              # Saved bot configs
│   ├── btc-grid.json
│   ├── hype-usdc.json
│   └── ...
└── cache/                # Price data cache
    └── hyperliquid/
        ├── BTC/
        └── HYPE/

API Endpoints Used

Troubleshooting

Appendix: Hyperliquid Info API

Backtesting note: This appendix is for live metadata and user state lookups. It is not a source of tick-level historical data for supurr backtest.

Get address via: supurr whoami — returns the configured wallet address.

All endpoints use POST https://api.hyperliquid.xyz/info with Content-Type: application/json.

Market Data (No Address Required)

User Data (Address Required)

HIP-3 Sub-DEXes

TypeScript Helper

const HL = "https://api.hyperliquid.xyz/info";

async function query<T>(body: object): Promise<T> {
  const res = await fetch(HL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  return res.json();
}

// Examples
const mids = await query({ type: "allMids" });
const positions = await query({ type: "clearinghouseState", user: "0x..." });
const spotBal = await query({ type: "spotClearinghouseState", user: "0x..." });
const dexes = await query({ type: "perpDexs" });

Common Hazards

Tutorials

Step-by-step deployment guides with parameter selection advice and practical tips:

• 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