# 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*