name: boeingchoco-polymarket-ai-divergence
description: "Find markets where Simmer's AI consensus diverges from the real market price, then trade on the mispriced side using calibration-shrunk Kelly sizing. Scans for divergence, applies AI-overconfidence shrinkage, liquidity / spread / time-to-resolution safeguards, and executes trades on zero-fee markets with sufficient surviving edge."
metadata:
author: Simmer (@simmer_markets)
version: "2.6.1"
displayName: Polymarket AI Divergence
difficulty: intermediate
openclaw:
emoji: "🔮"
primaryEnv: SIMMERAPIKEY
requires:
anyBins:

• python3
• python

env:

• SIMMERAPIKEY

install:

• id: uv-simmer-sdk

kind: uv
package: "simmer-sdk>=0.11.1"
label: "Install Simmer SDK (uv)"

Polymarket AI Divergence Trader

Find markets where Simmer's AI consensus diverges from the real market price, then trade the edge — defensively.

This is a template. v2.6 defaults trade when the calibrated edge survives 3% (raw divergence × source/adaptive shrinkage − fees − 1% slippage buffer − optional longshot penalty), on zero-fee Polymarket markets with ≥ $1k liquidity, ≥ $500 24h volume, ≥ 6h to resolution, ≤ 180d to resolution, top-of-book depth ≥ $250, and where the half-spread eats < 50% of the edge. Position size is fractional Kelly (cap 0.20), capped at 5% of market liquidity and 20% of top-of-book depth, scaled by sqrt(days_to_resolve / 30), then adjusted by category-aware Kelly multipliers. Remix any of these (see Configuration). The skill handles plumbing — your agent provides the alpha.

What's new in v2.6 (category-aware sizing)

v2.6 adds a category-aware Kelly multiplier. Research (Kalshibench, QuantPedia 2025) shows AI consensus alpha is heterogeneous across Polymarket categories:

• Politics & crypto are dominated by professional bot flow → AI edge is small but cleaner → multiplier 0.60
• Sports has more retail noise → AI edge is larger and less compressed → multiplier 0.85
• Niche / long-tail (default bucket) is where AI most outperforms market consensus → multiplier 0.75

Set category_multipliers_csv to remix, e.g. "politics=0.5,crypto=0.5,sports=0.9,weather=1.0,default=0.7". Disable with SIMMER_DIVERGENCE_ENABLE_CATEGORY_MULTIPLIER=0.

Also in v2.6: the structured automaton report now includes a skip_reason_counts histogram so operators can tell which safeguard is doing most of the filtering and tune the right knob.

What's new in v2.5 (research-backed)

v2.5 adds source-aware and adaptive calibration shrinkage on top of v2.4. Instead of using one fixed shrinkage for every market, the strategy now starts with a signal-source-specific shrinkage (oracle_shrinkage=0.65, crowd_shrinkage=0.80) and then shrinks edge harder in stress regimes:

• high 1-day price-move markets (one_day_price_change) where short-term volatility and narrative whipsaw are elevated
• thinner-liquidity markets near the floor where executable alpha is less reliable
• low-probability contracts where favorite-longshot bias is structurally expensive
• thin top-of-book markets where fills are likely to move the price

This is controlled by:

• oracle_shrinkage (default 0.65)
• crowd_shrinkage (default 0.80)
• enable_adaptive_shrinkage (default 1)
• adaptive_shrinkage_vol_mult (default 1.25)
• longshot_threshold (default 0.15)
• longshot_penalty_bps (default 75)
• slippage_buffer_pct (default 0.01)
• min_top_book_depth_usd (default 250)

The goal is simple: fewer false positives, higher realized edge per executed trade.

What changed in v2.4 (research-backed)

Independent research showed AI forecasters are systematically overconfident (Kalshibench: even Claude Opus shows ECE ≈ 0.12) and that 87% of Polymarket wallets lose money primarily to position-size mistakes, not bad predictions. v2.4 adds seven safeguards designed to address those failure modes:

1. AI calibration shrinkage — multiply the raw AI − market divergence by ai_shrinkage (default 0.70) before treating it as edge.
2. Liquidity floor — skip Polymarket markets with on-book liquidity below min_liquidity_usd (default $1k).
3. Volume floor — skip markets with 24h volume below min_volume_24h_usd (default $500) to avoid stale prices.
4. Time-to-resolution band — skip markets resolving in less than min_hours_to_resolve (default 6h, terminal-volatility / oracle risk) or more than max_days_to_resolve (default 180d, capital opportunity cost).
5. Extreme-divergence sanity cap — skip divergences above max_divergence_sanity (default 40%) as likely stale data or broken oracles.
6. CLOB spread check — fetch the YES/NO orderbook from clob.polymarket.com and skip if the half-spread exceeds max_spread_pct_of_edge (default 50%) of the calibrated edge. Use the crossing price (not the stale external price) for Kelly sizing.
7. Liquidity / depth-aware position cap — position is capped at max_position_pct_liquidity × on-book liquidity (default 5%) and 20% of top-of-book depth.
8. Time-decay sizing — multiply final position by sqrt(days_to_resolve / 30), capped at 1.0, so a 7-day market takes ~48% of a 30-day-equivalent position.

1. Tradable-price band — skip markets with crossing price outside min_price..max_price (defaults 3%..97%) to avoid favorite/longshot tails where calibration degrades.
2. Minimum expected edge in dollars — require position_size × edge >= min_expected_profit_usd (default $0.10) so tiny, noisy bets are skipped.

Together these typically cut trade count by 30–60% but raise per-trade expected value materially. All knobs can be tuned or turned off (SIMMER_DIVERGENCE_ENABLE_SPREAD_CHECK=0, etc.) for traders who want v2.3 behavior.

What's new in v2.5 (execution + calibration upgrade)

1. Source-aware calibration — distinct shrinkage per signal source (oracle_shrinkage=0.65, crowd_shrinkage=0.80) because AI-oracle and crowd-flow signals have different error profiles.
2. Longshot-bias penalty — optional additional edge haircut on low-probability contracts (longshot_threshold=0.15, longshot_penalty_bps=75) to avoid structurally expensive tails.

What It Does

1. Scans all active markets for AI vs market price divergence
2. Calibrates by shrinking raw divergence toward zero to correct for AI overconfidence
3. Filters to markets with calibrated edge above threshold (default 3%), zero fees, sufficient liquidity / volume, and a reasonable time-to-resolution band
4. Checks safeguards (flip-flop detection, existing positions, spread, top-of-book depth, sanity caps)
5. Sizes using fractional Kelly (cap 0.20), capped at 5% of liquidity & 20% of top-of-book, time-decayed by √(days/30)
6. Executes trades on the mispriced side using the actual orderbook crossing price (YES when AI is bullish, NO when bearish)

Setup Flow

When user asks to install or configure this skill:

1. Install the Simmer SDK

   python -m pip install "simmer-sdk>=0.11.1"

1. Ask for Simmer API key

• They can get it from simmer.markets/dashboard → SDK tab
• Store in environment as SIMMER_API_KEY

1. Ask for wallet private key (only for external-wallet self-custody trading)

• This is the private key for their Polymarket wallet (the wallet that holds USDC)
• Store in environment as WALLET_PRIVATE_KEY
• The SDK uses this to sign orders client-side automatically — no manual signing needed
• Not needed for managed wallets or $SIM paper trading on the Simmer venue

Quick Commands

# Scan only (dry run, no trades)
python ai_divergence.py

# Scan + execute trades
python ai_divergence.py --live

# Only show bullish divergences
python ai_divergence.py --bullish

# Only >15% divergence
python ai_divergence.py --min 15

# JSON output
python ai_divergence.py --json

# Cron mode (quiet, trades only)
python ai_divergence.py --live --quiet

# Show config
python ai_divergence.py --config

# Update config
python ai_divergence.py --set max_bet_usd=10

Configuration

| Key | Env Var | Default | Description |
|-----|---------|---------|-------------|
| min_divergence | SIMMER_DIVERGENCE_MIN | 5.0 | Min divergence % for scanner display |
| min_edge | SIMMER_DIVERGENCE_MIN_EDGE | 0.03 | Min calibrated edge to trade after shrinkage + fees |
| max_bet_usd | SIMMER_DIVERGENCE_MAX_BET_USD | 5.0 | Max bet per trade |
| max_trades_per_run | SIMMER_DIVERGENCE_MAX_TRADES_PER_RUN | 3 | Max trades per cycle |
| kelly_cap | SIMMER_DIVERGENCE_KELLY_CAP | 0.20 | Fractional Kelly cap |
| daily_budget | SIMMER_DIVERGENCE_DAILY_BUDGET_USD | 25.0 | Daily spend limit |
| default_direction | SIMMER_DIVERGENCE_DIRECTION_FILTER | (both) | Filter: "bullish" or "bearish" |
| ai_shrinkage | SIMMER_DIVERGENCE_AI_SHRINKAGE | 0.70 | Multiplier on raw AI − market divergence |
| min_liquidity_usd | SIMMER_DIVERGENCE_MIN_LIQUIDITY_USD | 1000 | Min Polymarket on-book liquidity (USD) |
| min_volume_24h_usd | SIMMER_DIVERGENCE_MIN_VOLUME_24H_USD | 500 | Min 24h volume (USD) |
| max_position_pct_liquidity | SIMMER_DIVERGENCE_MAX_POS_PCT_LIQ | 0.05 | Max position as fraction of market liquidity |
| min_hours_to_resolve | SIMMER_DIVERGENCE_MIN_HOURS_TO_RESOLVE | 6 | Skip markets resolving within this many hours |
| max_days_to_resolve | SIMMER_DIVERGENCE_MAX_DAYS_TO_RESOLVE | 180 | Skip markets beyond this many days |
| max_divergence_sanity | SIMMER_DIVERGENCE_MAX_DIV_SANITY | 0.40 | Skip suspiciously extreme divergences |
| max_spread_pct_of_edge | SIMMER_DIVERGENCE_MAX_SPREAD_PCT_EDGE | 0.50 | Skip if half-spread > this share of edge |
| enable_spread_check | SIMMER_DIVERGENCE_ENABLE_SPREAD_CHECK | 1 | 1 = check CLOB spread; 0 = skip |
| enable_time_decay | SIMMER_DIVERGENCE_ENABLE_TIME_DECAY | 1 | 1 = sqrt(days/30) sizing; 0 = constant |
| min_price | SIMMER_DIVERGENCE_MIN_PRICE | 0.03 | Skip trades below this crossing price (longshot tail) |
| max_price | SIMMER_DIVERGENCE_MAX_PRICE | 0.97 | Skip trades above this crossing price (favorite tail) |
| min_expected_profit_usd | SIMMER_DIVERGENCE_MIN_EXPECTED_PROFIT_USD | 0.10 | Minimum size × edge before a trade is allowed |
| enable_adaptive_shrinkage | SIMMER_DIVERGENCE_ENABLE_ADAPTIVE_SHRINKAGE | 1 | 1 = volatility/liquidity-aware shrinkage of AI edge |
| adaptive_shrinkage_vol_mult | SIMMER_DIVERGENCE_ADAPTIVE_SHRINK_VOL_MULT | 1.25 | Liquidity stress multiplier used by adaptive shrinkage |
| oracle_shrinkage | SIMMER_DIVERGENCE_ORACLE_SHRINKAGE | 0.65 | Shrinkage for signal_source=oracle |
| crowd_shrinkage | SIMMER_DIVERGENCE_CROWD_SHRINKAGE | 0.80 | Shrinkage for signal_source=crowd |
| longshot_threshold | SIMMER_DIVERGENCE_LONGSHOT_THRESHOLD | 0.15 | Contracts below this price are treated as longshots |
| longshot_penalty_bps | SIMMER_DIVERGENCE_LONGSHOT_PENALTY_BPS | 75 | Extra edge haircut for longshots (bps) |
| slippage_buffer_pct | SIMMER_DIVERGENCE_SLIPPAGE_BUFFER_PCT | 0.01 | Conservative execution-cost buffer subtracted from edge before Kelly |
| min_top_book_depth_usd | SIMMER_DIVERGENCE_MIN_TOP_BOOK_DEPTH_USD | 250 | Skip when top-of-book depth is too thin for reliable fills |
| category_multipliers_csv | SIMMER_DIVERGENCE_CATEGORY_MULTIPLIERS | politics=0.60,crypto=0.60,sports=0.85,default=0.75 | Per-category Kelly multipliers |
| enable_category_multiplier | SIMMER_DIVERGENCE_ENABLE_CATEGORY_MULTIPLIER | 1 | 1 = apply category multipliers; 0 = treat all the same |

Update via CLI: python ai_divergence.py --set max_bet_usd=10

How It Works

Divergence Signal

Each imported market has two prices:

• AI consensus (current_probability) — Simmer's AI consensus price, derived from multi-model ensemble forecasting
• External price (external_price_yes) — Real market price on Polymarket/Kalshi

raw_divergence  = AI consensus - external price
source_shrink   = oracle_shrinkage | crowd_shrinkage | ai_shrinkage
effective_shrink= source_shrink × adaptive market-quality multipliers
calibrated_edge = raw_divergence × effective_shrink
tradeable_edge  = calibrated_edge − fee_pct − slippage_buffer_pct − optional_longshot_penalty

We trade only when |tradeable_edge| ≥ min_edge (default 3%).

When calibrated edge > 0 → buy YES. When calibrated edge < 0 → buy NO.

Kelly Sizing

Position size uses the fractional Kelly criterion on the calibrated edge:

kelly_fraction = tradeable_edge / (1 - crossing_price)
size           = clamp(kelly_fraction, 0, kelly_cap) * max_bet_usd
size           = min(size,
                     max_position_pct_liquidity * gamma_liquidity,
                     0.20 * top_of_book_depth_usd)
size          *= sqrt(days_to_resolve / 30)              # capped at 1.0

Capped at kelly_cap (default 0.20). Research consistently shows that full Kelly fails under estimation error — quarter / fifth Kelly is industry standard for AI-driven strategies.

Fee Filtering

75% of Polymarket markets have 0% fees. The remaining 25% charge 10% (short-duration crypto/sports). The skill subtracts the fee from the calibrated edge and skips trades where the residual falls below min_edge, so fee-heavy markets are filtered automatically.

Safeguards (v2.5)

• Fee + slippage check: Skips when calibrated edge − fee − slippage buffer < min_edge
• Flip-flop detection: Uses SDK's context API to detect contradictory trades
• Position check: Skips markets where you already hold a position
• Daily budget: Stops trading when daily spend limit is reached
• Source/adaptive calibration shrinkage: Multiplies raw divergence by source and market-quality shrinkage to correct for systematic AI overconfidence
• Longshot penalty: Haircuts low-price contracts before Kelly sizing
• Liquidity + volume floors: Skips polymarket-sourced markets below thresholds (stale prices, no execution)
• Time-to-resolution band: Skips < 6h (terminal volatility / oracle risk) and > 180d (capital lock-up)
• Sanity divergence cap: Skips raw divergences > 40% (almost always stale data / broken oracle)
• CLOB spread guard: Skips when half-spread > 50% of edge; uses real crossing price for Kelly
• Top-of-book depth floor + depth-aware sizing: Requires sufficient depth, then caps at 5% of book liquidity and 20% of top-of-book depth
• Time-decay sizing: position × sqrt(days_to_resolve / 30) so near-term bets shrink automatically

API Endpoints Used

• GET /api/sdk/markets/opportunities — Divergence-ranked market list
• GET /api/sdk/context/{market_id} — Fee rate and safeguards per market
• POST /api/sdk/trade — Trade execution (via SDK client)
• GET /api/sdk/positions — Current portfolio positions

Troubleshooting

"No markets above min edge threshold"
→ All divergences are below the min_edge setting. Lower it with --set min_edge=0.01 or wait for larger divergences.

"Daily budget exhausted"
→ The skill has hit its daily spend limit. Adjust with --set daily_budget=50.

All markets skipped for fees
→ Only zero-fee markets are traded. If all available divergence opportunities have fees, no trades execute. This is by design.

"context fetch failed"
→ The SDK context endpoint is rate-limited (18 req/min). If running frequently, reduce max_trades_per_run.