A high-performance spot grid trading bot written in Go, designed to accumulate HYPE on the Hyperliquid DEX. Features a rich terminal dashboard, WebSocket-driven fill detection, geometric grid spacing, and automatic risk management.
Warning
Trading risk disclaimer: this bot places real orders with real funds. Crypto markets are volatile and you can lose capital quickly. Use this software at your own risk.
Safe first run: start with small capital, low leverage/no leverage, conservative grid settings, and monitor closely before scaling up.
Important
Security first: never commit .env, private keys, wallet secrets, or exchange credentials to git. Keep secrets local, and immediately rotate/revoke any key that was exposed or committed (even briefly).
- You define a price range (e.g., ±3% around current price)
- The bot builds a grid of buy/sell levels using geometric spacing
- Buy orders are placed below the current price, sell orders above
- On each sell, the bot keeps a percentage of HYPE (e.g., 5%) as profit
- Rinse and repeat — the more the price oscillates, the more HYPE you accumulate
- Geometric grid spacing — Equal percentage gaps between levels (better than linear for volatile assets)
- Near-price weighting — Concentrates more capital near the current price for higher fill rates
- Auto-recentering — Grid automatically rebuilds when price drifts too far from center
- WebSocket fills — Instant fill detection via WS, with REST sync as safety net
- Heartbeat monitoring — Detects stale WS connections and auto-reconnects
- Fee tracking — Accurate P&L accounting including trading fees
- Telegram notifications — Daily accumulation reports sent to your phone
- Terminal dashboard — Real-time TUI with grid visualization, P&L, and trade history
- Headless mode — Perfect for VPS/Docker deployment
- Graceful shutdown — Cancels all orders on Ctrl+C
- Linux host (for
gridbot-linux) or Docker - A Hyperliquid account with USDC and/or HYPE balance
git clone https://github.com/catsika/Hyperliquid-Bot.git
cd Hyperliquid-Botcp .env.example .env
# Edit .env with your own wallet + key (keep this file local)Start small and tighten risk controls before live scaling. Example:
CAPITAL_ALLOCATION=0.10
INITIAL_DEPLOY_PCT=0.20
GRID_LEVELS=6
MAX_DRAWDOWN_PCT=0.05chmod +x ./gridbot-linux
./gridbot-linux- Never paste private keys into chats, issues, screenshots, or logs.
- Never commit secrets to git history (
.env, key files, exported account dumps). - Use dedicated API/wallet credentials with least privilege where possible.
- If a key is ever exposed or committed, treat it as compromised: rotate immediately.
- Review
SECURITY.mdfor vulnerability reporting and coordinated disclosure.
# Build
docker build -t hype-gridbot .
# Run (mount your .env file)
docker run -d --name hype-gridbot --env-file .env hype-gridbotAll settings are configured via environment variables (.env file):
| Variable | Description |
|---|---|
HL_ACCOUNT_ADDRESS |
Your Hyperliquid wallet address |
HL_PRIVATE_KEY |
Your private key (never shared, stays local) |
| Variable | Default | Description |
|---|---|---|
GRID_LEVELS |
30 |
Number of grid levels (20-50 recommended) |
GRID_RANGE_PCT |
0.03 |
Grid range as % of spot price (0.03 = ±1.5%) |
SELL_BACK_PCT |
0.95 |
Sell back 95%, keep 5% HYPE per round-trip |
CAPITAL_ALLOCATION |
0.95 |
% of USDC to deploy in the grid |
NEAR_PRICE_WEIGHT |
2.0 |
Weight multiplier for levels near spot (1.0 = uniform) |
RECENTER_THRESHOLD_PCT |
0.6 |
Auto-recenter when price exits 60% of range |
| Variable | Default | Description |
|---|---|---|
STOP_LOSS_PRICE |
0.0 |
Hard stop-loss price (0 = disabled) |
MAX_DRAWDOWN_PCT |
0.10 |
Max 10% drawdown from peak equity triggers emergency sell |
MIN_ORDER_SIZE_USD |
5.0 |
Minimum order size in USD |
| Variable | Default | Description |
|---|---|---|
MAINTENANCE_INTERVAL_SECONDS |
5.0 |
How often to sync and maintain the grid |
DEBUG_MODE |
False |
Show debug information |
| Variable | Default | Description |
|---|---|---|
TELEGRAM_BOT_TOKEN |
"" |
Telegram bot token for daily reports |
TELEGRAM_CHAT_ID |
"" |
Telegram chat ID for daily reports |
gridbot-linux # Prebuilt Linux binary
internal/
├── config/config.go # Configuration loading & validation
├── exchange/
│ ├── client.go # Hyperliquid REST API wrapper
│ ├── websocket.go # WebSocket client with heartbeat monitoring
│ └── types.go # Shared types
├── grid/
│ ├── engine.go # Core grid logic (build, place, fill, recenter)
│ ├── engine_test.go # Unit tests
│ └── risk.go # Risk management (stop-loss, max drawdown)
├── accounting/
│ └── tracker.go # P&L, fee tracking, HYPE accumulation stats
├── tui/
│ └── dashboard.go # Terminal UI rendering
└── notifier/
└── notifier.go # Telegram notification sender
WebSocket ──→ Fill Events ──→ Engine.HandleFill() ──→ Counter Orders
──→ Price Updates ──→ Engine.UpdatePrice()
Maintenance Ticker ──→ Engine.Maintain()
├── updateAccountData()
├── syncOrders() (REST safety net)
├── checkRisk()
├── auto-recenter (if needed)
└── fillGridGaps()
With default settings (GRID_LEVELS=30, GRID_RANGE_PCT=0.03, SELL_BACK_PCT=0.95):
- If HYPE is at $25.00, the grid spans $24.625 — $25.375
- 30 levels with geometric spacing (~0.1% between each)
- More capital concentrated near $25.00 (2x weight)
- Each round-trip (buy → sell) keeps 5% of the HYPE
- If price oscillates 10 times through a level: ~0.5 HYPE accumulated from that level alone
go test ./internal/... -v# Copy gridbot.service to systemd
sudo cp gridbot.service /etc/systemd/system/
sudo systemctl enable gridbot
sudo systemctl start gridbot
# Check logs
sudo journalctl -u gridbot -fThis bot is for educational purposes. Trading crypto involves significant risk. Grid bots perform best in ranging/sideways markets — strong trends can lead to losses. Only trade with funds you can afford to lose. The authors are not responsible for any financial losses.