Prediction Analyzer

A complete modular analysis tool for prediction market traders. Analyze past trades, calculate PnL, generate charts, and export reports across multiple prediction market platforms.

Supported Platforms

Platform	Currency	Auth Method	API Key Prefix
Limitless Exchange	USDC	API key	`lmts_`
Polymarket	USDC	Wallet address (public API)	`0x`
Kalshi	USD	RSA key pair (RSA-PSS signing)	`kalshi_`
Manifold Markets	MANA	API key	`manifold_`

Features

For Everyone

Graphical User Interface (GUI) - Easy-to-use desktop application with provider selection
Multi-platform support - Load and analyze trades from 4 prediction market platforms
Load trade history from JSON, CSV, or Excel (auto-detects provider format)
Calculate global and market-specific PnL
Filter trades by date, type, side (YES/NO), PnL thresholds, and source provider
Export reports in multiple formats (CSV, Excel, JSON)
Interactive CLI menu for easy navigation

For Novice Traders

Simple, easy-to-understand charts
Step-by-step interactive menus
Clear PnL summaries with per-provider breakdowns
One-click analysis

For Professional Traders

Advanced interactive charts with Plotly
Multi-market dashboards
Cross-provider portfolio analysis
Portfolio position tracking with unrealized PnL and concentration risk (HHI)
Drawdown analysis with recovery tracking
Tax reporting with FIFO/LIFO/average cost basis methods and wash sale detection
Period-over-period performance comparison
Currency-separated PnL aggregation (real-money USD/USDC vs play-money MANA)
FIFO PnL computation for providers without native PnL
MCP server integration for Claude Code / Claude Desktop
FastAPI web server with JWT authentication and security headers
Command-line interface for automation

Installation

For detailed installation instructions, see INSTALL.md For a step-by-step walkthrough, see TUTORIAL.md

Quick Start (3 Easy Steps)

Windows Users (Easiest):

Download/clone this repository
Double-click install.bat (or run it from command prompt)
Run python run.py

All Platforms:

# 1. Install dependencies
pip install -r requirements.txt

# 2. Run the analyzer
python run.py --help

The run.py script will automatically check for missing dependencies and guide you if anything is missing!

Full Installation (Optional)

If you want to install as a package and use prediction-analyzer command anywhere:

pip install -e .

After installation, you can use the prediction-analyzer command directly:

prediction-analyzer --file your_trades.json

Quick Start

GUI Mode (Easiest)

The easiest way to use Prediction Analyzer is through the graphical interface:

# Windows: Just double-click run_gui.bat
# Or run from command line:
python run_gui.py

The GUI provides a 7-tab interface:

Global Summary — Aggregate PnL with currency and provider breakdowns
Market Analysis — Per-market PnL, charts, and outcome inference
Trade Browser — Sortable, searchable trade list with market search
Filters — Date, type, side (YES/NO), and PnL filters
Charts — Simple, Pro, Enhanced, and Dashboard chart generation
Portfolio — Open positions, concentration risk (HHI), drawdown analysis
Tax Report — Capital gains with FIFO/LIFO/average cost basis, wash sale detection

Plus: provider selection dropdown, CSV/Excel/JSON export, keyboard shortcuts (Ctrl+O, Ctrl+S, Ctrl+F, Ctrl+Q), and period comparison dialog

Interactive CLI Mode (Terminal-Friendly)

# Without installation
python run.py --file your_trades.json

# Or with installation
prediction-analyzer --file your_trades.json

Command-Line Mode (Pro Users)

# Global PnL summary
python run.py --file trades.json --global

# Analyze specific market with pro chart
python run.py --file trades.json --market "ETH-USD" --chart pro

# Multi-market dashboard
python run.py --file trades.json --dashboard

# Filter and export
python run.py --file trades.json \
    --start-date 2024-01-01 \
    --end-date 2024-12-31 \
    --type Buy \
    --export filtered_trades.xlsx

Note: Replace python run.py with prediction-analyzer if you installed the package.

Fetch Live Data from Prediction Markets

# Limitless Exchange
export LIMITLESS_API_KEY="lmts_your_api_key_here"
python run.py --fetch

# Polymarket (uses public Data API with wallet address)
python run.py --fetch --provider polymarket --key "0xYourWalletAddress"

# Kalshi (RSA key pair)
export KALSHI_API_KEY_ID="your_key_id"
export KALSHI_PRIVATE_KEY_PATH="kalshi_private_key.pem"
python run.py --fetch --provider kalshi --key "kalshi_KEY_ID:key.pem"

# Manifold Markets
python run.py --fetch --provider manifold --key "manifold_your_key"

# Auto-detect provider from key format
python run.py --fetch --key "lmts_your_api_key_here"

MCP Server (for Claude Code / Claude Desktop)

# stdio transport (default, for Claude Code)
python -m prediction_mcp

# HTTP/SSE transport (for web agents)
python -m prediction_mcp --sse --port 8000

# With SQLite session persistence
python -m prediction_mcp --persist session.db

Usage Examples

Example 1: Multi-Provider Analysis

# Fetch from multiple providers sequentially
python run.py --fetch --provider limitless --key "lmts_..."
python run.py --fetch --provider polymarket --key "0x..."

# Load a file with auto-detected format
python run.py --file polymarket_trades.json --global

Example 2: Quick Market Analysis

python run.py --file trades.json --market "BTC-USD" --chart simple

Example 3: Professional Dashboard

python run.py --file trades.json --dashboard

Example 4: Filtered Export

python run.py --file trades.json \
    --start-date 2024-06-01 \
    --min-pnl 10 \
    --export profitable_trades.csv

Example 5: Advanced Metrics

python run.py --file trades.json --metrics

Python API

You can also use the package programmatically:

from prediction_analyzer.trade_loader import load_trades
from prediction_analyzer.pnl import calculate_global_pnl_summary
from prediction_analyzer.charts.pro import generate_pro_chart

# Load trades (auto-detects provider format)
trades = load_trades("trades.json")

# Calculate PnL
summary = calculate_global_pnl_summary(trades)
print(f"Total PnL: ${summary['total_pnl']:.2f}")

# Fetch from a specific provider
from prediction_analyzer.providers import ProviderRegistry
provider = ProviderRegistry.get("polymarket")
trades = provider.fetch_trades("0xYourWallet")

# Apply FIFO PnL computation
from prediction_analyzer.providers.pnl_calculator import compute_realized_pnl
trades = compute_realized_pnl(trades)

# Filter by source provider
from prediction_analyzer.trade_filter import filter_trades_by_source
poly_trades = filter_trades_by_source(trades, "polymarket")

CLI Options

Data Source

--file FILE - Load trades from file (JSON/CSV/XLSX) with auto-format detection
--fetch - Fetch live trades from prediction market API
--key KEY - API key/credential (format depends on provider)
--provider {auto,limitless,polymarket,kalshi,manifold} - Provider selection (default: auto-detect from key)

Analysis

--market MARKET - Analyze specific market
--global - Show global PnL summary
--chart {simple,pro,enhanced} - Chart type (default: simple)
--dashboard - Generate multi-market dashboard
--metrics - Show advanced trading metrics (Sharpe, drawdown, streaks)

Filters

--start-date DATE - Filter from date (YYYY-MM-DD)
--end-date DATE - Filter to date (YYYY-MM-DD)
--type {Buy,Sell} - Filter by trade type
--min-pnl PNL - Minimum PnL threshold
--max-pnl PNL - Maximum PnL threshold

Export

--export FILE - Export filtered trades (.csv or .xlsx)
--report - Generate detailed text report

Project Structure

prediction_analyzer/
├── __init__.py              # Package initialization
├── __main__.py              # CLI entry point (multi-provider)
├── config.py                # Configuration constants + PROVIDER_CONFIGS
├── trade_loader.py          # Trade loading (JSON/CSV/XLSX) with auto-detection
├── trade_filter.py          # Trade filtering (market, source, dedup)
├── filters.py               # Advanced filters (date, type, PnL)
├── pnl.py                   # PnL calculations (with per-source breakdown)
├── metrics.py               # Advanced trading metrics (Sharpe, Sortino, drawdown, streaks)
├── positions.py             # Open positions, unrealized PnL, concentration risk
├── drawdown.py              # Drawdown analysis with recovery tracking
├── tax.py                   # Tax reporting (FIFO/LIFO/average cost basis, wash sales)
├── comparison.py            # Period-over-period performance comparison
├── inference.py             # Market outcome inference
├── exceptions.py            # Custom exception classes
├── providers/               # Multi-market provider abstraction
│   ├── base.py              # MarketProvider ABC + ProviderRegistry
│   ├── limitless.py         # Limitless Exchange provider
│   ├── polymarket.py        # Polymarket provider
│   ├── kalshi.py            # Kalshi provider (RSA-PSS auth)
│   ├── manifold.py          # Manifold Markets provider
│   └── pnl_calculator.py    # FIFO PnL computation
├── charts/                  # Chart generation modules
│   ├── simple.py            # Simple charts (matplotlib)
│   ├── pro.py               # Professional charts (Plotly)
│   ├── enhanced.py          # Battlefield-style visualization
│   └── global_chart.py      # Multi-market dashboard
├── reporting/               # Report generation
│   ├── report_text.py       # Text reports
│   └── report_data.py       # Data exports (CSV/Excel/JSON)
├── utils/                   # Utility functions
│   ├── auth.py              # Multi-provider API authentication
│   ├── data.py              # Limitless API data fetching
│   ├── time_utils.py        # Time utilities
│   ├── math_utils.py        # Math utilities
│   └── export.py            # Export utilities
├── api/                     # FastAPI web application (JWT auth, security headers)
│   ├── models/              # SQLAlchemy ORM models (Numeric precision for money)
│   ├── routers/             # API route handlers (all authenticated)
│   ├── schemas/             # Pydantic request/response schemas (with field constraints)
│   └── services/            # Business logic services (10 MB upload limit)
└── core/                    # Core modules
    └── interactive.py       # Interactive CLI menu

prediction_mcp/              # MCP server for Claude integration
├── server.py                # MCP server entry point (stdio + SSE)
├── state.py                 # Session state (multi-source)
├── persistence.py           # SQLite session persistence
├── errors.py                # @safe_tool decorator + recovery hints
├── serializers.py           # JSON serialization (NaN/Infinity safe)
├── validators.py            # Input validation + case normalization
├── _apply_filters.py        # Shared filter application helper
└── tools/                   # MCP tool modules (18 tools)
    ├── data_tools.py        # load_trades, fetch_trades, list_markets, get_trade_details
    ├── analysis_tools.py    # get_global_summary, get_market_summary, get_advanced_metrics, get_market_breakdown, get_provider_breakdown
    ├── filter_tools.py      # filter_trades (with clear=true)
    ├── chart_tools.py       # generate_chart, generate_dashboard
    ├── export_tools.py      # export_trades (csv/xlsx/json)
    ├── portfolio_tools.py   # get_open_positions, get_concentration_risk, get_drawdown_analysis, compare_periods
    └── tax_tools.py         # get_tax_report

Root directory:
├── run.py                   # CLI launcher
├── run_gui.py               # GUI launcher
├── run_gui.bat              # Windows GUI launcher
├── gui.py                   # GUI application (Tkinter, multi-provider)
├── requirements.txt         # Dependencies
├── .env.example             # Environment variable template (all providers)
└── tests/                   # Test suite

Testing

# Run tests
pytest

# Run with coverage
pytest --cov=prediction_analyzer

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

Troubleshooting

For complete troubleshooting guide, see INSTALL.md

Missing Dependencies (pandas, numpy, cryptography, etc.)

The run.py script will now detect missing dependencies and show you exactly what's missing!

Quick Fix:

# Windows: Double-click install.bat or run:
install.bat

# All platforms:
pip install -r requirements.txt

"ModuleNotFoundError: No module named 'setuptools'"

Don't use python setup.py directly. Instead:

pip install -r requirements.txt

"ImportError: attempted relative import with no known parent package"

Don't run files from inside the prediction_analyzer/ directory. Always use:

# From the project root directory:
python run.py --file your_trades.json

Windows Path Issues

On Windows, use forward slashes or escape backslashes in file paths:

# Good
python run.py --file "C:/Users/YourName/trades.json"

# Also good
python run.py --file "C:\\Users\\YourName\\trades.json"

GUI Not Launching (Linux)

If the GUI doesn't launch on Linux, you may need to install tkinter:

# Ubuntu/Debian
sudo apt-get install python3-tk

# Fedora
sudo dnf install python3-tkinter

# Arch Linux
sudo pacman -S tk

Kalshi RSA Key Issues

If you get errors with Kalshi authentication:

# Ensure cryptography package is installed
pip install cryptography>=41.0.0

# Verify your PEM key file is readable
ls -la your_private_key.pem

Name		Name	Last commit message	Last commit date
Latest commit History 109 Commits
.claude		.claude
.github/workflows		.github/workflows
data		data
docs		docs
prediction_analyzer		prediction_analyzer
prediction_mcp		prediction_mcp
tests		tests
.env.example		.env.example
.flake8		.flake8
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODEBASE_AUDIT.md		CODEBASE_AUDIT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
EXPERT_BUG_AUDIT_FINDINGS.md		EXPERT_BUG_AUDIT_FINDINGS.md
EXPERT_BUG_AUDIT_PROMPT.md		EXPERT_BUG_AUDIT_PROMPT.md
FRONTEND_QA_AUDIT_PROMPT.md		FRONTEND_QA_AUDIT_PROMPT.md
INSTALL.md		INSTALL.md
MCP_READINESS_PLAN.md		MCP_READINESS_PLAN.md
MULTI_MARKET_PLAN.md		MULTI_MARKET_PLAN.md
Makefile		Makefile
QA_AUDIT_PROMPT.md		QA_AUDIT_PROMPT.md
README.md		README.md
SECURITY_AUDIT.md		SECURITY_AUDIT.md
TUTORIAL.md		TUTORIAL.md
docker-compose.yml		docker-compose.yml
gui.py		gui.py
install.bat		install.bat
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
run.py		run.py
run_api.py		run_api.py
run_gui.bat		run_gui.bat
run_gui.py		run_gui.py
run_static_tests.py		run_static_tests.py

Folders and files

Latest commit

History

Repository files navigation

Prediction Analyzer

Supported Platforms

Features

For Everyone

For Novice Traders

For Professional Traders

Installation

Quick Start (3 Easy Steps)

Windows Users (Easiest):

All Platforms:

Full Installation (Optional)

Quick Start

GUI Mode (Easiest)

Interactive CLI Mode (Terminal-Friendly)

Command-Line Mode (Pro Users)

Fetch Live Data from Prediction Markets

MCP Server (for Claude Code / Claude Desktop)

Usage Examples

Example 1: Multi-Provider Analysis

Example 2: Quick Market Analysis

Example 3: Professional Dashboard

Example 4: Filtered Export

Example 5: Advanced Metrics

Python API

CLI Options

Data Source

Analysis

Filters

Export

Project Structure

Testing

Contributing

License

Troubleshooting

Missing Dependencies (pandas, numpy, cryptography, etc.)

"ModuleNotFoundError: No module named 'setuptools'"

"ImportError: attempted relative import with no known parent package"

Windows Path Issues

GUI Not Launching (Linux)

Kalshi RSA Key Issues

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages