saymrwulf/alpha-arena
1
0
Fork 0
mirror of https://github.com/saymrwulf/alpha-arena.git synced 2026-09-04 18:43:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
alpha-arena/docs/WEB_APP_MANUAL.md
oho 774f8b3f61 Initial commit: Alpha Arena - Polymarket Autonomous Trading Harness 
A comprehensive autonomous trading system for Polymarket prediction markets
featuring multi-LLM provider support, a native macOS menu bar app, and a
web-based control dashboard.

Key features:
- Multi-agent trading system (Research, Risk, Execution, Reflection agents)
- LLM provider flexibility (Anthropic, OpenAI, Google, xAI, Local models)
- Automatic provider fallback chain for resilience
- Native Swift/SwiftUI macOS menu bar application
- FastAPI web dashboard with real-time WebSocket updates
- Risk management with kill switch
- Technical indicators and market analysis
2026-01-12 23:04:58 +01:00

722 lines
37 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Alpha Arena Web Interface Guide
**Your complete guide to mastering the Alpha Arena control center**
---
## At a Glance
| What | Where | Shortcut |
|------|-------|----------|
| Start server | `./alpha start` | - |
| Open web UI | `./alpha open` | - |
| URL | http://localhost:8000 | - |
| Stop server | `./alpha stop` | - |
---
## Table of Contents
1. [Quick Start](#1-quick-start)
2. [Dashboard](#2-dashboard)
3. [Trading Control](#3-trading-control)
4. [Positions & Orders](#4-positions--orders)
5. [Markets](#5-markets)
6. [Wallet Analysis](#6-wallet-analysis)
7. [Agent Monitoring](#7-agent-monitoring)
8. [Risk Management](#8-risk-management)
9. [Configuration](#9-configuration)
10. [Logs & Metrics](#10-logs--metrics)
11. [Keyboard Shortcuts](#11-keyboard-shortcuts)
12. [Troubleshooting](#12-troubleshooting)
---
## 1. Quick Start
### Starting the Server
```bash
# One command to start everything
./alpha start
```
You'll see a macOS notification when the server is ready.
### Opening the Interface
```bash
# Opens in your default browser
./alpha open
```
Or navigate to: **http://localhost:8000**
### First-Time Checklist
1. **Check Configuration** - Go to `/config` to verify API keys
2. **Set Risk Limits** - Visit `/risk` to configure safety limits
3. **Test in Simulation** - Always start with simulation mode
4. **Watch the Dashboard** - Monitor `/` for system health
---
## 2. Dashboard
**URL:** `/` (home page)
The dashboard is your mission control center.
### Layout Overview
```
┌─────────────────────────────────────────────────────────────────────┐
│ Alpha Arena [Start Trading] [Kill Switch] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Balance │ │ Daily P&L│ │Positions │ │ Trades │ │
│ │ $1,234 │ │ +$45.67 │ │ 3/5 │ │ 127 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌─────────────────────────────────┐ ┌───────────────────────┐ │
│ │ │ │ System Status │ │
│ │ Equity Curve Chart │ │ ● Trading: Running │ │
│ │ ╱╲ ╱╲ │ │ ● Mode: Simulation │ │
│ │ ╱ ╲ ╱ ╲___ │ │ ● Kill Switch: Off │ │
│ │ ╱ ╲╱ │ │ ● WebSocket: Live │ │
│ │ │ │ │ │
│ │ [1D] [7D] [30D] [ALL] │ │ Risk Utilization │ │
│ └─────────────────────────────────┘ │ ████████░░ 80% │ │
│ └───────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Recent Activity │ │
│ │ • 14:32:15 Trade executed: BUY 100 USDC on Market X │ │
│ │ • 14:30:45 Signal generated: HIGH confidence (0.85) │ │
│ │ • 14:28:12 Position closed: +$12.34 profit │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
### Metric Cards Explained
| Card | What It Shows | Good Sign |
|------|---------------|-----------|
| **Balance** | Your current USDC balance | Stable or growing |
| **Daily P&L** | Today's profit/loss | Green number |
| **Positions** | Open positions / max allowed | Below limit |
| **Trades** | Total trades today | Reasonable activity |
### Color Coding
| Color | Meaning |
|-------|---------|
| Green | Positive / Good / Running |
| Red | Negative / Warning / Stopped |
| Yellow/Amber | Caution / Approaching limit |
| Blue | Informational |
| Gray | Inactive / Disabled |
### Equity Curve
The chart shows your portfolio value over time:
- **1D** - Last 24 hours (minute resolution)
- **7D** - Last week (hourly resolution)
- **30D** - Last month (daily resolution)
- **ALL** - All time
**Hover** over points to see exact values.
---
## 3. Trading Control
**URL:** `/trading`
This is where you start and stop the trading engine.
### Main Controls
```
┌─────────────────────────────────────────────────────────────────────┐
│ Trading Engine Status: STOPPED │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ │
│ │ START TRADING │ │
│ │ ▶ │ │
│ └─────────────────────┘ │
│ │
│ Mode Selection: │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ ◉ SIMULATION │ │ ○ LIVE │ │
│ │ Paper trading │ │ Real money │ │
│ │ No risk │ │ Actual trades │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### Trading Modes
| Mode | What Happens | When to Use |
|------|--------------|-------------|
| **Simulation** | Fake trades, real market data | Testing, learning |
| **Live** | Real trades with real money | Production trading |
### Configuration Options
| Setting | Description | Recommended |
|---------|-------------|-------------|
| Loop Interval | Seconds between trading cycles | 60-300 |
| Max Iterations | Stop after N cycles (null = forever) | null |
| Min Confidence | Required confidence level | 0.6-0.7 |
| Min Edge | Required profit margin | 0.03-0.05 |
### Feature Toggles
| Feature | What It Does |
|---------|--------------|
| **Multi-Agent System** | Multiple AI agents collaborate on decisions |
| **Agent Debate** | Agents debate before making trades |
| **Technical Indicators** | Use EMA, RSI, MACD in analysis |
| **Arbitrage Detection** | Find price discrepancies to exploit |
| **Reflection** | System learns from past decisions |
| **Memory System** | Remember past trades and outcomes |
### Kill Switch
```
┌─────────────────────────────────────────────────────────────────────┐
│ ⚠️ KILL SWITCH │
│ │
│ Emergency button to stop ALL trading immediately. │
│ Use when: unexpected market events, system errors, panic. │
│ │
│ ┌─────────────────────┐ │
│ │ 🛑 ACTIVATE │ │
│ └─────────────────────┘ │
│ │
│ Note: Existing positions remain open. Close them manually. │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 4. Positions & Orders
**URL:** `/positions`
Manage your open positions and pending orders.
### Positions Table
```
┌─────────────────────────────────────────────────────────────────────┐
│ Open Positions (3) [Refresh] │
├─────────────────────────────────────────────────────────────────────┤
│ Market │ Side │ Size │ Entry │ Current │ P&L │
│ ───────────────────────────────────────────────────────────────── │
│ Will Trump win? │ YES │ 50 USDC │ $0.45 │ $0.52 │ +$7.78 │
│ BTC > 100k Dec? │ NO │ 30 USDC │ $0.35 │ $0.32 │ +$2.57 │
│ Fed rate cut? │ YES │ 25 USDC │ $0.68 │ $0.65 │ -$1.10 │
├─────────────────────────────────────────────────────────────────────┤
│ Total P&L: +$9.25 │
└─────────────────────────────────────────────────────────────────────┘
```
### Position Actions
| Action | How | Effect |
|--------|-----|--------|
| **Close Position** | Click row → "Close" | Sells at market price |
| **View Details** | Click row | Shows entry time, market info |
### Orders Table
```
┌─────────────────────────────────────────────────────────────────────┐
│ Open Orders (1) [Cancel All] │
├─────────────────────────────────────────────────────────────────────┤
│ Market │ Side │ Size │ Price │ Status │ Action │
│ ───────────────────────────────────────────────────────────────── │
│ ETH > 5k Jan? │ BUY │ 20 USDC │ $0.28 │ Pending │ [Cancel]│
└─────────────────────────────────────────────────────────────────────┘
```
### Order Actions
| Action | How | Effect |
|--------|-----|--------|
| **Cancel Order** | Click "Cancel" | Removes pending order |
| **Cancel All** | Click "Cancel All" | Removes all pending orders |
---
## 5. Markets
**URL:** `/markets`
Browse and analyze Polymarket markets.
### Market Browser
```
┌─────────────────────────────────────────────────────────────────────┐
│ Markets [Refresh] [Filters]│
├─────────────────────────────────────────────────────────────────────┤
│ Filters: │
│ Category: [All ▼] Liquidity: [$1000+ ▼] Volume: [Active ▼] │
│ Search: [_______________________] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 📊 Will Trump win 2024 election? │ │
│ │ YES: $0.52 (+2.1%) │ NO: $0.48 (-2.1%) │ │
│ │ Volume: $1.2M │ Liquidity: $450K │ Ends: Nov 5, 2024 │ │
│ │ [View Details] [Trade] │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 📊 Fed rate cut in December? │ │
│ │ YES: $0.73 (+5.2%) │ NO: $0.27 (-5.2%) │ │
│ │ Volume: $890K │ Liquidity: $320K │ Ends: Dec 18, 2024 │ │
│ │ [View Details] [Trade] │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### Market Detail View
Click "View Details" to see:
- **Price history** chart
- **Technical indicators** (EMA, RSI, MACD)
- **Order book** depth
- **Recent trades** list
- **Related markets** suggestions
### Filtering Markets
| Filter | Options | Use Case |
|--------|---------|----------|
| **Category** | Politics, Sports, Crypto, etc. | Focus on topics you know |
| **Liquidity** | $1K+, $10K+, $100K+ | Ensure easy entry/exit |
| **Volume** | Low, Medium, High | Find active markets |
| **Status** | Open, Closing Soon, Resolved | Filter by timeframe |
---
## 6. Wallet Analysis
**URL:** `/wallet-analysis`
Analyze any Polymarket wallet's trading history and strategy.
### How to Use
```
┌─────────────────────────────────────────────────────────────────────┐
│ Wallet Analysis │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Enter a wallet address to analyze: │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 0x1234567890abcdef1234567890abcdef12345678 │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ [Analyze Wallet] │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### Analysis Results
After analysis, you'll see:
| Section | Information |
|---------|-------------|
| **Overview** | Total P&L, win rate, trade count |
| **Performance** | Equity curve, drawdown analysis |
| **Strategy** | Detected patterns, preferred markets |
| **Risk Profile** | Position sizes, holding times |
| **Trade History** | Detailed trade log |
### Sample Output
```
┌─────────────────────────────────────────────────────────────────────┐
│ Wallet: 0x1234...5678 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Performance Summary │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Total P&L│ │ Win Rate │ │ Trades │ │ Avg Hold │ │
│ │ +$12,456 │ │ 67% │ │ 234 │ │ 4.2 days│ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ Strategy Analysis │
│ • Prefers political markets (78% of trades) │
│ • Contrarian style - buys when others sell │
│ • Average position size: $150 │
│ • Best performing: US Elections (+$4,200) │
│ │
│ Risk Assessment: MODERATE │
│ • Max drawdown: -$1,200 (9.6%) │
│ • Largest single loss: -$340 │
│ • Recovery time: 12 days average │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 7. Agent Monitoring
**URL:** `/agents`
Monitor AI agent status and decision history.
### Agent Overview
```
┌─────────────────────────────────────────────────────────────────────┐
│ AI Agents │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 🤖 Fundamentals Agent Status: Active │
│ │ Role: Analyzes market fundamentals and news │
│ │ Last Decision: 2 min ago │
│ │ Accuracy: 72% │ Decisions Today: 45 │
│ │ [View History] │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 📈 Sentiment Agent Status: Active │
│ │ Role: Analyzes social media and market sentiment │
│ │ Last Decision: 5 min ago │
│ │ Accuracy: 68% │ Decisions Today: 38 │
│ │ [View History] │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 🔬 Technical Agent Status: Active │
│ │ Role: Analyzes price patterns and indicators │
│ │ Last Decision: 1 min ago │
│ │ Accuracy: 65% │ Decisions Today: 52 │
│ │ [View History] │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### Decision History
Click "View History" to see:
- Each decision with timestamp
- Reasoning provided by the agent
- Confidence level
- Outcome (if resolved)
---
## 8. Risk Management
**URL:** `/risk`
Configure safety limits to protect your capital.
### Risk Settings
```
┌─────────────────────────────────────────────────────────────────────┐
│ Risk Management [Save] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Position Limits │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Max Position Size: [$____500____] USDC │
│ │ Max Total Positions: [____5_____] │
│ │ Max Per Market: [$____200____] USDC │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Loss Limits │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Daily Loss Limit: [$____100____] USDC │
│ │ Max Drawdown: [____15_____] % │
│ │ Stop Loss Per Trade: [____10_____] % │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Kelly Criterion │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Kelly Fraction: [____0.25___] (0.0 - 1.0) │
│ │ Explanation: Bet 25% of Kelly-optimal size for safety │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Auto Kill Switch │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ [✓] Enable automatic kill switch │
│ │ Trigger when: Daily loss > $100 OR Drawdown > 15% │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### Risk Parameters Explained
| Parameter | What It Does | Recommended |
|-----------|--------------|-------------|
| **Max Position Size** | Largest single position | 2-5% of capital |
| **Max Positions** | How many open positions | 3-10 |
| **Daily Loss Limit** | Stop trading after this loss | 2-5% of capital |
| **Max Drawdown** | Maximum allowed decline | 10-20% |
| **Kelly Fraction** | Position sizing aggressiveness | 0.25 (quarter Kelly) |
### Kill Switch Triggers
The automatic kill switch activates when:
- Daily loss exceeds limit
- Drawdown exceeds threshold
- Unusual market conditions detected
- API errors exceed threshold
---
## 9. Configuration
**URL:** `/config`
Manage all system settings.
### Configuration Tabs
| Tab | Contents |
|-----|----------|
| **General** | Basic settings, intervals, paths |
| **API Keys** | Polymarket, LLM providers |
| **Trading** | Strategies, parameters |
| **Display** | UI preferences, themes |
### API Key Setup
```
┌─────────────────────────────────────────────────────────────────────┐
│ API Keys │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Anthropic (Claude) Status: ✓ Configured │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ sk-ant-api03-******************************** │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ OpenAI Status: ✗ Not Set │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ Enter OpenAI API key... │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ Polymarket Status: ✓ Configured │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ Private Key: ******************************** │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### LLM Provider Selection
| Provider | Model | Use Case |
|----------|-------|----------|
| **Anthropic** | Claude 3.5 Sonnet | Best for reasoning |
| **OpenAI** | GPT-4 | Good for analysis |
| **Local** | Llama 3 | Privacy, cost savings |
---
## 10. Logs & Metrics
**URL:** `/logs`
View decision logs and performance metrics.
### Decision Logs
```
┌─────────────────────────────────────────────────────────────────────┐
│ Decision Logs [Export] [Clear] [Filter] │
├─────────────────────────────────────────────────────────────────────┤
│ Time │ Market │ Decision │ Confidence │ Outcome │
│ ────────────────────────────────────────────────────────────────── │
│ 14:32:15 │ Trump 2024 │ BUY YES │ 0.82 │ +$12.34 │
│ 14:28:45 │ Fed Rate Cut │ HOLD │ 0.45 │ - │
│ 14:25:12 │ BTC > 100k │ SELL NO │ 0.71 │ Pending │
│ 14:20:33 │ ETH Merge │ BUY YES │ 0.88 │ +$8.90 │
│ ... │
└─────────────────────────────────────────────────────────────────────┘
```
### Performance Charts
Available visualizations:
- **Equity Curve** - Portfolio value over time
- **Drawdown Chart** - Decline from peak
- **Win/Loss Distribution** - Trade outcomes
- **P&L by Category** - Performance by market type
- **Confidence vs Outcome** - Calibration chart
### Export Options
| Format | Contents | Use Case |
|--------|----------|----------|
| **CSV** | All trades | Spreadsheet analysis |
| **JSON** | Full data | Programming |
| **PDF** | Summary report | Sharing |
---
## 11. Keyboard Shortcuts
### Global Shortcuts
| Key | Action |
|-----|--------|
| `?` | Show help |
| `g d` | Go to Dashboard |
| `g t` | Go to Trading |
| `g p` | Go to Positions |
| `g m` | Go to Markets |
| `g r` | Go to Risk |
| `g c` | Go to Config |
| `g l` | Go to Logs |
### Trading Shortcuts
| Key | Action |
|-----|--------|
| `s` | Start trading |
| `x` | Stop trading |
| `k` | Toggle kill switch |
| `r` | Refresh data |
### Navigation
| Key | Action |
|-----|--------|
| `j` | Next item |
| `k` | Previous item |
| `Enter` | Select / Open |
| `Esc` | Close / Cancel |
---
## 12. Troubleshooting
### Common Issues
#### Server Won't Start
```bash
# Check what's running on port 8000
lsof -i :8000
# Kill existing process
./alpha stop
# Try starting again
./alpha start
```
#### Can't Connect to WebSocket
Symptoms: Data not updating, "Disconnected" status
Solutions:
1. Refresh the page
2. Check browser console for errors
3. Restart the server: `./alpha restart`
#### API Keys Not Working
1. Go to `/config`
2. Verify keys are entered correctly
3. Check for extra spaces
4. Test with provider's API directly
#### Trading Not Starting
Checklist:
- [ ] Server is running (`./alpha status`)
- [ ] Not in kill switch mode
- [ ] API keys configured
- [ ] Risk limits not exceeded
- [ ] At least one market available
### Error Messages
| Error | Meaning | Solution |
|-------|---------|----------|
| "Kill switch active" | Emergency stop engaged | Disable in `/trading` |
| "Daily limit reached" | Loss limit hit | Wait until tomorrow or adjust in `/risk` |
| "No markets available" | Can't find tradeable markets | Check filters in `/markets` |
| "Provider error" | LLM API issue | Check API key and quota |
| "Insufficient balance" | Not enough USDC | Deposit funds |
### Getting Help
1. **Check Logs**: `/logs` page or `./alpha logs`
2. **Run Diagnostics**: `./alpha check`
3. **In-App Help**: `/help` page
4. **Reset Everything**:
```bash
./alpha stop
rm -rf .venv
./scripts/setup.sh
./alpha start
```
---
## Quick Reference Card
### URLs
| Page | URL |
|------|-----|
| Dashboard | `/` |
| Trading | `/trading` |
| Positions | `/positions` |
| Markets | `/markets` |
| Wallet Analysis | `/wallet-analysis` |
| Agents | `/agents` |
| Risk | `/risk` |
| Config | `/config` |
| Logs | `/logs` |
| Help | `/help` |
### CLI Commands
| Command | Action |
|---------|--------|
| `./alpha start` | Start server |
| `./alpha stop` | Stop server |
| `./alpha status` | Check status |
| `./alpha logs` | View logs |
| `./alpha open` | Open browser |
| `./alpha restart` | Restart server |
### API Endpoints
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/trading/start` | POST | Start trading |
| `/api/trading/stop` | POST | Stop trading |
| `/api/trading/status` | GET | Get status |
| `/api/trading/kill-switch` | POST | Toggle kill switch |
| `/api/positions` | GET | List positions |
| `/api/orders` | GET | List orders |
| `/api/system/health` | GET | Health check |
| `/ws` | WebSocket | Real-time updates |
---
*Last updated: January 2025*
Reference in a new issue View git blame Copy permalink