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/QUICKSTART.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

5.4 KiB
Raw Blame History

Quick Start Guide

Your daily reference for Alpha Arena commands.

Essential Commands

Start

./alpha start

Starts the server in the background. You'll get a macOS notification when it's ready.

Stop

./alpha stop

Graceful shutdown with notification.

Status

./alpha status

Shows if running, the URL, and health status.

Logs

./alpha logs

Watch live server logs. Press Ctrl+C to exit.

Open Web UI

./alpha open

Opens http://localhost:8000 in your browser (starts server if needed).

All Commands

Command Description
./alpha start Start in background, notify when ready
./alpha stop Stop gracefully, notify when stopped
./alpha restart Stop then start
./alpha status Show running status and URL
./alpha logs Watch live logs (Ctrl+C to exit)
./alpha open Open web UI in browser
./alpha test Run all tests
./alpha check Run system diagnostics
./alpha help Show all commands

Web Interface

Once started, open: http://localhost:8000

Page What it does
Dashboard Live P&L, positions, system status
Trading Start/stop trading, simulation/live modes
Positions View and manage open positions
Markets Browse Polymarket markets
Wallet Analysis Analyze any wallet's strategy
Agents Monitor AI agent status
Risk Configure limits and kill switch
Config All system settings
Logs Decision logs and metrics

Notifications

You'll get macOS notifications when:

  • Server starts successfully
  • Server stops
  • Errors occur

Environment Variables

Override defaults without editing config:

# Change port
ALPHA_PORT=9000 ./alpha start

# Change host (for network access)
ALPHA_HOST=0.0.0.0 ./alpha start

Menu Bar App (macOS)

For a native macOS experience, use the menu bar app instead of terminal commands.

Requirements

  • macOS 13.0 or later
  • Xcode 15.0+ (for building from source)

Build & Install

# Build the app
cd macos-app
./build.sh

# Or build and install to /Applications
./build.sh install

Open in Xcode (for development)

open macos-app/AlphaArena.xcodeproj

Features

  • Native SwiftUI menu bar app
  • Status icon in menu bar (green=running, gray=stopped)
  • Start/Stop server with one click
  • Real-time P&L and position updates via WebSocket
  • Network mode toggle (localhost vs LAN-accessible)
  • Rich notifications with action buttons
  • Open Dashboard, View Logs, Copy URL shortcuts
  • Preferences window for configuration

Menu Bar Controls

┌────────────────────────────────────────┐
│ ● Server Running                       │
│   http://127.0.0.1:8000                │
├────────────────────────────────────────┤
│ P&L: +$127.45 | 5 positions            │
│ Trading: Active (simulation)           │
├────────────────────────────────────────┤
│ Stop Server                   ⌘⇧S      │
│ Open Dashboard                ⌘D       │
│ Copy Server URL               ⌘C       │
│ View Logs                     ⌘L       │
├────────────────────────────────────────┤
│ Network Mode                        ▶  │
│   ✓ Localhost Only (127.0.0.1)        │
│     LAN Access (0.0.0.0)              │
├────────────────────────────────────────┤
│ Preferences...                ⌘,       │
│ Quit Alpha Arena              ⌘Q       │
└────────────────────────────────────────┘

Keyboard Shortcuts

Shortcut Action
⌘S Start Server
⌘⇧S Stop Server
⌘D Open Dashboard
⌘C Copy Server URL
⌘L View Logs
⌘, Preferences
⌘Q Quit

Auto-Start at Login

To have Alpha Arena start automatically when you log in:

./scripts/install-autostart.sh

To remove auto-start:

./scripts/install-autostart.sh remove

Testing

# Run all tests
./alpha test

# Or use the test script directly
./scripts/test.sh          # All tests
./scripts/test.sh unit     # Unit tests only
./scripts/test.sh api      # API tests only
./scripts/test.sh e2e      # End-to-end tests
./scripts/test.sh coverage # With coverage report

First-Time Setup

If ./alpha start says setup is needed:

./scripts/setup.sh

Then add your API keys to .env:

ANTHROPIC_API_KEY=sk-ant-...

Troubleshooting

Server won't start

./scripts/check.sh --fix

Check what's running

./alpha status

See error details

./alpha logs

Reset everything

./alpha stop
rm -rf .venv
./scripts/setup.sh
./alpha start

Next Steps