supurr

Backtest, deploy, and monitor trading bots on Hyperliquid. Supports Grid, DCA, and Spot-Perp Arbitrage strategies across Native Perps, Spot markets (USDC/USDH), and HIP-3 sub-DEXes.

# Supurr CLI — Complete Command Reference

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

---

## Quick Reference

| Command                | Purpose                       |
| ---------------------- | ----------------------------- |
| `supurr init`          | Setup wallet credentials      |
| `supurr whoami`        | Show current wallet           |
| `supurr new grid`      | Generate grid strategy config |
| `supurr new arb`       | Generate spot-perp arb config |
| `supurr new dca`       | Generate DCA strategy config  |
| `supurr configs`       | List saved configs            |
| `supurr config <name>` | View config details           |
| `supurr backtest`      | Run historical simulation     |
| `supurr deploy`        | Deploy bot to production      |
| `supurr monitor`       | View active bots              |
| `supurr history`       | View historical bot sessions  |
| `supurr stop`          | Stop a running bot (signed)   |
| `supurr prices`        | Debug price data              |
| `supurr update`        | Update CLI to latest          |

---

## Global Options

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

---

## 1. `supurr init` — Credential Setup

```bash
# Interactive
supurr init

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

# Overwrite existing
supurr init --force
```

| Option                | Description                    |
| --------------------- | ------------------------------ |
| `-f, --force`         | Overwrite existing credentials |
| `--address <address>` | Wallet address (0x...)         |
| `--api-wallet <key>`  | API wallet private key         |

---

## 2. `supurr whoami` — Show Identity

```bash
supurr whoami    # Shows: Address + masked key
```

---

## 3. `supurr new <strategy>` — Config Generator

Supports three strategies: `grid`, `arb`, `dca`.

```bash
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 <symbol>`  | `BTC`         | Base asset (BTC, ETH, HYPE, etc.)              |
| `-o, --output <file>`   | `config.json` | Output filename                                |
| `--type <type>`         | `native`      | Market type: native, spot, hip3                |
| `--dex <dex>`           | —             | **Required for hip3**: hyna, xyz, km, vntl     |
| `--quote <quote>`       | —             | **Required for spot**: USDC, USDE, USDT0, USDH |
| `--mode <mode>`         | `long`        | Grid mode: long, short, neutral                |
| `--levels <n>`          | `20`          | Number of grid levels                          |
| `--start-price <price>` | —             | Grid start price                               |
| `--end-price <price>`   | —             | Grid end price                                 |
| `--investment <amount>` | `1000`        | Max investment in quote currency               |
| `--leverage <n>`        | `2`           | Leverage (1 for spot)                          |
| `--testnet`             | false         | Use Hyperliquid testnet                        |

#### Grid Examples

```bash
# 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 <symbol>` | `BTC`              | Perp asset name (BTC, ETH, HYPE, etc.)       |
| `--amount <usdc>`      | `100`              | Order amount in USDC per leg                 |
| `--leverage <n>`       | `1`                | Leverage for perp leg                        |
| `--open-spread <pct>`  | `0.003`            | Min opening spread (0.003 = 0.3%)            |
| `--close-spread <pct>` | `-0.001`           | Min closing spread (-0.001 = -0.1%)          |
| `--slippage <pct>`     | `0.001`            | Slippage buffer for both legs (0.001 = 0.1%) |
| `-o, --output <file>`  | `{asset}-arb.json` | Output filename                              |
| `--testnet`            | false              | Use Hyperliquid testnet                      |

#### Arb Examples

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

# HYPE arb with $50 per leg, 2x lever