DISCLAIMER: This software is for educational and research purposes only. Trading prediction markets involves substantial risk of loss. This is not financial advice. Do your own research, comply with all applicable laws, and never risk capital you cannot afford to lose. You are solely responsible for securing your private keys and wallet funds.

polymarket-endcycle-sniper is a production-grade Python bot that scans Polymarket for tail-end / endcycle sniper opportunities — markets nearing resolution where heavily favored outcomes (typically priced $0.88–$0.98) may still offer small but consistent positive expected value when held to resolution.

Prediction markets converge toward $0 or $1 as resolution approaches. In the final days/hours of a market's lifecycle, the dominant outcome often trades at $0.88–$0.98 — implying 88–98% probability. The endcycle sniper strategy buys these favored outcomes and holds to resolution, capturing the remaining 2–12% edge when the market resolves as expected.

This bot automates:

1. Discovery — Scan active markets resolving within a configurable window (default: 0–7 days)
2. Filtering — Apply liquidity, spread, volume, and probability thresholds
3. Scoring — Rank opportunities by conviction (probability × edge × liquidity)
4. Execution — Place limit buy orders slightly below best ask via CLOB V2
5. Risk management — Position sizing, exposure limits, daily loss caps, cooldowns
6. Audit — Full SQLite logging of every opportunity and trade

Safe by default: dry-run mode is enabled out of the box. No real orders are placed until you explicitly disable it.

Example: A market "Will X happen by July 15?" resolves in 3 days. "Yes" trades at $0.93 ask. Buying at $0.92 limit yields ~8.7% ROI if Yes resolves ($1.00 payout). Win rate is high but losses on wrong calls are large — hence strict position sizing.

• Hold to resolution for the small percentage edge
• Limit orders below ask to improve entry
• Diversify across multiple markets
• Risk-first — one bad tail-end loss can wipe many small wins

• Professional Typer + Rich CLI (scan, run, backtest, positions, config, health)
• Gamma API market discovery with end-date filtering
• CLOB V2 order book + order placement via py-clob-client-v2
• Pydantic v2 typed models throughout
• SQLite persistence for opportunities, trades, and PnL
• YAML + .env configuration
• Paper trading / dry-run mode (default ON)
• Telegram alerts (optional)
• Structured logging with rotation (loguru)
• Backtesting module (proxy replay)
• Risk management — position limits, daily loss, cooldowns
• Graceful shutdown on SIGINT/SIGTERM

sequenceDiagram
    participant CLI
    participant Scanner
    participant Gamma
    participant CLOB
    participant Analyzer
    participant Executor
    participant DB

    CLI->>Scanner: scan / run
    Scanner->>Gamma: GET /markets (endDate filter)
    Gamma-->>Scanner: market metadata + clobTokenIds
    loop Each candidate
        Scanner->>CLOB: get_order_book(token_id)
        CLOB-->>Scanner: bids / asks
        Scanner->>Analyzer: score opportunity
        Analyzer-->>Scanner: ScoredOpportunity
    end
    Scanner->>Executor: approved opportunities
    Executor->>Executor: risk checks
    Executor->>CLOB: place_limit_buy (or dry-run log)
    Executor->>DB: save trade + audit log

See docs/architecture.md for full system design.

• Python 3.12+
• A Polymarket account with funded wallet (for live trading only)
• Polygon mainnet wallet private key (for live trading only)

# Clone the repository
git clone https://github.com/your-org/polymarket-endcycle-sniper.git
cd polymarket-endcycle-sniper

# Create virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Install with dev dependencies
pip install -e ".[dev]"

# Copy environment template
cp .env.example .env

# Initialize database
polymarket-sniper init-db

Edit .env — keep DRY_RUN=true for testing:

DRY_RUN=true
POLYMARKET_PRIVATE_KEY=          # Only needed for live trading
POLYMARKET_FUNDER_ADDRESS=       # Deposit wallet address (type 3)
POLYMARKET_SIGNATURE_TYPE=3

polymarket-sniper scan

polymarket-sniper scan --execute

polymarket-sniper run

polymarket-sniper positions

DRY_RUN=false

polymarket-sniper run --execute

Warning: Live trading uses real funds. Start with minimal position sizes in config/default.yaml.

strategy:
  end_window_max_days: 7
  min_implied_probability: 0.88
  max_spread: 0.05
  min_edge_pct: 0.015

risk:
  max_position_size_usd: 50
  max_concurrent_positions: 5
  max_daily_loss_usd: 100

Override with custom path: SNIPER_CONFIG_PATH=/path/to/custom.yaml

View merged config:

polymarket-sniper config

# Scan with JSON output for scripting
polymarket-sniper scan --json | jq '.[0]'

# Run bot with 3-minute scan interval
polymarket-sniper run --interval 180

# Backtest over 14 days
polymarket-sniper backtest --days 14

# Run example backtest script
python scripts/example_backtest.py

• Lower min_implied_probability to 0.85
• Increase end_window_max_days to 14
• Lower min_edge_pct to 0.01
• Increase max_position_size_usd

• Raise min_implied_probability to 0.92
• Shorten end_window_max_days to 3
• Tighten max_spread to 0.02
• Lower max_concurrent_positions to 2
• Increase min_volume_usd and min_liquidity_usd

THIS SOFTWARE CAN LOSE MONEY. USE AT YOUR OWN RISK.

• Not financial advice — for research and automation only
• Tail-end losses are asymmetric — a $0.95 bet that loses costs ~19× a typical win
• Private key security — never commit .env, use a dedicated trading wallet
• Regulatory compliance — ensure prediction market trading is legal in your jurisdiction
• No guarantees — past performance does not predict future results
• Smart contract / API risk — Polymarket infrastructure may change without notice

Built-in safeguards:

• Dry-run default
• Max position size per trade
• Max concurrent markets
• Daily loss limit with cooldown
• Full audit trail in SQLite + logs

polymarket-sniper backtest --days 30

The backtest module replays current market conditions as a proxy — it does not have historical order book archives. Use it for strategy calibration, not performance guarantees.

For production backtesting, integrate archived CLOB snapshots or the Polymarket Data API trade history.

Structured logs write to stderr and logs/sniper.log (rotating, 10 MB, 30-day retention).

TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

Alerts fire on: new opportunities, fills, and errors (configurable in config/default.yaml).

polymarket-endcycle-sniper/
├── README.md
├── .env.example
├── pyproject.toml
├── config/default.yaml
├── src/polymarket_sniper/
│   ├── config.py          # YAML + env settings
│   ├── models.py          # Pydantic domain models
│   ├── gamma_client.py    # Async Gamma API
│   ├── clob_wrapper.py    # CLOB V2 wrapper
│   ├── scanner.py         # End-of-cycle scanner
│   ├── analyzer.py        # Opportunity scoring
│   ├── executor.py        # Order execution + risk
│   ├── database.py        # SQLite persistence
│   ├── alerts.py          # Telegram notifications
│   ├── backtest.py        # Backtest module
│   ├── utils.py           # Logging, helpers
│   └── main.py            # Typer CLI
├── tests/
├── scripts/example_backtest.py
└── docs/architecture.md

1. Fork the repository
2. Create a feature branch
3. Add tests for new logic
4. Run pytest and ruff check .
5. Submit a pull request

MIT License — see LICENSE for details.

TRADING INVOLVES SUBSTANTIAL RISK OF LOSS AND IS NOT SUITABLE FOR EVERY INVESTOR. The authors and contributors of this project are not registered financial advisors. This software is provided "as is" without warranty of any kind. By using this software, you acknowledge that you are solely responsible for any financial losses, legal compliance, and security of your private keys and funds. Never trade with money you cannot afford to lose.