saymrwulf/alpha-arena
1
0
Fork 0
mirror of https://github.com/saymrwulf/alpha-arena.git synced 2026-05-14 20:37:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
alpha-arena/docs/WEB_APP_MANUAL.md

723 lines
37 KiB
Markdown
Raw Permalink Normal View History

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 22:04:58 +00:00
# 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 Copy permalink