mirror of
https://github.com/saymrwulf/alpha-arena.git
synced 2026-05-14 20:37:51 +00:00
774f8b3f61
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
37 KiB
37 KiB
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
- Quick Start
- Dashboard
- Trading Control
- Positions & Orders
- Markets
- Wallet Analysis
- Agent Monitoring
- Risk Management
- Configuration
- Logs & Metrics
- Keyboard Shortcuts
- Troubleshooting
1. Quick Start
Starting the Server
# One command to start everything
./alpha start
You'll see a macOS notification when the server is ready.
Opening the Interface
# Opens in your default browser
./alpha open
Or navigate to: http://localhost:8000
First-Time Checklist
- Check Configuration - Go to
/configto verify API keys - Set Risk Limits - Visit
/riskto configure safety limits - Test in Simulation - Always start with simulation mode
- 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 |
| 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
# 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:
- Refresh the page
- Check browser console for errors
- Restart the server:
./alpha restart
API Keys Not Working
- Go to
/config - Verify keys are entered correctly
- Check for extra spaces
- 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
- Check Logs:
/logspage or./alpha logs - Run Diagnostics:
./alpha check - In-App Help:
/helppage - Reset Everything:
./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