hyperliquid-grid-trading-bot

# Hyperliquid Grid Trading Bot

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

A configurable grid strategy runner for [Hyperliquid DEX](https://hyperliquid.xyz). Places layered buy/sell orders around a price range with risk controls (stop loss, take profit, drawdown limits, rebalancing). Primary implementation is **TypeScript/Node.js**; a legacy Python tree exists for reference and learning examples.

---

## Install

```bash
git clone https://github.com/PolyPulse-Analytics/hyperliquid-trading-bot.git
cd hyperliquid-trading-bot
npm install
```

**Requirements:** Node.js 20.19+, a Hyperliquid wallet private key, `git`.

Optional Python support: install [uv](https://github.com/astral-sh/uv) for legacy `src/` tree and `learning_examples/`.

---

## Environment Setup

```bash
cp .env.example .env
```

Edit `.env` — minimum required fields:

```env
# Testnet (recommended for development)
HYPERLIQUID_TESTNET_PRIVATE_KEY=0xyour_testnet_private_key_here
HYPERLIQUID_TESTNET=true

# Mainnet (real funds — use with caution)
# HYPERLIQUID_MAINNET_PRIVATE_KEY=0xyour_mainnet_private_key_here
# HYPERLIQUID_TESTNET=false
```

> **Never commit `.env` or share your private key.** Use a dedicated testnet wallet when experimenting.

---

## Key CLI Commands

| Command | Purpose |
|---------|---------|
| `npm start` | Run bot using first `active: true` config in `bots/` |
| `npm run validate` | Validate selected YAML config (no key required) |
| `npm test` | Run automated tests (grid math, etc.) |
| `npx tsc --noEmit` | TypeScript type check |
| `npx tsx ts/src/runBot.ts path/to/config.yaml` | Run with explicit config file |

```bash
# Validate before running live
npm run validate

# Start with auto-discovered active config
npm start

# Start with explicit config
npx tsx ts/src/runBot.ts bots/btc_conservative.yaml
```

---

## Bot Configuration (YAML)

Configs live in `bots/*.yaml`. Set `active: true` on exactly one file for auto-discovery.

### Full configuration reference

```yaml
# bots/my_strategy.yaml
name: "btc_grid_v1"
active: true

exchange:
  type: "hyperliquid"
  testnet: true            # Override with HYPERLIQUID_TESTNET env var

account:
  max_allocation_pct: 10.0  # Use at most 10% of account balance

grid:
  symbol: "BTC"            # Perpetual symbol on Hyperliquid
  levels: 10               # Number of grid levels (buy + sell orders)
  price_range:
    mode: "auto"           # "auto" or "manual"
    auto:
      range_pct: 5.0       # ±5% around current price
    # manual:
    #   lower: 90000
    #   upper: 100000
  order_size_usd: 50.0     # Size per grid level in USD

risk_management:
  stop_loss_enabled: false
  stop_loss_pct: 10.0       # Trigger if price drops X% below entry

  take_profit_enabled: false
  take_profit_pct: 20.0     # Trigger if profit exceeds X%

  max_drawdown_pct: 15.0    # Cancel/pause if drawdown exceeds this
  max_position_size_pct: 40.0  # Max % of allocation in open position

  rebalance:
    enabled: true
    price_move_threshold_pct: 12.0  # Rebalance grid if price moves this far

monitoring:
  log_level: "INFO"         # DEBUG | INFO | WARN | ERROR
```

### Conservative BTC example (testnet)

```yaml
# bots/btc_conservative.yaml
name: "btc_conservative"
active: true

exchange:
  type: "hyperliquid"
  testnet: true

account:
  max_allocation_pct: 5.0

grid:
  symbol: "BTC"
  levels: 8
  price_range:
    mode: "auto"
    auto:
      range_pct: 3.0
  order_size_usd: 25.0

risk_management:
  stop_loss_enabled: true
  stop_loss_pct: 8.0
  take_profit_enabled: false
  max_drawdown_pct: 10.0
  max_position_size_pct: 30.0
  rebalance:
    enabled: true
    price_move_threshold_pct: 10.0

monitoring:
  log_level: "INFO"
```

---

## Python Legacy & Learning Examples

```bash
# Sync Python dependencies
uv sync

# Validate Python bot config
uv run src/run_bot.py --validate

# Run Python bot
uv run src/run_bot.py
```

### Learning examples (educational, testnet only)

```bash
# Real-time price feed via WebSocket
uv run learning_examples/01_websockets/realtime_prices.py

# Fetch all market prices
uv run learning_examples/02_market_data/get_all_prices.py

# Place a limit order
uv run learning_examples/04_trading/place_limit_order.py
```

---

## Common Patterns

### Running multiple strategies

Only one config should have `active: true` for auto-discovery. Use explicit path to run a specific config:

```bash
# Run ETH strategy explicitly
npx tsx ts/src/runBot.ts bots/eth_aggressive.yaml

# In a separate terminal, run BTC strategy
npx tsx ts/src/runBot.ts bots/btc_conservative.yaml
```

### Switching between testnet and mainnet

```bash
# Force testnet via env (overrides YAML)
HYPERLIQUID_TESTNET=true npm start

# Mainnet — verify YAML also has testnet: false
HYPERLIQUID_TESTNET=false npx tsx ts/src/runBot.ts bots/btc_live.yaml
```

### Graceful shutdown

Press **Ctrl+C** — the engine attempts to cancel all open orders before exiting. Always check logs to confirm cancellation completed:

```bash
npm start 2>&1 | tee bot.log
# After Ctrl+C:
grep -i "cancel" bot.log
```

### Validate config without credentials

```bash
npm run validate
# or explicitly:
npx tsx ts/src/validateConfig.ts bots/my_strategy.yaml
```

---

## Grid Math Concepts

The bot divides a price range into `levels` equally spaced steps:

```
price_upper = current_price * (1 + range_pct / 100)
price_lower = current_price * (1 - range_pct / 100)
step = (price_upper - price_lower) / levels

# Buy orders placed at: price_lower, price_lower + step, ..., current_price
# Sell orders placed at: current_price, current_price + step, ..., price_upper
```

Each fill triggers the opposite order at the adjacent level, capturing the spread repeatedly.

---

## Troubleshooting

### Bot exits immediately / no orders placed
- Run `npm run validate` first — check YAML syntax errors
- Confirm `.env` has the correct private key variable for testnet vs mainnet
- Verify `HYPERLIQUID_TESTNET` matches `exchange.testnet` in YAML

### "No active config found"
- Ensure exactly one `bots/*.yaml` has `active: true`
- Or pass explicit path: `npx tsx ts/src/runBot.ts bots/myconfig.yaml`

### Orders not cancelling on shutdown
- Check logs: `grep -i "cancel\|error" bot.log`
- Manually cancel via Hyperliquid UI or API if needed
- Re-run bot briefly then Ctrl+C again

### Insufficient balance errors
- Lower `max_allocation_pct` or `order_size_usd` in YAML
- Fund testnet wallet via [testnet faucet](https://faucet.chainstack.com/hyperliquid-testnet-faucet)

### TypeScript errors
```bash
npx tsc --noEmit   # Shows all type errors without compiling
npm test           # Runs unit tests to catch logic issues
```

### Python `uv` not found
```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# or
pip install uv
```

---

## Project Structure

```
hyperliquid-trading-bot/
├── bots/                    # YAML strategy configs
│   └── btc_conservative.yaml
├── ts/src/                  # TypeScript source (primary)
│   ├── runBot.ts            # Main entrypoint
│   └── validateConfig.ts    # Config validator
├── src/                     # Python legacy bot
│   └── run_bot.py
├── learning_examples/       # Educational Python scripts
│   ├── 01_websockets/
│   ├── 02_market_data/
│   └── 04_trading/
├── .env.example             # Environment variable template
├── package.json
└── pyproject.toml           # Python deps (uv)
```

---

## Safety Checklist

- [ ] Always start on **testnet** (`HYPERLIQUID_TESTNET=true`)
- [ ] Use a **dedicated wallet** — never your main holdings wallet
- [ ] Start with **small `order_size_usd`** (e.g. $10–25)
- [ ] Enable **`max_drawdown_pct`** as a safety net
- [ ] Run `npm run validate` before every config change
- [ ] Monitor logs actively during first live run
- [ ] Keep private keys only in `.env`, never in YAML or code