hyperliquid-grid-trading-bot

Hyperliquid Grid Trading Bot

Skill by ara.so — Daily 2026 Skills collection.

A configurable grid strategy runner for Hyperliquid DEX. 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

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 for legacy src/ tree and learning_examples/.

---

Environment Setup

cp .env.example .env

Edit .env — minimum required fields:

# 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

# 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

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

# 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

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

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

# 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

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

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

Validate config without credentials

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

TypeScript errors

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

Python uv not found

# 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