hyperliquid-grid-trading-bot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hyperliquid Grid Trading Bot

Hyperliquid网格交易机器人

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.

由ara.so提供的技能 — 2026每日技能合集。

这是一个可配置的网格策略运行器，适用于Hyperliquid DEX。它会在指定价格区间内挂出分层买卖订单，并具备风险控制功能（止损、止盈、回撤限制、再平衡）。主要实现基于TypeScript/Node.js；同时提供了遗留的Python版本，用于参考和学习示例。

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/

bash

git clone https://github.com/PolyPulse-Analytics/hyperliquid-trading-bot.git
cd hyperliquid-trading-bot
npm install

要求： Node.js 20.19+、Hyperliquid钱包私钥、

git

。

可选Python支持：安装uv以使用遗留的

src/

目录和

learning_examples/

示例。

Environment Setup

环境设置

bash

cp .env.example .env

Edit

.env

— minimum required fields:

env

undefined

bash

cp .env.example .env

编辑

.env

文件 — 至少需要填写以下字段：

env

undefined

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.

---


> **绝对不要提交`.env`文件或分享你的私钥。** 实验时请使用专用的测试网钱包。

---

Key CLI Commands

关键CLI命令

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

undefined

命令	用途
`npm start`	使用 `bots/` 目录中第一个 `active: true` 的配置运行机器人
`npm run validate`	验证所选YAML配置（无需私钥）
`npm test`	运行自动化测试（网格计算等）
`npx tsc --noEmit`	TypeScript类型检查
`npx tsx ts/src/runBot.ts path/to/config.yaml`	使用指定配置文件运行机器人

bash

undefined

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

---

npx tsx ts/src/runBot.ts bots/btc_conservative.yaml

---

Bot Configuration (YAML)

机器人配置（YAML）

Configs live in

bots/*.yaml

. Set

active: true

on exactly one file for auto-discovery.

配置文件位于

bots/*.yaml

。设置

active: true

的文件只能有一个，以便自动发现。

Full configuration reference

完整配置参考

yaml

undefined

yaml

undefined

bots/my_strategy.yaml

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

undefined

exchange: type: "hyperliquid" testnet: true # 可通过HYPERLIQUID_TESTNET环境变量覆盖

account: max_allocation_pct: 10.0 # 最多使用账户余额的10%

grid: symbol: "BTC" # Hyperliquid上的永续合约标的 levels: 10 # 网格层数（买单+卖单） price_range: mode: "auto" # "auto" 或 "manual" auto: range_pct: 5.0 # 当前价格上下±5%的区间 # manual: # lower: 90000 # upper: 100000 order_size_usd: 50.0 # 每个网格层级的订单规模（美元）

risk_management: stop_loss_enabled: false stop_loss_pct: 10.0 # 当价格较入场价下跌X%时触发止损

take_profit_enabled: false take_profit_pct: 20.0 # 当利润超过X%时触发止盈

max_drawdown_pct: 15.0 # 当回撤超过此比例时，取消订单/暂停机器人 max_position_size_pct: 40.0 # 持仓占分配资金的最大比例

rebalance: enabled: true price_move_threshold_pct: 12.0 # 当价格波动超过此比例时，重新平衡网格

monitoring: log_level: "INFO" # DEBUG | INFO | WARN | ERROR

undefined

Conservative BTC example (testnet)

保守型BTC示例（测试网）

yaml

undefined

yaml

undefined

bots/btc_conservative.yaml

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"

---

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

Python遗留版本与学习示例

bash

undefined

bash

undefined

Sync Python dependencies

同步Python依赖

uv sync

Validate Python bot config

验证Python机器人配置

uv run src/run_bot.py --validate

Run Python bot

运行Python机器人

uv run src/run_bot.py

undefined

uv run src/run_bot.py

undefined

Learning examples (educational, testnet only)

学习示例（仅用于教学，仅支持测试网）

bash

undefined

bash

undefined

Real-time price feed via WebSocket

通过WebSocket获取实时价格 feed

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

---

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

undefined

自动发现模式下，只能有一个配置文件设置

active: true

。使用指定路径运行特定配置：

bash

undefined

Run ETH strategy explicitly

显式运行ETH策略

npx tsx ts/src/runBot.ts bots/eth_aggressive.yaml

In a separate terminal, run BTC strategy

在另一个终端运行BTC策略

npx tsx ts/src/runBot.ts bots/btc_conservative.yaml

undefined

npx tsx ts/src/runBot.ts bots/btc_conservative.yaml

undefined

Switching between testnet and mainnet

在测试网和主网之间切换

bash

undefined

bash

undefined

Force testnet via env (overrides YAML)

通过环境变量强制使用测试网（覆盖YAML配置）

HYPERLIQUID_TESTNET=true npm start

Mainnet — verify YAML also has testnet: false

主网 — 需确认YAML中的testnet: false也已设置

HYPERLIQUID_TESTNET=false npx tsx ts/src/runBot.ts bots/btc_live.yaml

undefined

HYPERLIQUID_TESTNET=false npx tsx ts/src/runBot.ts bots/btc_live.yaml

undefined

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

按下Ctrl+C — 引擎会尝试在退出前取消所有未成交订单。务必查看日志确认取消操作已完成：

bash

npm start 2>&1 | tee bot.log

After Ctrl+C:

按下Ctrl+C后：

grep -i "cancel" bot.log

undefined

grep -i "cancel" bot.log

undefined

Validate config without credentials

无需凭证验证配置

bash

npm run validate

bash

npm run validate

or explicitly:

或显式指定：

npx tsx ts/src/validateConfig.ts bots/my_strategy.yaml

---

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

机器人将价格区间平均划分为

levels

个等间距的步骤：

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

买单挂在：price_lower, price_lower + step, ..., current_price

Sell orders placed at: current_price, current_price + step, ..., price_upper

卖单挂在：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

先运行
```
npm run validate
```
— 检查YAML语法错误
确认
```
.env
```
文件中测试网/主网的私钥变量正确
验证
```
HYPERLIQUID_TESTNET
```
与YAML中的
```
exchange.testnet
```
设置一致

"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

确保
```
bots/*.yaml
```
中恰好有一个文件设置了
```
active: true
```

或传入指定路径：

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

查看日志：
```
grep -i "cancel\|error" bot.log
```
若需要，通过Hyperliquid UI或API手动取消订单
短暂重启机器人后再次按下Ctrl+C尝试

Insufficient balance errors

余额不足错误

Lower
```
max_allocation_pct
```
or
```
order_size_usd
```
in YAML
Fund testnet wallet via testnet faucet

在YAML中降低
```
max_allocation_pct
```
或
```
order_size_usd
```
通过测试网水龙头为测试网钱包充值

TypeScript errors

TypeScript错误

bash

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

bash

npx tsc --noEmit   # 显示所有类型错误，不进行编译
npm test           # 运行单元测试以排查逻辑问题

Python

uv

not found

Python

uv

未找到

bash

undefined

bash

undefined

Install uv

安装uv

curl -LsSf https://astral.sh/uv/install.sh | sh

or

或

pip install uv

---

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)

hyperliquid-trading-bot/
├── bots/                    # YAML策略配置文件
│   └── btc_conservative.yaml
├── ts/src/                  # TypeScript源码（主版本）
│   ├── runBot.ts            # 主入口文件
│   └── validateConfig.ts    # 配置验证器
├── src/                     # Python遗留版本机器人
│   └── run_bot.py
├── learning_examples/       # 教学用Python脚本
│   ├── 01_websockets/
│   ├── 02_market_data/
│   └── 04_trading/
├── .env.example             # 环境变量模板
├── package.json
└── pyproject.toml           # Python依赖（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_TESTNET=true
```
）
使用专用钱包 — 绝不要使用存放主要资产的钱包
初始使用较小的
order_size_usd
（例如10–25美元）
启用**
```
max_drawdown_pct
```
**作为安全保障
每次修改配置后都运行
```
npm run validate
```
首次上线运行时主动监控日志
私钥仅存放在
```
.env
```
中，绝不要写入YAML或代码