Polymarket — Бот исследований и торговли

Version 0.2.0 · MIT License · Python 3.9+

Ключевые возможности

Архитектура

The bot follows a modular pipeline architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────────────────┐
│                         CLI (Click) / Dashboard (Flask)             │
│  scan │ research │ forecast │ paper-trade │ trade │ engine │ dash   │
├───────┴──────────┴──────────┴─────────────┴───────┴────────┴───────┤
│                                                                     │
│  Connectors          Research             Forecast                  │
│  ┌──────────────┐    ┌───────────────┐    ┌───────────────────┐    │
│  │ Gamma API    │    │ Query Builder │    │ Feature Builder    │    │
│  │ CLOB API     │───▶│ Source Fetcher│───▶│ LLM Forecaster    │    │
│  │ Web Search   │    │ Evidence Ext. │    │ Ensemble (3 LLMs) │    │
│  │ WebSocket    │    └───────────────┘    │ Calibrator         │    │
│  │ Rate Limiter │                         └───────────────────┘    │
│  └──────────────┘                                │                  │
│                                                  ▼                  │
│  Policy                        Analytics                            │
│  ┌─────────────────────┐       ┌──────────────────────────┐        │
│  │ Edge Calculator     │       │ Regime Detector          │        │
│  │ Risk Limits (15)    │◀─────▶│ Calibration Feedback     │        │
│  │ Position Sizer      │       │ Adaptive Model Weights   │        │
│  │ Drawdown Manager    │       │ Smart Entry Calculator   │        │
│  │ Portfolio Risk      │       │ Wallet Scanner           │        │
│  │ Timeline Intel      │       └──────────────────────────┘        │
│  └─────────────────────┘                                            │
│            │                                                        │
│            ▼                                                        │
│  Execution                     Storage / Observability              │
│  ┌─────────────────────┐       ┌──────────────────────────┐        │
│  │ Order Builder        │       │ SQLite + WAL + Migrations│        │
│  │ Order Router (dry)   │       │ structlog JSON Logging   │        │
│  │ Fill Tracker         │       │ In-Process Metrics       │        │
│  │ Cancel Manager       │       │ Alerts (Telegram/Slack)  │        │
│  │ TWAP / Iceberg       │       │ JSON Run Reports         │        │
│  └─────────────────────┘       └──────────────────────────┘        │
└─────────────────────────────────────────────────────────────────────┘

Module Map

Торговый пайплайн

Every trading cycle follows this deterministic pipeline. Each step must succeed for the next to proceed:

Market Discovery & Classification

The bot discovers markets through Polymarket's Gamma REST API and automatically classifies them by keyword matching.

Scanning Filters

Market Type Classification

Markets are classified by matching keywords in the question text:

Pre-Research Filter

Before spending API credits on research, markets are scored (0-100) on volume, liquidity, recency, and category. Markets scoring below filter_min_score (default 25) are skipped. Markets of type UNKNOWN are blocked entirely.

Движок исследований

The research module implements a source-first, whitelisted search pipeline to ensure evidence comes from authoritative sources.

Query Strategy (4 phases)

Evidence Extraction

An LLM processes fetched sources to extract structured evidence. Every bullet must include:

{
  "text": "CPI-U increased 3.1% YoY in January 2026",
  "metric_name": "CPI-U YoY",
  "metric_value": "3.1",
  "metric_unit": "percent",
  "metric_date": "2026-01-31",
  "confidence": 0.97,
  "citation": {
    "url": "https://www.bls.gov/...",
    "publisher": "Bureau of Labor Statistics",
    "authority_score": 1.0
  }
}

Evidence Quality Scoring

Quality is computed independently of LLM self-assessment using:

• Source recency — Penalty for stale data (>7 days old, severe >30 days)
• Domain authority — Government sources score 1.0, news outlets 0.6-0.8
• Cross-source agreement — Multiple sources confirming the same metric
• Numeric density — Bonus for evidence with concrete numbers, dates, and units
• Contradiction detection — Conflicting sources reduce confidence

Search Providers

Blocked Domains

The following domains are always excluded: wikipedia.org, reddit.com, medium.com, twitter.com/x.com, quora.com, and other user-generated content sites.

Прогнозирование и ансамбль

The forecasting system queries multiple Large Language Models in parallel to produce probability estimates.

Ensemble Architecture

Aggregation Methods

• Trimmed Mean (default) — Removes the highest and lowest forecasts, averages the rest. Robust to outlier models.
• Median — Takes the middle forecast. Completely resistant to outliers.
• Weighted — Uses per-model weights (static or adaptive). Best when model quality is known.

Graceful Degradation

If some models fail (API errors, timeouts), the ensemble degrades gracefully. It requires min_models_required (default 1) to succeed. If all models fail, it falls back to a single-model query to fallback_model (default: GPT-4o).

Prompt Structure

Each model receives: the market question, market type, evidence summary, top evidence bullets, contradictions, and market features (volume, spread, implied probability, days to resolution). The model must return a probability (0-1), confidence level (LOW/MEDIUM/HIGH), reasoning, and invalidation triggers.

Adaptive Model Weights

The AdaptiveModelWeighter module tracks per-model, per-category Brier scores from resolved markets. It computes inverse-Brier weights so that models with better track records in a specific category receive more influence. Uses Bayesian smoothing to blend learned weights with priors, requiring 50+ samples for full confidence.

Калибровка

Raw LLM probabilities are systematically adjusted for better real-world calibration.

Platt Scaling (Default)

Applies logistic compression with shrinkage toward 0.5. This counteracts the tendency of LLMs to produce overconfident extreme probabilities.

Adjustments Applied

• Shrinkage — Extreme probabilities (>0.95 or <0.05) are pulled toward 0.5
• Low-Evidence Penalty — Up to 15% penalty when evidence quality is below threshold
• Contradiction Penalty — Each contradiction reduces confidence proportionally
• Ensemble Disagreement — Wide spread among models triggers additional shrinkage

Historical Calibration Learning

The CalibrationFeedbackLoop records every (forecast, outcome) pair when markets resolve. After 30+ samples, the bot trains a logistic regression to learn optimal calibration parameters from its own track record, becoming more accurate over time.

Расчёт Edge

Edge measures the difference between the bot's model probability and the market-implied probability.

Direction Logic

• If model_prob > implied_prob → BUY YES (the market underestimates probability)
• If model_prob < implied_prob → BUY NO (the market overestimates probability)

Transaction Costs

Costs include entry fees (transaction_fee_pct, default 2%) and gas costs. The bot uses a hold-to-resolution model (single-leg entry, no exit trade), so only entry costs are deducted.

Expected Value

EV per dollar = (model_prob × $1 − cost) / cost. Only positive net-EV trades pass risk checks.

Управление рисками

The risk engine enforces 15 independent checks. A trade is only allowed if ALL pass. Any single violation blocks the trade.

Position Sizing (Kelly Criterion)

Position sizes are computed using the fractional Kelly criterion with multiple adjustment layers.

Adjustment Multipliers

Caps

• max_stake_per_market — Hard cap per trade (default $50)
• max_bankroll_fraction — No trade exceeds 5% of bankroll
• Liquidity cap — Stake capped at 5% of available market liquidity

Drawdown Management

The drawdown system tracks the equity curve and progressively reduces risk during losing periods.

Heat Levels

Portfolio Risk Management

Portfolio-level constraints prevent over-concentration and correlated losses.

Исполнение ордеров

The execution layer builds orders and routes them through safety checks before submission.

Order Types

• Limit Orders — Default; placed at calculated price with TTL (default 300s)
• Market Orders — Immediate fill at current price; used for urgent entries
• TWAP — Time-Weighted Average Price; splits large orders into 5 slices over 30s intervals
• Iceberg — Hides order size; shows only 20% of total, refills as filled. Triggered at $500+ orders

Triple Dry-Run Gate

Smart Entry Timing

The SmartEntryCalculator calculates optimal entry levels using orderbook depth analysis, VWAP divergence, microstructure signals, and momentum. This can improve entry prices by 1-3% (10-30 basis points).

Position Exits

Continuous Trading Engine

The engine runs the full pipeline in a loop, coordinating all components autonomously.

Cycle (Default: every 3 minutes)

Between Cycles

• Check drawdown state and heat level
• Monitor position exits (stop-loss, take-profit, time-based, resolution)
• Scan whale wallet activity
• Detect market regime changes
• Persist engine state to DB for dashboard visibility

Analytics & Regime Detection

Market Regime Detector

Adapts strategy based on detected market conditions:

Calibration Feedback Loop

When markets resolve, the bot records (forecast_prob, actual_outcome) pairs and periodically retrains calibration. Per-model accuracy is tracked for adaptive weighting. This creates a self-improving system that gets more accurate over time.

Performance Tracking

The analytics module tracks: win rate, Brier score, Sharpe ratio, max drawdown, average edge, P&L by category, accuracy by confidence level, and more.

Whale / Smart-Money Scanner

The Whale Tracker is a comprehensive smart-money intelligence system that monitors the top 15 Polymarket leaderboard wallets and generates actionable signals. It provides real-time visibility into what the most profitable traders are doing.

Архитектура

The scanner runs on a 15-minute cycle within the bot's main engine loop:

• Phase 1 – Fetch: Queries positions for all 15 tracked wallets via the Data API (up to 200 positions each)
• Phase 2 – Score: Computes a composite quality score (0-100) per wallet based on P&L, win rate, and activity
• Phase 3 – Delta Detection: Compares current positions against the previous snapshot to identify new entries, exits, and size changes (>10% threshold)
• Phase 4 – Conviction Signals: Groups positions by market+outcome and generates conviction signals where 2+ whales agree

Smart Money Index (SMI)

A proprietary aggregate indicator (0-100) computed from all active whale signals, weighted by position size:

Conviction Scoring

Each market where 2+ whales hold the same outcome receives a conviction score (0-100):

Signal strength classification:

High Consensus Alerts

When 3+ whales agree on the same market outcome, a "High Consensus Alert" is triggered. These are the strongest smart money signals and appear as highlighted cards in the dashboard. The bot uses these for whale-edge convergence detection.

Чистый поток китов

Tracks aggregate capital entering vs. exiting whale positions:

• Flow In: Sum of $ from NEW_ENTRY and SIZE_INCREASE deltas
• Flow Out: Sum of $ from EXIT and SIZE_DECREASE deltas
• Net Flow: Flow In - Flow Out (positive = net accumulation, negative = net distribution)

Whale Tier System

Each tracked wallet is classified into a performance tier based on total P&L:

Delta Detection

Position changes tracked between scan cycles:

Dashboard Components

The Whale Tracker tab includes:

• 6 KPI Cards: Tracked Wallets, Conviction Signals, Smart Money Index, Net Whale Flow, Avg Win Rate, Top Conviction
• SMI Gauge: Visual gauge showing bullish/bearish sentiment with animated fill
• Flow Breakdown: Bar chart of entry/exit/increase/decrease activity
• Direction Distribution: Doughnut chart (bullish vs bearish signals)
• Top Markets by Whale Capital: Horizontal bar chart of most concentrated markets
• High Consensus Alerts: Highlighted cards for 3+ whale agreement
• Conviction Signals Table: Filterable table with conviction progress bars
• Live Activity Feed: Styled event feed of whale moves with icons
• Whale Leaderboard: Card-based leaderboard with tiers, scores, and activity counts

Edge Integration

Database Tables

API Endpoint

Returns: tracked_wallets, conviction_signals, recent_deltas, high_consensus_signals, top_markets, and summary (including SMI, net flow, direction distribution, action breakdown, tier enrichment).

Decision Intelligence Log

A comprehensive audit trail of every decision the engine makes, from market scanning through trade execution. Provides full transparency into the AI's reasoning process.

What Gets Logged

• SCAN: Market discovery and initial filtering decisions
• RESEARCH: Evidence gathering, source quality, query construction
• FORECAST: Probability estimates from individual models and the ensemble
• EDGE: Edge calculations — market price vs. forecast probability
• RISK: Risk check passes/failures (drawdown, exposure, position limits)
• SIZE: Position sizing decisions (Kelly fraction, scaling)
• EXECUTE: Order submission, fill tracking, simulated execution
• MONITOR: Position monitoring, TP/SL proximity, exit triggers

Dashboard Tab Features

• Real-time feed of all decisions with timestamps
• Color-coded decision types (TRADE, NO_TRADE, SKIP, ERROR)
• Filter by stage (SCAN, RESEARCH, FORECAST, etc.)
• Search across all decision fields
• Integrity verification via SHA-256 hashes
• Summary cards: total decisions, trade rate, top categories

API Endpoint

Returns: entries (decision records with id, market_id, decision, stage, details, integrity_hash, timestamp), summary (total, by_stage breakdown, by_decision breakdown, recent_rate).

Data Integrity

Each decision entry includes a SHA-256 integrity_hash computed from the decision data, ensuring the audit trail cannot be tampered with. The dashboard shows a ✅ indicator for verified entries.

Стратегии и кошельки

A portfolio management system for organizing trading activity across multiple wallets and strategies, enabling multi-strategy allocation and performance tracking.

Core Concepts

Database Tables

API Endpoints

Dashboard Tab

The Strategies tab provides a visual interface to:

• View all wallets with balance, P&L, status, and linked strategies
• View all strategies with risk levels, descriptions, and linked wallets
• Create, edit, and delete wallets and strategies via modal dialogs
• Bind/unbind strategies to wallets with allocation percentages
• Summary cards showing total capital, active wallets, total P&L, and average allocation

API коннекторы

Gamma API (Market Discovery)

The GammaClient connects to Polymarket's public market-listing API at https://gamma-api.polymarket.com. Used for: listing markets, fetching metadata (question, category, end date, resolution source), and getting pricing snapshots.

CLOB API (Orderbook & Trading)

The CLOBClient connects to https://clob.polymarket.com for real-time orderbook data (bids/asks), trade history, spread calculations, and order placement via the py-clob-client signing library.

WebSocket Feed

The WebSocketFeed subscribes to real-time price ticks for monitored markets, providing live data for the dashboard and microstructure analysis.

Rate Limiter

A global rate limiter prevents API abuse with configurable per-endpoint limits and automatic backoff on 429 responses.

Хранилище и БД

All data is persisted in a SQLite database with WAL (Write-Ahead Logging) mode for concurrent reads.

Tables

Migrations

Schema is managed through numbered migrations (currently 10). Migrations run automatically on startup, ensuring the database schema stays in sync with the code. Each migration is idempotent and includes proper error handling.

Backup

Database backups can be triggered from the Admin Panel. Backups are stored as timestamped copies in the data/ directory.

Наблюдаемость

Structured Logging (structlog)

All logs use JSON-structured format via structlog. Sensitive data (API keys, private keys) is automatically redacted by a custom log processor. Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL.

In-Process Metrics

The metrics module tracks counters, gauges, and histograms in-memory:

• orders.simulated, orders.submitted, orders.filled
• forecasts.total, forecasts.trade, forecasts.no_trade
• risk.violations, risk.kills
• api.calls, api.errors, api.latency_ms

Cost Tracking

LLM and search API costs are tracked per-provider with running totals visible in the Admin Panel. Includes token counts and estimated USD costs for OpenAI, Anthropic, Google, and search providers.

JSON Run Reports

Each engine cycle produces a JSON report saved to reports/ with full pipeline details.

Sentry Integration

Optional error tracking via Sentry SDK. Configure with SENTRY_DSN environment variable.

Алерты и уведомления

Multi-channel alerting for critical events:

Alert Triggers

• Trade executions (paper and live)
• Large P&L moves
• Drawdown warnings and kill switch activations
• Risk limit breaches
• System errors
• Daily summary (configurable hour, default 6pm)

Руководство по дашборду

The web dashboard provides a real-time view of all bot operations, accessible at http://localhost:2345.

Tabs Overview

Authentication

Set DASHBOARD_API_KEY in your .env file. Access the dashboard with the API key as a header (X-API-Key) or query parameter (?api_key=...). If no key is set, the dashboard runs in open-access mode.

Auto-Refresh

Обновление каждые 15 сек — только для активной вкладки, чтобы минимизировать нагрузку на API.

Справочник конфигурации

All configuration is managed via config.yaml with environment variable overrides. The dashboard Admin Panel provides a visual config editor.

CLI команды

The bot is controlled via the bot CLI (Click-based). Entry point: src.cli:cli.

Quick Start

# Install
git clone <repo-url> polymarket-bot
cd polymarket-bot
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Configure
cp .env.example .env
# Edit .env with API keys: OPENAI_API_KEY, TAVILY_API_KEY, etc.

# Run
bot scan --limit 20                    # Discover markets
bot forecast --market <CONDITION_ID>   # Full forecast pipeline
bot dashboard                          # Launch web UI on :2345

Безопасность

Safety Mechanisms

• Triple dry-run gate — Three independent flags must all allow live trading
• Kill switch — Instant halt, accessible from CLI, config, and dashboard
• Auto-kill on max drawdown — Prevents catastrophic losses
• 15 independent risk checks — All must pass for any trade
• Position limits — Per-trade, per-category, and portfolio-wide caps

Security Practices

• API keys loaded from environment only, never committed to code
• Private keys automatically redacted in structlog output
• Dashboard auth via API key header or query parameter
• Docker — Runs as non-root user in container
• Audit trail — All admin actions and config changes logged to database

Развёртывание

Local Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
bot dashboard

Docker

docker compose build
docker compose up -d          # Runs dashboard + engine
docker compose logs -f        # Follow logs

Environment Variables

Testing

pytest                                   # Run all tests
pytest --cov=src --cov-report=term       # With coverage
pytest tests/test_policy.py -v           # Specific test file
mypy src/                                # Type checking
ruff check src/ tests/                   # Linting

Глоссарий