Alpha Lens

A Polymarket trader leaderboard that identifies and ranks skilled traders based on their historical performance in resolved prediction markets.

Features

• Trader Leaderboard: View top-performing Polymarket traders sorted by skill score, PnL, ROI, win rate, or consistency
• Detailed Profiles: See individual trader metrics, monthly performance charts, and top markets
• Performance Metrics:
  • Realized PnL: Actual profit/loss from resolved markets
  • ROI: Return on investment percentage
  • Win Rate: Percentage of profitable positions
  • Consistency Score: Monthly profitability rate
  • Skill Score: Composite metric (40% ROI, 20% PnL, 20% Win Rate, 20% Consistency)
• Filtering & Sorting: Filter by minimum volume, minimum markets, and sort by any metric
• Polymarket Links: Direct links to trader profiles on Polymarket

Tech Stack

• Backend: Python with FastAPI
• Database: PostgreSQL
• Frontend: Next.js 14 with TypeScript
• Styling: Tailwind CSS
• Charts: Recharts
• Data Fetching: TanStack Query

Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL 15+
• Docker & Docker Compose (optional)

Quick Start

Using Docker Compose (Recommended)

1. Start all services:

   docker-compose up -d

2. Run the initial backfill:

   docker-compose exec api python scripts/backfill_historical.py

3. Access the application:

   • Frontend: http://localhost:3000
   • API: http://localhost:8000
   • API Docs: http://localhost:8000/docs

Manual Setup

Backend

1. Create virtual environment:

   cd backend
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

   pip install -r requirements.txt

3. Set up environment:

   cp ../.env.example .env
   # Edit .env with your database credentials

4. Start PostgreSQL:

   # Using Docker:
   docker run -d --name alpha-lens-db \
     -e POSTGRES_USER=alphalens \
     -e POSTGRES_PASSWORD=dev_password_change_in_prod \
     -e POSTGRES_DB=alpha_lens \
     -p 5433:5432 \
     postgres:15-alpine

5. Run database migrations:

   alembic upgrade head

6. Run the backfill script:

   python scripts/backfill_historical.py

7. Start the API:

   uvicorn app.main:app --reload

Frontend

1. Install dependencies:

   cd frontend
   npm install

2. Set up environment:

   echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local

3. Start the development server:

   npm run dev

4. Open http://localhost:3000

API Endpoints

Health Check

GET /health

Leaderboard

GET /api/v1/traders

Query Parameters:

• limit (default: 50, max: 100)
• offset (default: 0)
• sort_by (skill_score, realized_pnl, roi, win_rate, consistency_score, total_volume)
• order (desc, asc)
• min_volume (optional)
• min_markets (optional)

Trader Detail

GET /api/v1/traders/{wallet_address}

Configuration

Key environment variables (see .env.example):

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	See .env.example
POLYMARKET_DATA_API_URL	Polymarket Data API	https://data-api.polymarket.com
POLYMARKET_GAMMA_API_URL	Polymarket Gamma API	https://gamma-api.polymarket.com
MIN_QUALIFIED_MARKETS	Minimum markets for qualification	10
MIN_QUALIFIED_VOLUME	Minimum volume for qualification	1000.0
ENABLE_SCHEDULER	Enable background jobs	true

Background Jobs

The scheduler runs the following jobs automatically:

• Hourly Trade Ingestion: Fetches new trades
• Daily Market Update (6 AM): Updates market resolution status
• Daily Metrics Computation (2 AM): Recalculates all trader metrics

Project Structure

alpha-lens/
├── backend/
│   ├── app/
│   │   ├── api/           # API routes
│   │   ├── ingestion/     # Data pipeline
│   │   ├── models/        # SQLAlchemy models
│   │   ├── schemas/       # Pydantic schemas
│   │   ├── scheduler/     # Background jobs
│   │   ├── services/      # Business logic
│   │   └── main.py        # FastAPI app
│   ├── migrations/        # Alembic migrations
│   ├── scripts/           # CLI scripts
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── app/           # Next.js pages
│   │   ├── components/    # React components
│   │   ├── hooks/         # Custom hooks
│   │   ├── lib/           # Utilities
│   │   └── types/         # TypeScript types
│   └── package.json
├── docker-compose.yml
└── README.md

Development

Running Tests

cd backend
pytest

Database Migrations

cd backend
# Create a new migration
alembic revision --autogenerate -m "Description"
# Apply migrations
alembic upgrade head

Roadmap

• Category-specific leaderboards (Politics, Crypto, Sports)
• User accounts and trader following
• Real-time trade alerts
• Advanced metrics (Sharpe ratio, max drawdown)
• Copy trading integration

License

MIT