Alphapoly - Polymarket alpha detection platform

Trades against Polymarket V2 (pUSD collateral). The legacy V1 (USDC.e) stack was retired on 2026-04-28 — git checkout v1-final to inspect it. If you hold USDC.e, wrap it to pUSD with experiments/trading/02wrapto_pusd.py before trading.

Find covering portfolios across correlated prediction markets using predefined rules and LLM decisions. The system detects relationships between markets, classifies them to identify hedging pairs, and tracks their prices. The platform offers a smooth UI for entering detected pairs when profit opportunities exist and tracking your positions.

For a good experience, you'll need to add an LLM from OpenRouter and an RPC node (see .env.example).

Trading runs through per-user deposit wallets (signature type 3). You supply an EOA signing key plus a Relayer API key (minted at polymarket.com/settings?tab=api-keys); the app deploys a deposit wallet gaslessly and the relayer pays gas — fund the deposit wallet with pUSD, no POL needed. Bare EOAs can't trade directly (they're blocked by the V2 CLOB allowlist).

Dashboard Screenshot

How It Works

Groups - Fetches markets from Polymarket (e.g., "Presidential Election Winner")
Implications (LLM) - Extracts logical relationships between groups
Validation (LLM) - Validates implications at the individual market level
Portfolios - Computes cost and expected profit for validated pairs using live market prices
Positions - Tracks your purchased position pairs

Prerequisites

uv (manages Python automatically)
Node.js 18+ via fnm, nvm, or brew

Quick Start

cp .env.example .env
With make
make install && make dev
Without make
cd backend && uv sync
cd frontend && npm install
cd backend && uv run python -m uvicorn server.main:app --port 8000 &
cd frontend && npm run dev

Dashboard: http://localhost:3000 · API: http://localhost:8000/docs

Commands

With make (auto-detects fnm/nvm/volta):

make install    # Install deps make dev        # Start both servers make pipeline   # Run ML pipeline (incremental, also available in UI) make lint       # Auto-fix: ruff + prettier + eslint

Without make:

# Backend cd backend && uv sync cd backend && uv run python -m uvicorn server.main:app --reload --port 8000
Frontend
cd frontend && npm install
cd frontend && npm run dev

Agentic Coding

This repo is configured for AI coding agents via the .claude/ directory:

CLAUDE.md — project context, commands, conventions, and API routes
hooks/ — auto-lint on edit, guard against writing secrets (Claude Code only)
skills/ — workflows for pipeline management, trading, and feature development

Skills

The .claude/skills/ directory contains Agent Skills — an open standard for extending AI coding agents with reusable, modular capabilities. Each skill is a directory with a SKILL.md file (YAML frontmatter + natural-language instructions) that teaches an agent how to perform a domain-specific workflow.

| Skill | Purpose | |-------|---------| | alphapoly-pipeline | Run, debug, and manage the ML pipeline | | alphapoly-portfolios | Fetch and display portfolio opportunities | | alphapoly-enter-position | Execute a covered pair trade | | alphapoly-exit-position | Exit or manage an open position | | alphapoly-feature | Add features following stack conventions | | alphapoly-experiment | Scaffold standalone experiment scripts |

To use the skills in this repo with a different agent, point it at .claude/skills/ or copy the skill directories into the agent's expected location (e.g., ~/.codex/skills/ for Codex CLI).

Instructions file

CLAUDE.md is read natively by Claude Code and by GitHub Copilot in VS Code (opt-in via chat.useClaudeMdFile). For broader cross-agent compatibility, AGENTS.md is also provided as a symlink to CLAUDE.md — an open format supported by Codex, Cursor, Copilot, and others.

Experiments

Standalone research scripts (no imports from backend/). Four groups:

| Folder | Description | |--------|-------------| | experiments/ | Pipeline-step learning examples — fetch events, build groups, extract implications, validate, score portfolios, stream prices. Mirrors what backend/core/runner.py orchestrates, one stage per file. | | experiments/trading/ | Wallet + funding + position helpers. Set up a per-user deposit wallet (sigtype-3, deployed gaslessly via a Relayer API key), wrap USDC.e ↔ pUSD via Polymarket's CollateralOnramp/Offramp (1:1, gas-only, no slippage), buy a position, transfer tokens. | | experiments/onchain-otc/ | On-chain OTC trading without the CLOB — split/merge, P2P transfers, atomic escrow, NegRisk conversions, and intent-based settlement on an Anvil fork of Polygon. Forked-chain research; uses USDC.e collateral (the fork's frozen state predates Polymarket V2 / pUSD). | | experiments/verify/ | Verification probes for the deposit-wallet path. 03sigtype3_spike.py walks the official polymarket-client SDK from L1 auth → deposit-wallet derivation → relayer deploy → a non-filling order, confirming the sigtype-3 allowlist gate is cleared. Reach for it when onboarding breaks. |

Disclaimer: This software is provided as-is for educational and research purposes only. It is not financial advice. Trading prediction markets involves risk—you may lose money. Use at your own discretion.

🔗 More in this category