An advanced, event-driven trading bot for the Hyperliquid exchange, written in Rust. It supports high-frequency Grid strategies for both Spot and Perpetual markets with real-time status broadcasting.

• High Performance: Built on tokio for non-blocking I/O and low latency.
• Dual Markets: Supports SpotGrid and PerpGrid (with leverage) strategies.
• Live Monitoring: Native WebSocket server broadcasts state to external UIs (Web/CLI).
• Robust Engine: Safety checks for balances, order tracking, and error handling.
• Visual Order Book: Strategies export zone data for CLOB-style visualizations.

• Architecture Design: System overview, component diagrams, and data flow.
• Spot Grid Strategy: Start here for Spot trading logic.
• Perp Grid Strategy: Advanced grid logic for Perpetuals.

• Rust (latest stable)
• A Hyperliquid Account (Mainnet or Testnet)
• A Hyperliquid Account (Mainnet or Testnet)
• Wallet Configuration File: A JSON file containing your Agent Private Key and Master Account Address.

1. Clone the repository:

   git clone https://github.com/your-username/hyperliquid-trading-bot.git
   cd hyperliquid-trading-bot

2. Build the project:

   cargo build --release

3. Configure Environment:

   a. Create a wallet_config.json file (keep this secure!):

   {
     "master_account_address": "0xMasterWalletAddress...",
     "agent_private_key": {
         "mainnet": "0xMainnetAgentPrivateKey...",
         "testnet": "0xTestnetAgentPrivateKey..."
     }
   }

   b. Create a .env file in the root directory:

   HYPERLIQUID_WALLET_CONFIG_FILE=./wallet_config.json

Run the bot using cargo run. You must specify a configuration file.

cargo run --release -- --config <PATH_TO_CONFIG> [OPTIONS]

## Deployment (Production)

For long-running production usage, we recommend using our `tmux` based deployment scripts which allow the bot to persist after you close your terminal.

See using [**Deployment Guide**](DEPLOYMENT.md) for full details.

### Quick Start
```bash
./deployment/start.sh

1. Run a Spot Grid Strategy:

cargo run --release -- --config configs/spot_grid.toml

2. Run with specific WebSocket Port: By default, the status server runs on port 9000. You can change this:

cargo run --release -- --config configs/my_perp.toml --ws-port 8080

Strategies are defined in .toml files. You can create them manually or use the interactive wizard.

The bot includes a wizard to guide you through creating a valid configuration file.

cargo run --release -- --create

Follow the on-screen prompts to select your strategy type and parameters. The file will be saved to your specified path.

Example spot_grid.toml:

[strategy]
type = "SpotGrid"
symbol = "HYPE/USDC"
upper_price = 20.0
lower_price = 10.0
grid_count = 50
total_investment = 1000.0
grid_type = "Arithmetic"
# trigger_price = 15.0 # Optional start trigger

See Spot Grid Docs for full parameter details.

The bot exposes a WebSocket feed at ws://localhost:<PORT>. New connections immediately receive the Strategy Configuration and the latest Status Summary.

Event Types:

• config: Strategy settings.
• summary: Periodic snapshots (PnL, Inventory, Zones).
• order_update: Real-time order fills/placements.
• market_update: Price ticks.

A modern React-based dashboard is included to visualize the bot's status in real-time.

1. Start the Bot (Ensure it's running and broadcasting):

   cargo run --release -- --config configs/<your_strategy>.toml

2. Start the Web Client: Open a new terminal in the frontend directory:

   cd frontend
   npm install  # First time only
   npm run dev

3. Access the Interface: Open your browser and navigate to http://localhost:5173.

You can also run the dashboard as a standalone desktop application.

Build:

cd frontend
npm run electron:build

The executable (e.g., .AppImage) will be generated in frontend/dist.

Run: Simply execute the generated binary:

./frontend/dist/hyperliquid-dashboard-0.0.0.AppImage

• Real-time PnL & Balance Tracking
• Live Grid Visualization (Order Book style)
• Active Strategy Configuration
• Connection Status Indicator

The bot can send real-time notifications to your Telegram.

1. Create a Bot: Talk to @BotFather on Telegram to create a new bot and get a Token.
2. Get Chat ID:
   • Open your new bot in Telegram.
   • Click Start or send a message (e.g., "Hello").
   • Visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in your browser.
   • Look for "chat":{"id":12345678,...} in the JSON response. This 12345678 is your TELEGRAM_CHAT_ID.
3. Update .env:

   TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
   TELEGRAM_CHAT_ID=123456789

• Notifications: The bot sends a message automatically when an order is FILLED.
• Commands: Send /status to the bot to get a current snapshot of PnL, Price, and Inventory.

MIT