Hyperliquid Grid Bot — Technical Reference

Runtime: Node.js ≥20.19. SDK: @nktkas/hyperliquid, wallet: viem, config: js-yaml, logs: pino.

Layout

bots/*.yaml          # active, exchange, grid, risk_management
src/runBot.ts        # CLI: validate | run
src/core/            # engine, config loader, keys, risk
src/exchanges/       # HL adapter + WS allMids
src/strategies/grid/ # basic grid

Keys (env)

Variable	Scope
HYPERLIQUID_TESTNET_PRIVATE_KEY	testnet 0x…
HYPERLIQUID_MAINNET_PRIVATE_KEY	mainnet
HYPERLIQUID_PRIVATE_KEY	legacy fallback
HYPERLIQUID_TESTNET	override YAML exchange.testnet

YAML sections

• active: true — auto-select when no path arg
• exchange.type: hyperliquid | hl
• account.max_allocation_pct — sizes total_allocation vs notional 10_000 USD base
• grid.levels, grid.symbol, price_range.auto.range_pct
• risk_management — drawdown, position %, rebalance threshold, optional SL/TP
• monitoring.log_level — DEBUG | INFO | WARNING | ERROR

CLI

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

Shutdown semantics

SIGINT → cancel open orders; positions not flattened automatically.

Safety

Testnet before mainnet. Keys outside repo. Authors not liable for trading losses.