Novaquant-labs/hyperliquid-trading-bot
hyperliquid trading bot, perp trading bot, hyperliquid profitable trading bot, hyperliquid trading bot, perp trading bot, hyperliquid profitable trading bot, hyperliquid trading bot, perp trading bot, hyperliquid profitable trading bot, hyperliquid trading bot, perp trading bot, hyperliquid profitable trading bot,
项目说明
🤖 Hyperliquid Grid Trading Bot
An intelligent grid trading strategy runner for Hyperliquid — automate layered orders with built-in risk management.
🎯 What This Bot Does
This bot automatically places layered buy and sell orders around your target price range on Hyperliquid. Think of it as a smart assistant that:
✅ Places multiple orders at different price levels (your "grid")
✅ Automatically rebalances when the market moves
✅ Protects your capital with stop-loss, take-profit, and drawdown limits
✅ Logs everything for transparency and debugging
✅ Runs 24/7 on testnet or mainnet (your choice)
Perfect for: Volatile markets, range-bound trading, automated income generation, and hands-off position management.
⚠️ Risk Warning
Trading derivatives is risky. You can lose your entire investment. This bot is for education and research only.
🔴 Before you start:
- Start on testnet with fake funds
- Keep position sizes small while learning
- Always understand the strategy before running it
- Never share your private keys or
.envfile - Read
bots/btc_conservative.yamlto understand risk settings
The authors provide no financial or legal advice. You are fully responsible for your trading decisions.
📋 Prerequisites
You'll need just three things:
| What | Why | Link |
|---|---|---|
| Node.js 20.19+ | Runs the bot engine | Download Node.js |
| Hyperliquid Wallet | Holds your trading funds | Create wallet |
| Git | Clones this repository | Get Git |
Optional: uv if you want to play with Python learning examples.
🚀 Quick Start (5 Minutes)
Step 1: Clone the Repository
git clone https://github.com/Novaquant-labs/hyperliquid-trading-bot.git
cd hyperliquid-trading-bot
npm install
Step 2: Set Up Your Environment
cp .env.example .env
Then edit .env and add your wallet's private key:
For testnet (recommended first):
HYPERLIQUID_TESTNET=true
HYPERLIQUID_TESTNET_PRIVATE_KEY=your_testnet_private_key_here
For mainnet (real money):
HYPERLIQUID_TESTNET=false
HYPERLIQUID_MAINNET_PRIVATE_KEY=your_mainnet_private_key_here
🔒 Never commit
.envto Git. It's already in.gitignore— keep it that way.
Step 3: Configure Your Strategy
The bot comes with a sample config: bots/btc_conservative.yaml
To use it, make sure it has active: true:
name: "my_first_grid"
active: true # ← Set this to true
exchange:
type: "hyperliquid"
testnet: true # Change to false for mainnet
account:
max_allocation_pct: 10.0 # Risk only 10% of your account
grid:
symbol: "BTC"
levels: 10 # 10 buy/sell orders per side
price_range:
mode: "auto"
auto:
range_pct: 5.0 # Grid spans ±5% around current price
Step 4: Validate & Run
npm run validate # Quick check for config errors
npm start # 🤖 Bot is now trading!
Press Ctrl+C to stop. The bot will cancel all open orders.
📖 Understanding Your Configuration
All bot settings live in one YAML file under bots/.
Basic Structure
name: "my_bot_name" # What to call this strategy
active: true # true = bot will auto-start, false = skip
exchange:
type: "hyperliquid" # Only option for now
testnet: true # true = testnet, false = mainnet
account:
max_allocation_pct: 10.0 # Max % of wallet to use (safety limit)
grid:
symbol: "BTC" # Trading pair: BTC, ETH, SOL, etc.
levels: 10 # Number of orders on each side
price_range:
mode: "auto" # Can be "auto" or "manual"
auto:
range_pct: 5.0 # Grid covers ±5% from current price
risk_management:
stop_loss_enabled: false
stop_loss_pct: 10.0
take_profit_enabled: false
take_profit_pct: 20.0
max_drawdown_pct: 15.0 # Pause if down 15%
rebalance:
price_move_threshold_pct: 12.0
monitoring:
log_level: "INFO" # INFO, DEBUG, WARN, ERROR
Key Settings Explained
grid.levels — How many buy orders below and sell orders above your center price
→ More levels = thinner spreads, more orders to manage
price_range.auto.range_pct — How wide your grid spans
→ 5% = grid from -5% to +5% of current price
max_allocation_pct — % of your wallet the bot can use
→ 10% = max risk is 10% of your total funds
max_drawdown_pct — Bot pauses if losses hit this threshold
→ 15% = shut down if down $15 per $100 in the account
🎓 Common Configurations
🛡️ Conservative (Low Risk, Slow Profit)
grid:
levels: 15
price_range:
auto:
range_pct: 2.0
account:
max_allocation_pct: 5.0
risk_management:
max_drawdown_pct: 10.0
⚡ Aggressive (Higher Risk, Faster Profit)
grid:
levels: 5
price_range:
auto:
range_pct: 10.0
account:
max_allocation_pct: 25.0
risk_management:
max_drawdown_pct: 25.0
💰 Balanced (Medium Risk)
grid:
levels: 10
price_range:
auto:
range_pct: 5.0
account:
max_allocation_pct: 15.0
risk_management:
max_drawdown_pct: 15.0
🛠️ Commands & Tools
| Command | What It Does |
|---|---|
npm start | Run bot with first active config |
npm run validate | Check config syntax (no keys needed) |
npx tsx ts/src/runBot.ts bots/my_config.yaml | Run specific config |
npm test | Run automated tests |
npm run debug | Start with verbose logging |
🔄 How It Works (Under the Hood)
┌─────────────────────────────────────────────────────┐
│ 1. Bot Starts │
│ Reads your .env (private key) + YAML config │
└──────────────────┬──────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ 2. Places Grid Orders │
│ Puts buy orders below + sell orders above │
│ e.g., BTC at $43k, $42.9k, $42.8k (buy side) │
│ $44k, $44.1k, $44.2k (sell side) │
└──────────────────┬──────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ 3. Monitor & Manage │
│ Watch for fills, check risk limits, rebalance │
│ Logs every action for transparency │
└──────────────────┬──────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ 4. Loop Until Stopped │
│ Repeat every few seconds (configurable) │
└─────────────────────────────────────────────────────┘
📊 Real Example Walkthrough
Let's say BTC is trading at $43,000:
Your Config:
levels: 5(5 buy, 5 sell orders)range_pct: 4.0(±4% = $41,280 to $44,720)
Bot Creates This Grid:
SELL Orders (Above Price) BUY Orders (Below Price)
───────────────────────── ──────────────────────
Limit $44,720 (±4%) Limit $41,280 (±4%)
Limit $44,344 Limit $41,656
Limit $43,968 (←Mid) Limit $42,032 (←Mid)
Limit $43,592 Limit $42,408
Limit $43,216 Limit $42,784
When price rises to $44,000 → sells execute → profit locked.
When price drops to $42,000 → buys execute → averaging down.
Rinse and repeat.
🐍 Python Examples (Educational)
Want to learn the API? Check out the learning examples:
# Install Python deps
uv sync
# Run examples
uv run learning_examples/01_websockets/realtime_prices.py
uv run learning_examples/02_market_data/get_all_prices.py
uv run learning_examples/04_trading/place_limit_order.py
Also see the legacy Python bot:
uv run src/run_bot.py --validate
uv run src/run_bot.py
❓ FAQ
Q: Can I run multiple bots at once?
A: Not in auto-discovery mode (only one active: true). To run multiple, launch them separately with explicit config paths:
npx tsx ts/src/runBot.ts bots/btc_grid.yaml &
npx tsx ts/src/runBot.ts bots/eth_grid.yaml &
Q: What's the minimum position size?
A: Depends on Hyperliquid's rules. Start with the testnet to find out—no real money lost if wrong.
Q: Does the bot work 24/7?
A: Yes, as long as your server/machine stays on. Consider cloud hosting (AWS, DigitalOcean) for always-on trading.
Q: How often does it check & rebalance?
A: Every few seconds (configurable). Check logs to see the exact interval.
Q: Can I edit the config while the bot is running?
A: No. Stop the bot (Ctrl+C), edit the YAML, then restart.
Q: What if my key is exposed?
A: Immediately revoke it in your Hyperliquid wallet settings and generate a new one. Never re-use a compromised key.
🐛 Troubleshooting
Bot won't start
npm run validate
# Check for YAML syntax errors
# Verify .env file exists and has HYPERLIQUID_TESTNET_PRIVATE_KEY
Orders aren't filling
- Check market liquidity (sparse market = wider spreads needed)
- Verify
price_range.range_pctis wide enough - Ensure your account has enough collateral
- Look at logs:
npm run debug
"Invalid private key" error
- Double-check
.envfor typos - Verify you're using the correct key for testnet/mainnet
- Make sure the key is hex-encoded (no spaces)
Bot stops unexpectedly
- Check logs for error messages
- Verify your API rate limits aren't exceeded
- Ensure the bot account still has collateral
High slippage / orders not optimal
- Reduce
grid.levels(fewer, thicker orders) - Increase
price_range.range_pct(wider bands) - Trade more liquid pairs (BTC, ETH)
💡 Tips for Success
✅ Start small — Test on testnet with tiny amounts first
✅ Log everything — Keep detailed records of all trades
✅ Monitor trends — Grids work best in range-bound markets
✅ Set realistic limits — 15% drawdown > 5% of actual risk
✅ Adjust gradually — Change one setting at a time
✅ Read the docs — Hyperliquid has nuances; understand them
✅ Use alerts — Set up bot notifications (email, Telegram, Discord)
🔧 Advanced: Custom Configs
Need more control? Edit bots/your_config.yaml with all available options:
grid:
price_range:
mode: "manual" # Instead of auto
manual:
lower_bound: 40000
upper_bound: 50000
risk_management:
stop_loss_enabled: true
stop_loss_pct: 8.0
take_profit_enabled: true
take_profit_pct: 15.0
max_position_size_pct: 40.0
rebalance:
enabled: true
price_move_threshold_pct: 12.0
monitoring:
log_level: "DEBUG" # Verbose logging
📚 Development & Contributing
Local Development
# Typecheck
npx tsc --noEmit
# Run tests
npm test
# Run with debug logging
npm run debug
Contributing
See AGENTS.md / CLAUDE.md for code style and conventions.
Publishing (Maintainers)
Use scripts/publish-to-polypulse.ps1 to push to GitHub (requires GITHUB_TOKEN).
⚖️ License & Disclaimer
This software is provided "as is," without any warranty. You are fully responsible for:
- Securing your private keys and API credentials
- Compliance with exchange rules and local laws
- Any financial losses from using this bot
- Ensuring your strategy aligns with your risk tolerance
Read the full license in the repository.
🤝 Get Help
- 📖 Docs: Check
README.mdandbots/btc_conservative.yaml - 🐛 Issues: Report bugs on GitHub Issues
- 💬 Discussions: Join the community for questions
- 📧 Security: Report vulnerabilities privately to maintainers
🎉 Next Steps
- Clone the repo →
git clone ... - Set up
.env→ Add your testnet key - Run on testnet →
npm start - Monitor logs → Verify orders are placed correctly
- Tweak the config → Experiment with different settings
- Graduate to mainnet (optional) → When confident, switch to real funds
Happy trading! 🚀
Last Updated: May 2026 | Maintained by Novaquant-labs
