Hyperliquid HYPE Accumulator — Spot Grid Bot

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

---

🎯 How It Works

1. You define a price range (e.g., ±3% around current price)
2. The bot builds a grid of buy/sell levels using geometric spacing
3. Buy orders are placed below the current price, sell orders above
4. On each sell, the bot keeps a percentage of HYPE (e.g., 5%) as profit
5. Rinse and repeat — the more the price oscillates, the more HYPE you accumulate

Key Features

• 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

---

🚀 Quick Start

Prerequisites

• Linux host (for gridbot-linux) or Docker
• A Hyperliquid account with USDC and/or HYPE balance

1. Clone

git clone https://github.com/catsika/Hyperliquid-Bot.git
cd Hyperliquid-Bot

2. Configure local secrets

cp .env.example .env
# Edit .env with your own wallet + key (keep this file local)

3. Apply conservative first-run settings

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

4. Run

chmod +x ./gridbot-linux
./gridbot-linux

---

🔐 Security Guidance

• 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.md for vulnerability reporting and coordinated disclosure.

🐳 Advanced: Docker Deployment

# Build
docker build -t hype-gridbot .

# Run (mount your .env file)
docker run -d --name hype-gridbot --env-file .env hype-gridbot

---

⚙️ Configuration

All settings are configured via environment variables (.env file):

API Credentials

Variable	Description
HL_ACCOUNT_ADDRESS	Your Hyperliquid wallet address
HL_PRIVATE_KEY	Your private key (never shared, stays local)

Grid Parameters

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

Risk Management

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

Timing & Display

Variable	Default	Description
MAINTENANCE_INTERVAL_SECONDS	5.0	How often to sync and maintain the grid
DEBUG_MODE	False	Show debug information

Notifications (Optional)

Variable	Default	Description
TELEGRAM_BOT_TOKEN	""	Telegram bot token for daily reports
TELEGRAM_CHAT_ID	""	Telegram chat ID for daily reports

---

🏗 Architecture

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

Data Flow

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

---

📊 Example

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

---

🧪 Running Tests

go test ./internal/... -v

---

🚀 Advanced: VPS Deployment (systemd)

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

---

⚠️ Disclaimer

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