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

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

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

hyperliquid-grid-trading-bot

NPX Install

Tags

SKILL.md Content

Hyperliquid Grid Trading Bot

Install

Environment Setup

Key CLI Commands

Bot Configuration (YAML)

Full configuration reference

Conservative BTC example (testnet)

Python Legacy & Learning Examples

Learning examples (educational, testnet only)

Common Patterns

Running multiple strategies

Switching between testnet and mainnet

Graceful shutdown

Validate config without credentials

Grid Math Concepts

Troubleshooting

Bot exits immediately / no orders placed

"No active config found"

Orders not cancelling on shutdown

Insufficient balance errors

TypeScript errors

Python
`uv`
not found

Project Structure

Safety Checklist