alpha-arena/README.md

Alpha Arena

Autonomous trading system for Polymarket prediction markets

Single objective: maximize PnL

---

Start in 10 Seconds

./alpha start

Then open http://localhost:8000

That's it. Everything runs in the background with macOS notifications.

---

Daily Commands

Command	What it does
./alpha start	Start server (background, notifies when ready)
./alpha stop	Stop server (graceful shutdown)
./alpha status	Check if running
./alpha logs	Watch live logs
./alpha open	Open web UI in browser

See QUICKSTART.md for the complete command reference.

---

What You Get

Native macOS Menu Bar App

Control Alpha Arena from your menu bar:

• One-click server start/stop
• Real-time P&L updates via WebSocket
• Native notifications for trades and alerts
• Quick access to dashboard and logs
• Network mode toggle (localhost/LAN)

Requires: macOS 13.0+, Xcode 15.0+ (from App Store)

# Build and install
cd macos-app && ./build.sh install

See docs/MACOS_APP_MANUAL.md for full documentation.

Web Control Center

Real-time dashboard at localhost:8000 with:

• Live P&L and positions
• Start/stop trading controls
• Market browser and analysis
• Risk management settings
• Decision logs and metrics

Multi-Agent Trading

Four specialized AI agents collaborating:

• Research - Market analysis, probability estimation
• Risk - Position sizing with Kelly Criterion
• Execution - Optimal order timing
• Reflection - Learning from outcomes

Safety First

• Kill switch for emergency stop
• Daily loss limits
• Position size caps
• Simulation mode for testing

---

Requirements

• Python 3.11+ (tested with 3.14)
• macOS, Linux, or WSL
• At least one LLM API key (Anthropic, OpenAI, or xAI)

---

First-Time Setup

The ./alpha start command handles setup automatically. For manual control:

# 1. Run setup
./scripts/setup.sh

# 2. Add your API keys
nano .env

# 3. Verify everything works
./scripts/check.sh

# 4. Start
./alpha start

Required API Keys

Add to .env:

# At least one LLM provider
ANTHROPIC_API_KEY=sk-ant-...
# or
OPENAI_API_KEY=sk-...

# For live trading (optional)
POLYMARKET_API_KEY=...
POLYMARKET_API_SECRET=...
POLYMARKET_PASSPHRASE=...

---

Architecture

┌──────────────────┐     ┌────────────────────────────────────────┐
│  macOS Menu Bar  │     │       Web Application (FastAPI)        │
│   (SwiftUI App)  │     │     Dashboard | Trading | Markets      │
└────────┬─────────┘     └───────────────────┬────────────────────┘
         │                                   │
         └──────────────┬────────────────────┘
                        │ REST API + WebSocket
                        ▼
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
    ┌──────────┐  ┌──────────┐  ┌──────────┐
    │ Trading  │  │  Agent   │  │   Risk   │
    │   Loop   │  │ System   │  │ Manager  │
    └──────────┘  └──────────┘  └──────────┘
          │             │
          ▼             ▼
    ┌──────────┐  ┌──────────┐
    │ Broker   │  │   LLM    │
    │Polymarket│  │ Providers│
    └──────────┘  └──────────┘

---

Project Structure

alpha-arena/
├── alpha                 # Master control script
├── QUICKSTART.md         # Daily command reference
├── scripts/
│   ├── setup.sh          # First-time setup
│   ├── check.sh          # System diagnostics
│   └── test.sh           # Run tests
├── src/
│   ├── web/              # Web application
│   ├── broker/           # Market execution
│   ├── agents/           # AI agents + debate system
│   ├── signals/          # News, events, sentiment
│   ├── risk/             # Risk management
│   └── llm/              # LLM provider abstraction
├── macos-app/            # Native SwiftUI menu bar app
│   ├── AlphaArena/       # Swift source files
│   └── build.sh          # Build script
├── tests/                # Test suite (200+ tests)
├── docs/                 # Detailed documentation
├── .venv/                # Isolated Python (auto-created)
└── data/                 # Runtime data (auto-created)

---

Documentation

Document	Purpose
QUICKSTART.md	Daily commands, quick reference
docs/MACOS_APP_MANUAL.md	Native macOS menu bar app
docs/WEB_APP_MANUAL.md	Web interface guide
docs/USER_MANUAL.md	Full CLI and API reference
docs/TESTING.md	Testing guide

---

Troubleshooting

Server won't start

./scripts/check.sh --fix

Missing dependencies

./scripts/setup.sh

API key issues

Check .env has valid keys, then restart.

Something else broke

./alpha logs    # See what's happening
./alpha status  # Check process status

---

Isolation

Everything runs in complete isolation:

• .venv/ - Python packages (nothing global)
• data/ - All runtime data
• .env - Your configuration

Uninstall completely by deleting the folder.

---

License

MIT

---

Disclaimer

This software is for educational purposes. Trading prediction markets involves financial risk. Past performance does not guarantee future results. Use at your own risk.