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.

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

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

# Testnet (recommended first)
HYPERLIQUID_TESTNET=true
HYPERLIQUID_TESTNET_PRIVATE_KEY=0x...

# Mainnet (when ready)
# HYPERLIQUID_MAINNET_PRIVATE_KEY=0x...

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

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

Example structure in bots/*.yaml:

active: true                    # auto-select when no path arg

exchange:
  type: hyperliquid             # or "hl"
  testnet: true

account:
  max_allocation_pct: 50        # % of notional base (10_000 USD)

grid:
  symbol: BTC
  levels: 10
  price_range:
    auto:
      range_pct: 5              # ±5% around mid

risk_management:
  max_drawdown_pct: 10
  max_position_pct: 80
  rebalance_threshold_pct: 2
  # optional stop_loss_pct / take_profit_pct

monitoring:
  log_level: INFO               # DEBUG | INFO | WARNING | ERROR

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

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

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

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

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

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

Apache 2.0 — see LICENSE.