Hyperliquid AI Trading Bot — User Guide

Prerequisites
Installation
Configuration
- Environment Variables (.env)
- YAML Config (config/default.yaml)
CLI Commands
Trading Modes
Wallet Setup & Testnet
Dynamic Coin Scanner
Profit Target
Testing Workflow
Configuration Reference
Monitoring & Alerts
Troubleshooting

Prerequisites

Python 3.12+
A Hyperliquid wallet (for live/testnet trading)
Anthropic API key (for Claude AI analysis)

Installation

# Clone and enter the project
cd hyperliquid

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment with Python 3.12 and install dependencies
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[dev]"

# For backtesting support
uv pip install -e ".[backtest]"

# For Discord/Telegram alerts
uv pip install -e ".[alerts]"

# Install everything
uv pip install -e ".[dev,backtest,alerts]"

Configuration

Environment Variables

Copy the example file and fill in your keys:

cp .env.example .env

Edit .env:

# Required for live trading (not needed for paper mode with testnet data)
HYPERLIQUID_PRIVATE_KEY=0x_your_private_key_here
HYPERLIQUID_WALLET_ADDRESS=0x_your_wallet_address_here

# Network selection
HYPERLIQUID_TESTNET=true          # true = testnet, false = mainnet

# Required for AI analysis
ANTHROPIC_API_KEY=sk-ant-your-key-here

# Optional: Alert webhooks
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id

Variable	Required	Description
`HYPERLIQUID_PRIVATE_KEY`	For live trading	Your wallet private key (never share this)
`HYPERLIQUID_WALLET_ADDRESS`	For live trading	Your wallet address (0x...)
`HYPERLIQUID_TESTNET`	No (default: true)	`true` for testnet, `false` for mainnet
`ANTHROPIC_API_KEY`	For AI analysis	Claude API key from console.anthropic.com
`DISCORD_WEBHOOK_URL`	No	Discord webhook for alerts
`TELEGRAM_BOT_TOKEN`	No	Telegram bot token for alerts
`TELEGRAM_CHAT_ID`	No	Telegram chat ID for alerts

YAML Configuration

The main config file is config/default.yaml. You can create custom config files and pass them via --config.

# Use default config
python3 -m src.main

# Use custom config
python3 -m src.main --config config/aggressive.yaml

CLI Commands

`hypertrade` — Interactive Launcher

The main way to use the bot. Run with no arguments for an interactive menu:

source .venv/bin/activate
hypertrade

This shows a menu with all options: Demo, Paper Trading, Live Trading, Settings, Check Connection, Fetch Data, Run Backtest.

Direct commands (skip the menu):

hypertrade demo                # Demo mode, no keys needed
hypertrade check               # Test exchange connection
hypertrade fetch               # Fetch historical data (interactive)
hypertrade fetch --coins BTC ETH --days 90 --interval 1h   # Non-interactive
hypertrade backtest            # Run backtest (interactive)
hypertrade start               # Same as running with no args

What the menu does for each option:

Option	What it asks	What it launches
Demo Mode	Nothing	TUI with simulated data
Paper Trading	Coins, network (mainnet/testnet)	TUI with real prices, fake trades
Live Trading	Coins, network, confirmation	TUI with real orders
Settings	Nothing	TUI in demo mode (press `m` to open settings)
Check Connection	Nothing	Runs connection test
Fetch Data	Coins, interval, days	Downloads candles to data/candles/
Run Backtest	Coin, interval, days	Runs strategy backtest, prints results

Running the Bot (Advanced)

You can also run the bot directly without the interactive launcher:

# Activate the virtual environment first
source .venv/bin/activate

Basic usage:

python3 -m src.main [OPTIONS]

Options:

Flag	Values	Default	Description
`--config`	file path	`config/default.yaml`	Path to YAML config file
`--mode`	`paper`, `live`	from config (`paper`)	Trading mode
`--coins`	space-separated list	from config (`BTC ETH`)	Coins to trade
`--log-level`	`DEBUG`, `INFO`, `WARNING`, `ERROR`	from config (`INFO`)	Log verbosity

Examples:

# Paper trading BTC and ETH on testnet (default)
python3 -m src.main

# Paper trading with debug logging
python3 -m src.main --log-level DEBUG

# Paper trading only SOL and DOGE
python3 -m src.main --coins SOL DOGE

# Paper trading with custom config
python3 -m src.main --config config/conservative.yaml

# Live trading on testnet (requires wallet keys in .env)
python3 -m src.main --mode live

# Live trading specific coins with verbose logging
python3 -m src.main --mode live --coins BTC --log-level DEBUG

# Combine multiple overrides
python3 -m src.main --mode paper --coins BTC ETH SOL --log-level INFO

Stopping the bot:

Press Ctrl+C for graceful shutdown. The bot will:

Cancel all open orders
Stop WebSocket feeds
Flush logs and save metrics
Exit cleanly

TUI Dashboard

The bot includes a full terminal UI with live-updating panels for prices, positions, indicators, signals, AI decisions, and stats.

python3 -m src.tui.app [OPTIONS]

Options:

Flag	Values	Default	Description
`--demo`	flag	off	Run with simulated data (no exchange needed)
`--config`	file path	none	Config file to run real bot with TUI
`--mode`	`paper`, `live`	from config	Override trading mode
`--coins`	space-separated list	from config	Override coins

Examples:

# Demo mode — see the TUI with fake data, no keys needed
python3 -m src.tui.app --demo

# Paper trading with TUI
python3 -m src.tui.app --config config/default.yaml

# Live trading with TUI
python3 -m src.tui.app --config config/default.yaml --mode live

# Custom coins
python3 -m src.tui.app --config config/default.yaml --coins BTC SOL

Keyboard Shortcuts:

Key	Action
`q`	Quit the dashboard
`m`	Open Settings menu (mode, credentials, risk, AI config)
`p`	Pause / Resume data refresh
`l`	Focus the activity log (scroll with arrows)
`d`	Toggle debug mode
`c`	Close all open positions (emergency)
`r`	Reset circuit breaker

Dashboard Layout:

┌─────────────────────────────────────────────────────────────┐
│  HYPERLIQUID AI BOT          [PAPER] [TESTNET]     HH:MM:SS│
├───────────────────┬───────────────────┬─────────────────────┤
│ PRICES & MARKET   │ OPEN POSITIONS    │ TECHNICAL INDICATORS│
│                   │                   │                     │
│ BTC  $68,234  +1% │ BTC LONG 0.05    │ RSI  MACD  ADX  BB │
│ ETH   $3,456  -1% │ ETH SHORT 2.0    │ 67   +50   32  0.6 │
│ SOL     $178  +3% │                   │ 72   -30   18  0.8 │
├───────────────────┼───────────────────┼─────────────────────┤
│ SIGNALS           │ AI DECISIONS      │ BOT STATS           │
│                   │                   │                     │
│ BTC LONG  str=0.7 │ BTC BUY conf=85% │ Equity:  $10,536    │
│ ETH SHORT str=0.6 │ ETH HOLD conf=40%│ PnL:       +$536    │
│                   │                   │ Win Rate:    62.5%  │
├───────────────────┴───────────────────┴─────────────────────┤
│ ACTIVITY LOG                                                │
│ 14:32:05 SIGNAL BTC LONG strength=0.72                      │
│ 14:32:15 AI     BTC -> BUY conf=85% $0.0012                │
│ 14:32:16 TRADE  ORDER BUY BTC size=0.02 @ $68,234          │
└─────────────────────────────────────────────────────────────┘

Panel descriptions:

Panel	Content
Prices & Market	Live prices, % change, volume ratio, funding rate per coin
Open Positions	Current positions with side, size, entry, PnL, leverage
Technical Indicators	RSI, MACD histogram, ADX, Bollinger Band position, EMA trend
Signals	Recent signals with direction, strength bar, sources, AI escalation
AI Decisions	Claude responses with action, confidence, model, cost, cache status
Bot Stats	Equity, PnL, win rate, trades, fees, AI costs, circuit breaker
Activity Log	Scrollable log of all events color-coded by type

Settings Screen (press m):

Press m from the dashboard to open the settings modal with 3 tabs:

Tab	Settings
Mode & Keys	Paper/Live toggle, Testnet toggle, wallet private key, wallet address, Anthropic API key, webhook URL
Trading & Risk	Coins, auto-select coins toggle, auto-select top N, leverage, leverage mode, strategy, candle interval, max position %, max open positions, daily loss limit, max drawdown, stop loss %, take profit %, profit target %
AI Config	Routine interval, daily cost cap, cache TTL, routine model, major model, log level

Three action buttons at the bottom:

Save to Disk — validates, writes to config/default.yaml and .env, then closes
Apply Runtime — validates and applies to the running bot without saving to disk
Cancel / Escape — closes without changes

Credentials (private key, API key) are masked on display and only written to .env when changed.

Check Connection

Verify that the Hyperliquid SDK can connect and fetch data:

python3 scripts/check_connection.py

This runs 5 checks:

Fetch all mid prices
Get exchange metadata (available assets)
Get BTC L2 orderbook
Fetch BTC 1h candles (last 24 hours)
Check wallet state (if HYPERLIQUID_WALLET_ADDRESS is set)

Fetch Historical Data

Download historical candle data for backtesting:

python3 scripts/fetch_historical.py [OPTIONS]

Options:

Flag	Values	Default	Description
`--coins`	space-separated list	`BTC ETH`	Coins to fetch
`--interval`	`1m`, `5m`, `15m`, `1h`, `4h`, `1d`	`1h`	Candle interval
`--days`	integer	`90`	Days of history to fetch
`--testnet`	flag	off (uses mainnet)	Fetch from testnet instead

Examples:

# Fetch 90 days of 1h candles for BTC and ETH
python3 scripts/fetch_historical.py

# Fetch 180 days of 15-minute candles for BTC
python3 scripts/fetch_historical.py --coins BTC --interval 15m --days 180

# Fetch data for multiple coins
python3 scripts/fetch_historical.py --coins BTC ETH SOL DOGE --days 60

# Fetch 1-minute candles (large dataset)
python3 scripts/fetch_historical.py --coins BTC --interval 1m --days 30

Data is cached as Parquet files in data/candles/ (e.g., BTC_1h_90d.parquet). Re-running the same command uses the cache; delete the file to re-fetch.

Run Backtests

After fetching historical data, run backtests in a Python script or shell:

# backtest_example.py
from backtest.data_loader import fetch_candles
from backtest.runner import run_backtest
from backtest.strategies.bt_momentum import MomentumStrategy

# Load data (uses cache if available)
df = fetch_candles("BTC", interval="1h", days=90)

# Run backtest
results = run_backtest(
    df,
    MomentumStrategy,
    cash=10000,           # Starting capital ($)
    commission=0.00045,   # Taker fee (0.045%)
    margin=1/3,           # 3x leverage (margin = 1/leverage)
)

print(f"Return: {results['return_pct']:.2f}%")
print(f"Sharpe: {results['sharpe_ratio']:.2f}")
print(f"Max Drawdown: {results['max_drawdown_pct']:.2f}%")
print(f"Win Rate: {results['win_rate_pct']:.1f}%")
print(f"Total Trades: {results['total_trades']}")
print(f"Report: {results['report_path']}")

Or as a one-liner:

python3 -c "
from backtest.data_loader import fetch_candles
from backtest.runner import run_backtest
from backtest.strategies.bt_momentum import MomentumStrategy
results = run_backtest(fetch_candles('BTC', '1h', 90), MomentumStrategy)
print(results)
"

The HTML report is saved to data/backtest_MomentumStrategy.html.

Trading Modes

The bot has two independent toggles that combine into four modes:

`exchange.mode`	`exchange.testnet`	What Happens
`paper`	`true`	Simulated trades, testnet data. Start here.
`paper`	`false`	Simulated trades, real mainnet prices. Safe practice.
`live`	`true`	Real orders on Hyperliquid testnet. Needs testnet USDC.
`live`	`false`	Real money on mainnet. Requires explicit "YES" confirmation.

How to switch

Via config file (config/default.yaml):

exchange:
  mode: paper    # paper | live
  testnet: true  # true | false

Via environment (.env):

HYPERLIQUID_TESTNET=false   # switch to mainnet

Via CLI (overrides config):

python3 -m src.main --mode live   # switch to live (testnet still from config)

Safety: Live mode on mainnet always prompts for confirmation:

⚠️  LIVE TRADING MODE ⚠️
  Coins: ['BTC', 'ETH']
  Leverage: 3x
  Max daily loss: 5%
  Max drawdown: 15%

Type 'YES' to confirm live trading:

Wallet Setup & Testnet

Getting a Wallet

You need an EVM-compatible wallet. Recommended options:

Wallet	Type	Notes
MetaMask	Browser extension	Most widely used, works everywhere
Rabby	Browser extension	Better UX, built-in security checks
Any EVM wallet	Hardware/software	Anything that gives you a private key

Security tip: Create a separate wallet for bot trading. Never use your main wallet with significant holdings.

Getting Testnet Funds

Go to https://app.hyperliquid-testnet.xyz
Connect your wallet (MetaMask → click "Connect Wallet")
The testnet auto-funds your account with test USDC
If not funded automatically, look for a "Faucet" or "Deposit" button in the testnet UI
You should see a test USDC balance — this is free, not real money

Exporting Your Private Key

The bot needs your wallet's private key to sign transactions.

MetaMask:

Click the three-dot menu (⋮) next to your account name
Click Account Details
Click Show Private Key
Enter your MetaMask password
Copy the key (starts with 0x...)

Rabby:

Click the address bar at the top
Click the three-dot menu (⋮) next to the account
Click Export Private Key
Enter your password
Copy the key

Configuring the Bot with Your Wallet

Option A: Edit .env file

cp .env.example .env

Edit .env with your keys:

# Your wallet private key (NEVER share this)
HYPERLIQUID_PRIVATE_KEY=0xabc123...your_full_private_key_here

# Your wallet public address
HYPERLIQUID_WALLET_ADDRESS=0xDef456...your_wallet_address_here

# Network — true for testnet, false for mainnet
HYPERLIQUID_TESTNET=true

# Claude API key (from https://console.anthropic.com)
ANTHROPIC_API_KEY=sk-ant-your-key-here

Option B: Use the TUI Settings screen

Launch the TUI: python3 -m src.tui.app --demo
Press m to open Settings
Go to the Mode & Keys tab
Enter your Private Key, Wallet Address, and API Key
Toggle Testnet ON
Click Save to Disk — writes to both config/default.yaml and .env

Verifying Your Connection

source .venv/bin/activate
python3 scripts/check_connection.py

Expected output:

config_loaded     testnet=True mode=paper
testing_all_mids
all_mids_ok       count=50 sample={'BTC': '68234.5', ...}
testing_meta
meta_ok           total_assets=50 sample=['BTC', 'ETH', ...]
testing_l2_book   coin=BTC
l2_book_ok        best_bid=68233.0 best_ask=68235.0
testing_candles   coin=BTC interval=1h
candles_ok        count=24
testing_user_state address=0xDef456...
user_state_ok     equity=10000.0        ← your testnet balance
all_checks_passed

Known Issue: Testnet SDK Bug

The Hyperliquid Python SDK currently has a bug on testnet (IndexError: list index out of range during spot token initialization). This is an upstream SDK issue, not a bot bug.

Workaround — use mainnet in paper mode:

# config/default.yaml
exchange:
  mode: paper      # simulated trades, no real orders
  testnet: false   # real mainnet prices (read-only, safe)

This gives you real market data with simulated trades — zero risk, no wallet needed.

Once the SDK fix lands, switch to testnet live:

exchange:
  mode: live       # real orders
  testnet: true    # on testnet (free test money)

Quick Start Paths

What you have	What to do	Command
Nothing (just exploring)	Demo mode, no keys needed	`python3 -m src.tui.app --demo`
Anthropic API key only	Paper trade with real prices	Set `ANTHROPIC_API_KEY` in `.env`, run `python3 -m src.tui.app --config config/default.yaml`
API key + testnet wallet	Paper trade on testnet data	Set all keys in `.env`, set `testnet: true`
API key + testnet wallet + SDK fix	Live trade on testnet	Set `mode: live`, `testnet: true`
API key + mainnet wallet	Real money trading	Set `mode: live`, `testnet: false` (prompts for confirmation)

Recommended Progression

Step 1: python3 -m src.tui.app --demo
        → No keys needed, see how the TUI works

Step 2: Set ANTHROPIC_API_KEY in .env
        → Paper trade with real mainnet prices
        → Run for 1+ week, check data/paper_trades.csv

Step 3: Set wallet keys, testnet: true, mode: live
        → Real orders with free testnet money
        → Verify orders execute correctly

Step 4: testnet: false, mode: live
        → Real money on mainnet
        → Start with MINIMAL capital
        → Scale up only after weeks of validated performance

Dynamic Coin Scanner

Instead of manually picking coins, the bot can automatically scan all 200+ Hyperliquid perps and select the ones with the best trading opportunity.

How It Scores Coins

Each coin gets a composite score based on:

Factor	Weight	What it measures
Volatility (ATR%)	3.0x	Price movement range — more = more opportunity
Trend strength	2.0x	Directional consistency of recent candles
Price momentum	1.5x	% change over 24h — coins already moving
Volume (24h USD)	1.0x	Liquidity — capped contribution to avoid bias
Funding rate extreme	0.5x	Extreme funding = potential reversal setup

How to Enable

Settings screen (press m → Trading & Risk tab):

Toggle Auto-Select Coins ON
Set Auto-Select Top N (default: 5)

Or YAML (config/default.yaml):

trading:
  coins: [BTC, ETH]                    # Always kept (your base picks)
  auto_select_coins: true              # Enable dynamic scanning
  auto_select_top_n: 5                 # Total coins to trade
  auto_select_interval_seconds: 300    # Re-scan every 5 minutes
  auto_select_min_volume_usd: 1000000  # Ignore low-volume coins

Behavior

Scans every 5 minutes (configurable)
Your manually configured coins (e.g., BTC, ETH) are always kept — never dropped
Remaining slots filled with highest-scoring coins
Coins with open positions are never dropped mid-trade
Low-volume coins (< min threshold) are filtered out
Results cached between scans to avoid API spam

Example Scan Result

#   Coin     Score   Volatility  Trend  Momentum  Volume 24h
1   EIGEN    171.5   0.77%       83.3   +1.57%    $520K
2   APT      137.8   0.84%       66.7   +0.99%    $1.3M
3   CRV      136.6   0.74%       66.7   +0.53%    $2.0M
4   ARB      123.5   0.86%       58.3   +2.70%    $1.9M
5   DOT      105.7   0.90%       50.0   +1.82%    $1.6M
6   ETH       49.2   0.72%       16.7   +2.48%    $1.0B  ← always kept
7   BTC       47.8   0.63%       16.7   +1.72%    $2.9B  ← always kept

Profit Target

Automatically close all positions and pause the bot when your equity reaches a profit target. This locks in gains and prevents giving back profits.

How to Set

Settings screen (press m → Trading & Risk tab → Profit Target section):

Set Target Profit (%) — e.g., 10 for +10%
Set to 0 to disable

Or YAML (config/default.yaml):

risk:
  profit_target_pct: 0.10   # Stop at +10% profit. 0 = disabled

Behavior

Monitored continuously alongside the circuit breaker
When equity >= starting_equity * (1 + profit_target_pct):
1. All open positions are closed
2. Bot is paused automatically
3. Stats panel shows green PROFIT TARGET badge
4. Activity log shows the exact profit percentage and equity
Press r to reset the circuit breaker, then p to resume trading

Stats Panel Display

When enabled, the stats panel shows a progress bar toward your target:

Profit Target         $11,000 (80%)     ← 80% of the way to target

When reached:

Circuit Breaker       PROFIT TARGET     ← green badge (vs red for losses)

When disabled (0):

Profit Target         disabled

Examples

Starting Equity	Target	Triggers At
$10,000	10%	$11,000
$10,000	50%	$15,000
$10,000	100%	$20,000

Testing Workflow

Recommended progression from zero to live:

Step 1: Verify connectivity

python3 scripts/check_connection.py

Step 2: Fetch data and backtest

python3 scripts/fetch_historical.py --coins BTC ETH --days 90
# Then run backtests (see Run Backtests section)

Step 3: Paper trade on testnet

# Default settings — just run it
python3 -m src.main

Let it run for a few hours. Check logs/bot.log and data/paper_trades.csv.

Step 4: Paper trade on mainnet prices

# config/default.yaml
exchange:
  mode: paper
  testnet: false

python3 -m src.main

Run for 1+ week. Validate signals, AI costs, and drawdowns.

Step 5: Live on testnet

Get testnet USDC from the Hyperliquid testnet faucet, then:

exchange:
  mode: live
  testnet: true

python3 -m src.main --mode live

Step 6: Live on mainnet (real money)

exchange:
  mode: live
  testnet: false

python3 -m src.main --mode live
# Will prompt for "YES" confirmation

Start with minimal capital and scale gradually.

Configuration Reference

Exchange Settings

exchange:
  mode: paper              # paper = simulated | live = real orders
  testnet: true            # true = testnet API | false = mainnet API

Trading Settings

trading:
  coins:                   # List of coins to trade (always kept when auto-select is on)
    - BTC
    - ETH
  default_leverage: 3      # 1-50x (be careful above 10x)
  leverage_mode: cross     # cross | isolated
  auto_select_coins: false           # true = dynamically pick top coins by opportunity
  auto_select_top_n: 5               # how many coins to auto-select
  auto_select_interval_seconds: 300  # re-scan interval (seconds)
  auto_select_min_volume_usd: 1000000  # min 24h volume to consider

Indicator Settings

indicators:
  rsi_length: 14           # RSI lookback period
  macd_fast: 12            # MACD fast EMA
  macd_slow: 26            # MACD slow EMA
  macd_signal: 9           # MACD signal line
  bb_length: 20            # Bollinger Bands period
  bb_std: 2.0              # Bollinger Bands std deviation
  adx_length: 14           # ADX lookback period
  atr_length: 14           # ATR lookback period
  candle_buffer_size: 500  # How many candles to keep in memory
  candle_interval: 1m      # Candle interval (1m, 5m, 15m, 1h, 4h, 1d)

Claude AI Settings

claude:
  haiku_model: claude-haiku-4-5-20251001    # Fast/cheap model (90% of calls)
  opus_model: claude-sonnet-4-6             # Strong model (10% of calls)
  routine_interval_seconds: 900             # How often to call AI (900 = 15 min)
  min_call_interval_seconds: 60             # Minimum gap between calls
  daily_cost_cap_usd: 50.0                  # Hard daily spending limit
  max_input_tokens_per_call: 4000           # Max tokens per prompt
  cache_ttl_seconds: 1800                   # Cache AI responses for 30 min

Cost estimation:

At 15-min intervals: ~96 calls/day
90% Haiku (~~$0.001/call) + 10% Sonnet (~~$0.01/call) = ~$0.20-0.60/day
Cache hits reduce this further by ~30%

Risk Management Settings

risk:
  max_position_pct: 0.25           # Max 25% of equity per position
  max_total_exposure_pct: 0.75     # Max 75% total across all positions
  max_open_positions: 3            # Max simultaneous positions
  max_daily_loss_pct: 0.05         # Circuit breaker at 5% daily loss
  max_drawdown_pct: 0.15           # Circuit breaker at 15% drawdown
  default_stop_loss_pct: 0.02      # 2% stop loss
  default_take_profit_pct: 0.04    # 4% take profit (2:1 reward/risk)
  trailing_stop_activation_pct: 0.02  # Activate trailing after 2% profit
  trailing_stop_distance_pct: 0.01    # Trail 1% below peak
  consecutive_loss_reduction: 3    # Reduce size after 3 losses in a row
  size_reduction_factor: 0.5       # Cut size by 50% after consecutive losses
  profit_target_pct: 0.0           # 0 = disabled. E.g. 0.10 = stop at +10% profit

Strategy Settings

strategy:
  active: momentum                 # Which strategy to use
  momentum:
    adx_threshold: 25.0            # Minimum ADX for trend confirmation
    rsi_buy_threshold: 30.0        # RSI below this = oversold (buy signal)
    rsi_sell_threshold: 70.0       # RSI above this = overbought (sell signal)
    min_signal_strength: 0.5       # Minimum signal score to trade (0.0-1.0)
    ai_override_confidence: 0.7    # Minimum AI confidence to act on
    volume_spike_multiplier: 1.5   # Volume > 1.5x average = spike

Monitoring Settings

monitoring:
  log_level: INFO                  # DEBUG, INFO, WARNING, ERROR
  metrics_interval_seconds: 300    # Log stats every 5 minutes
  alert_webhook_url: ""            # Discord or Telegram webhook URL
  alert_debounce_seconds: 300      # Don't repeat same alert within 5 min

Monitoring & Alerts

Logs

Console: Human-readable output while running
File: logs/bot.log — full structured logs
Paper trades: data/paper_trades.csv — every simulated trade

Metrics

Saved to data/metrics.json every 5 minutes:

Total trades, win rate, average PnL
Max win, max loss, profit factor
Total fees and AI API costs
Bot uptime

Alerts

Configure a webhook in .env or config/default.yaml to receive alerts for:

Circuit breaker activation (daily loss or drawdown limit hit)
Large losses
Claude API budget exhausted
Exchange disconnection

Troubleshooting

"No module named pip"

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[dev]"

"Trading requires a private key"

You need to set HYPERLIQUID_PRIVATE_KEY in .env for live trading. Paper mode works without it.

"Daily cost cap reached"

The bot hit the daily_cost_cap_usd limit. It continues trading using local signals only (no AI). Increase the cap in config or wait for UTC midnight reset.

"circuit_breaker_tripped"

The bot lost more than the configured daily limit or drawdown. All positions are closed. Review your strategy parameters and market conditions. Reset manually if needed.

Stale data / WebSocket disconnected

The bot auto-reconnects after 60 seconds of no data. If persistent, check your network or Hyperliquid API status.

Backtest import error

Install backtesting dependencies:

uv pip install -e ".[backtest]"

FilesExpand file tree

GUIDE.md

Latest commit

History

GUIDE.md

File metadata and controls

Hyperliquid AI Trading Bot — User Guide

Table of Contents

Prerequisites

Installation

Configuration

Environment Variables

YAML Configuration

CLI Commands

hypertrade — Interactive Launcher

Running the Bot (Advanced)

TUI Dashboard

Check Connection

Fetch Historical Data

Run Backtests

Trading Modes

How to switch

Wallet Setup & Testnet

Getting a Wallet

Getting Testnet Funds

Exporting Your Private Key

Configuring the Bot with Your Wallet

Verifying Your Connection

Known Issue: Testnet SDK Bug

Quick Start Paths

Recommended Progression

Dynamic Coin Scanner

How It Scores Coins

How to Enable

Behavior

Example Scan Result

Profit Target

How to Set

Behavior

Stats Panel Display

Examples

Testing Workflow

Step 1: Verify connectivity

Step 2: Fetch data and backtest

Step 3: Paper trade on testnet

Step 4: Paper trade on mainnet prices

Step 5: Live on testnet

Step 6: Live on mainnet (real money)

Configuration Reference

Exchange Settings

Trading Settings

Indicator Settings

Claude AI Settings

Risk Management Settings

Strategy Settings

Monitoring Settings

Monitoring & Alerts

Logs

Metrics

Alerts

Troubleshooting

"No module named pip"

"Trading requires a private key"

"Daily cost cap reached"

"circuit_breaker_tripped"

Stale data / WebSocket disconnected

Backtest import error

`hypertrade` — Interactive Launcher