ManualTrader/docs/web-ui-setup.md

Web UI Setup Guide

This guide covers setting up and running the Hyperliquid Trading Bot Web UI (Phase 1 implementation).

🚀 Quick Start

1. Install Dependencies

The web UI requires additional FastAPI dependencies that have been added to pyproject.toml:

# If using uv
uv install

# If using pip
pip install -e .

2. Configure Environment

Add the following web UI settings to your .env file:

# Web UI Configuration
WEB_ENABLED=true
WEB_HOST=127.0.0.1
WEB_PORT=8080
WEB_API_KEY=your_secure_api_key_here
WEB_CORS_ORIGINS=http://localhost:8080,http://127.0.0.1:8080

Important: Generate a secure API key for WEB_API_KEY. This will be used for authentication.

3. Start the Web Server

Run the web server alongside your existing Telegram bot:

python web_start.py

The web UI will be available at: http://127.0.0.1:8080

📊 Dashboard Features (Phase 1)

Current Implementation

✅ Account Summary

• Account balance
• Total P&L and return percentage
• Win rate and profit factor
• Open positions count
• Max drawdown

✅ Live Positions

• Open positions with real-time P&L
• Entry price, mark price, leverage
• Side (long/short) indicators

✅ Recent Trades

• Last 10 completed trades
• P&L and ROE for each trade
• Trade timestamps

✅ Market Overview

• Real-time prices for major tokens (BTC, ETH, SOL, DOGE)
• 24-hour change percentages

✅ Responsive Design

• Mobile-friendly interface
• Tailwind CSS styling
• Auto-refresh functionality

Authentication

The web UI uses simple Bearer token authentication with the API key you configure. Enter your API key in the dashboard to access the data.

Copy Trading Tab Features

The copy trading tab provides comprehensive functionality including:

4. Enhanced Account Analysis (NEW)

• Clickable Analysis Results: All account addresses in analysis results and leaderboard are now clickable
• Deep Dive Analysis: Click any address to open a detailed analysis modal showing:
  • Account Overview: Address, analysis period, last trade, trading type
  • Score & Recommendation: 0-100 relative score with color-coded recommendation
  • Current Positions: Real-time positions with P&L, leverage, and position details
  • Performance Metrics: Total P&L, win rate, trades, duration, drawdown, profit factor
  • Trading Patterns: Frequency, leverage usage, token diversity, directional capability
  • Trading Style: Pattern analysis and top traded tokens
  • Recent Trading Activity: Last 10 trades with timestamps
  • Copy Trading Evaluation: Specific evaluation points and copyability assessment
  • Recommendations: Portfolio allocation suggestions and leverage limits
  • Quick Actions: "Set as Copy Target" button for recommended accounts

Enhanced User Experience

• Responsive Design: Modal adapts to screen size with scrollable content
• Visual Indicators: Emojis and color coding for quick interpretation
• Interactive Elements: Clickable addresses throughout the interface
• Real-time Data: Fresh analysis with current positions and recent trades
• Smart Recommendations: Context-aware suggestions based on account performance

🔧 Technical Details

Architecture

• Backend: FastAPI with async support
• Frontend: Vanilla JavaScript + Alpine.js + Tailwind CSS
• Database: Uses existing SQLite database
• Real-time: Auto-refresh every 30 seconds

File Structure

src/web/
├── __init__.py
├── app.py                 # Main FastAPI application
├── dependencies.py        # Authentication and dependencies
├── routers/
│   ├── __init__.py
│   └── dashboard.py       # Dashboard API endpoints
├── templates/
│   ├── base.html         # Base template
│   └── dashboard.html    # Dashboard page
└── static/
    ├── css/
    │   └── app.css       # Custom styles
    └── js/
        └── app.js        # JavaScript functionality

API Endpoints

• GET / - Dashboard page
• GET /api/dashboard/summary - Account summary data
• GET /api/dashboard/positions - Current positions
• GET /api/dashboard/recent-trades - Recent completed trades
• GET /api/dashboard/market-overview - Market data
• GET /health - Health check

🚀 Running with Telegram Bot

You can run both the Telegram bot and Web UI simultaneously:

Terminal 1 (Telegram Bot):

python trading_bot.py

Terminal 2 (Web UI):

python web_start.py

Both interfaces will access the same database and trading engine data.

🔍 Troubleshooting

Common Issues

1. Port already in use

   • Change WEB_PORT in your .env file
   • Or stop the process using the port: lsof -ti:8080 | xargs kill

2. API key authentication fails

   • Ensure WEB_API_KEY is set in .env
   • Enter the correct API key in the dashboard

3. Data not loading

   • Check that your trading bot has data in the database
   • Verify API key is correctly entered
   • Check browser console for errors

4. Configuration validation errors

   • Ensure all required environment variables are set
   • Check that WEB_ENABLED=true

Logs

Web UI logs are integrated with the existing logging system. Check:

• Console output when running web_start.py
• Log files in the logs/ directory

🛣️ Roadmap

Phase 2 (Next)

• Trading interface (place orders, close positions)
• Position management controls
• Real-time updates via WebSockets

Phase 3

• Copy trading dashboard and controls
• Target trader monitoring
• Copy trading performance metrics

Phase 4

• Advanced analytics and charts
• Performance visualizations
• Export functionality

🤝 Support

If you encounter issues:

1. Check the troubleshooting section above
2. Review logs for error messages
3. Ensure your .env configuration is correct
4. Verify the Telegram bot is working properly first