Supurr Hyperliquid Algorithmic Trading

2. supurr whoami — Show Identity

supurr whoami    # Shows: Address + masked key

3. supurr new — 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

| Type | Quote | Requires | Example | | -------- | -------- | --------- | --------------------------------------- | | native | USDC | — | --asset BTC | | spot | Variable | --quote | --asset HYPE --type spot --quote USDC | | hip3 | Per-DEX | --dex | --asset BTC --type hip3 --dex hyna |

#### Grid Options

| Option | Default | Description | | ----------------------- | ------------- | ---------------------------------------------- | | -a, --asset | BTC | Base asset (BTC, ETH, HYPE, etc.) | | -o, --output | config.json | Output filename | | --type | native | Market type: native, spot, hip3 | | --dex | — | Required for hip3: hyna, xyz, km, vntl | | --quote | — | Required for spot: USDC, USDE, USDT0, USDH | | --mode | long | Grid mode: long, short, neutral | | --levels | 20 | Number of grid levels | | --start-price | — | Grid start price | | --end-price | — | Grid end price | | --investment | 1000 | Max investment in quote currency | | --leverage | 2 | Leverage (1 for spot) | | --testnet | false | Use Hyperliquid testnet |

#### 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

| DEX | Quote | Assets | | ------ | ----- | ----------------------------------- | | hyna | USDE | Crypto perps (BTC, ETH, HYPE, etc.) | | xyz | USDE | Stocks (AAPL, TSLA, etc.) | | km | USDT | Kinetiq Markets | | vntl | USDE | AI/tech tokens |

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:

| You pass --asset | CLI resolves spot token | Spot pair | Perp pair | | ------------------ | ----------------------- | ---------- | ---------- | | BTC | UBTC | UBTC/USDC | BTC perp | | ETH | UETH | UETH/USDC | ETH perp | | SOL | USOL | USOL/USDC | SOL perp | | ENA | UENA | UENA/USDC | ENA perp | | WLD | UWLD | UWLD/USDC | WLD perp | | MON | UMON | UMON/USDC | MON perp | | MEGA | UMEGA | UMEGA/USDC | MEGA perp | | ZEC | UZEC | UZEC/USDC | ZEC perp | | XPL | UXPL | UXPL/USDC | XPL perp | | PUMP | UPUMP | UPUMP/USDC | PUMP perp | | HYPE | HYPE (exact name) | HYPE/USDC | HYPE perp | | TRUMP | TRUMP (exact name) | TRUMP/USDC | TRUMP perp | | PURR | PURR (exact name) | PURR/USDC | PURR perp | | BERA | BERA (exact name) | BERA/USDC | BERA perp |

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

| Option | Default | Description | | ---------------------- | ------------------ | -------------------------------------------- | | -a, --asset | BTC | Perp asset name (BTC, ETH, HYPE, etc.) | | --amount | 100 | Order amount in USDC per leg | | --leverage | 1 | Leverage for perp leg | | --open-spread | 0.003 | Min opening spread (0.003 = 0.3%) | | --close-spread | -0.001 | Min closing spread (-0.001 = -0.1%) | | --slippage | 0.001 | Slippage buffer for both legs (0.001 = 0.1%) | | -o, --output | {asset}-arb.json | Output filename | | --testnet | false | Use Hyperliquid testnet |

#### 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

| Option | Default | Description | | ---------------------------- | ------------- | -------------------------------------------------- | | -a, --asset | BTC | Base asset | | --mode | long | Direction: long or short | | --type | native | Market type: native, spot, hip3 | | --trigger-price | 100000 | Price to trigger base order | | --base-order | 0.001 | Base order size in base asset | | --dca-order | 0.001 | DCA order size in base asset | | --max-orders | 5 | Max number of DCA orders | | --size-multiplier | 2.0 | Size multiplier per DCA step | | --deviation | 0.01 | Price deviation % to trigger first DCA (0.01 = 1%) | | --deviation-multiplier | 1.0 | Deviation multiplier for subsequent steps | | --take-profit | 0.02 | Take profit % from avg entry (0.02 = 2%) | | --stop-loss | — | Optional stop loss as absolute PnL threshold | | --leverage | 2 | Leverage (1 for spot) | | --restart | false | Restart cycle after take profit | | --cooldown | 60 | Cooldown between cycles in seconds | | -o, --output | config.json | Output filename | | --testnet | false | Use Hyperliquid testnet |

#### 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 — 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  [options]

Options

| Option | Description | | --------------------- | ---------------------------------------- | | -c, --config | Required. Config file (name or path) | | -s, --start | Start date (YYYY-MM-DD) | | -e, --end | End date (YYYY-MM-DD) | | -p, --prices | Use local prices file | | -o, --output | Save results to JSON | | --no-cache | Disable price caching |

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

| Dex | Asset Format | Example | | ------------- | ---------------------- | ------------------ | | hyperliquid | BTC, HYPE | Native perp + Spot | | hyna | hyna:BTC, hyna:ETH | HIP-3 DEX |

> 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  [-s 
 | -v 
]

| Option | Description | | ---------------------------- | ------------------------------------------------------- | | -c, --config | Required. Config file (name or path) | | -s, --subaccount

# 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

✔ 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

supurr monitor [options]

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

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

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

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

supurr update    # Check and install latest version

# 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 

# 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

# 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

# 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

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

const HL = "https://api.hyperliquid.xyz/info";
async function query(body: object): Promise {
  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" });