Hyperliquid Grid Trading Bot

YAML-configured grid trading for Hyperliquid perpetuals. Define your levels, price range, and risk limits in a single config file — the engine handles order placement, rebalancing, and drawdown protection.

Why Grid Trading on Hyperliquid?

Grid bots profit from range-bound volatility — buying lower, selling higher, repeatedly. Hyperliquid offers deep perp liquidity and low fees, making it a strong venue for systematic grids.

This bot stands out because:

• Config-driven — no recompiling to change symbol, levels, or risk
• Auto price range — optional % range around current mid
• Built-in risk management — drawdown limits, position caps, optional SL/TP
• Clean shutdown — SIGINT cancels open orders (positions preserved)
• Testnet first — separate keys and flag for safe experimentation

Quick Start

1. Install

git clone https://github.com/metanode-trade/hyperliquid-trading-bot.git
cd hyperliquid-trading-bot
npm install
cp .env.example .env

2. Set keys

# Testnet (recommended first)
HYPERLIQUID_TESTNET=true
HYPERLIQUIDTESTNETPRIVATE_KEY=0x...
Mainnet (when ready)
HYPERLIQUIDMAINNETPRIVATE_KEY=0x...

3. Validate config

npm run validate
npx tsx src/runBot.ts --validate bots/btc_conservative.yaml

4. Run

npx tsx src/runBot.ts bots/btc_conservative.yaml
or
npm start

Bot Configuration (YAML)

Example structure in bots/*.yaml:

active: true                    # auto-select when no path arg
exchange:   type: hyperliquid             # or "hl"   testnet: true
account:   maxallocationpct: 50        # % of notional base (10_000 USD)
grid:   symbol: BTC   levels: 10   price_range:     auto:       range_pct: 5              # ±5% around mid
risk_management:   maxdrawdownpct: 10   maxpositionpct: 80   rebalancethresholdpct: 2   # optional stoplosspct / takeprofitpct
monitoring:   log_level: INFO               # DEBUG | INFO | WARNING | ERROR

Key sections

| Section | Controls | |---------|----------| | active | Bot picked automatically when no file arg | | exchange | Venue and testnet/mainnet | | account.maxallocationpct | Sizes total_allocation vs 10k USD notional base | | grid | Symbol, level count, manual or auto price range | | risk_management | Drawdown, position %, rebalance, SL/TP | | monitoring | Log verbosity |

Environment Variables

| Variable | Scope | |----------|--------| | HYPERLIQUIDTESTNETPRIVATE_KEY | Testnet signing key | | HYPERLIQUIDMAINNETPRIVATE_KEY | Mainnet signing key | | HYPERLIQUIDPRIVATEKEY | Legacy fallback | | HYPERLIQUID_TESTNET | Overrides YAML exchange.testnet |

How the Engine Works

flowchart TB
    YAML[bot.yaml] --> Loader[Config Loader]
    Loader --> Engine[Grid Engine]
    WS[HL WebSocket allMids] --> Engine
    Engine --> Orders[Place / Cancel Grid Orders]
    Engine --> Risk[Risk Manager]
    Risk -->|drawdown breach| Orders

• Load and validate YAML
• Connect Hyperliquid adapter + WebSocket mids feed
• Compute grid levels within price range
• Place limit orders on each level
• Rebalance when price moves beyond threshold
• Enforce drawdown and position limits

Project Structure

bots/                    # YAML configs (btc_conservative.yaml, etc.)
src/
├── runBot.ts            # CLI: validate | run
├── core/
│   ├── engine.ts        # Main loop
│   ├── configLoader.ts  # YAML parsing
│   ├── keys.ts          # Env key resolution
│   └── risk.ts          # Drawdown + limits
├── strategies/grid/
│   └── basicGrid.ts     # Grid logic
└── exchanges/hyperliquid/
    ├── adapter.ts       # REST + order management
    └── websocket.ts     # allMids feed

CLI Reference

| Command | Description | |---------|-------------| | npm run validate | Validate default/active bot config | | npx tsx src/runBot.ts --validate <yaml> | Validate specific file | | npx tsx src/runBot.ts <yaml> | Run bot | | npm run typecheck | TypeScript check |

Shutdown Behavior

SIGINT (Ctrl+C) → cancels all open grid orders. Positions are NOT flattened automatically — review exposure before stopping.

Safety Checklist

• [ ] Run on testnet with fake funds first
• [ ] Keep private keys outside the repo (env only)
• [ ] Set conservative maxdrawdownpct and maxpositionpct
• [ ] Monitor logs during first live session
• [ ] Understand grid risk in trending markets (one-sided inventory)

Disclaimer

Testnet before mainnet. Keys grant full account access. Authors not liable for trading losses.

License

Apache 2.0 — see LICENSE.