polymarket-trading

name	polymarket-trading
description	Polymarket-specific terminology, trading strategies, and API reference.

Terminology & Concepts

• Exit Plan: Automated limit sell at $0.99 placed as soon as position opens.
• Hedged Reversal: Holding both UP and DOWN positions simultaneously when trend flips.
• Midpoint Stop Loss: Market sell triggered by midpoint price dropping to/below $0.30.
• Scale-In: Adding capital to winning positions via Market Orders (FAK).
• Underdog: Side trading below $0.50. Requires >40% confidence for entry.
• Tick Size: Minimum price increment allowed for a market (e.g., 0.01 or 0.001).

Strategy Nuances

Confidence Calculation Methods (v0.5.0+)

The bot supports two confidence calculation methods for A/B testing:

Additive Method (Default):

• Directional voting system with weighted signal aggregation
• Confidence = (winning_total - (losing_total × 0.2)) × lead_lag_bonus
• Trend agreement bonus (1.1x) when Binance and Polymarket momentum align

Bayesian Method (Alternative):

• Statistically principled probability theory using log-odds
• Starts with market prior from Polymarket orderbook
• Accumulates evidence via log-likelihood ratios:

  evidence = (score - 0.5) × 2  # Scale to -1 to +1
  log_LR = evidence × 3.0 × quality  # Quality factor (0.7-1.5x)
  log_odds += log_LR × weight
  confidence = 1 / (1 + exp(-log_odds))
  

• Naturally handles conflicting signals (they cancel out)
• Market prior anchors calculation to Polymarket reality

A/B Testing:

• Both methods calculated simultaneously on every trade
• Results stored in database for comparison
• Toggle via BAYESIAN_CONFIDENCE environment variable (default: NO)
• Compare win rates after 100+ trades:

  SELECT
      AVG(CASE WHEN bias='UP' THEN edge ELSE -edge END) as avg_edge,
      COUNT(*) as total,
      SUM(CASE WHEN result='WIN' THEN 1 ELSE 0 END) as wins,
      CAST(wins AS REAL) / COUNT(*) as win_rate
  FROM trades
  WHERE settled = 1
  GROUP BY method;
  

Exit Plan Optimization

• Smart Exit Pricing:
  • High confidence trades (≥85%): Use $0.999 exit price for maximum profit
  • Standard trades: Use $0.99 exit price (configurable via EXIT_PRICE_TARGET)
  • Only apply 0.999 for winning positions (UP side with price ≥ entry OR DOWN side with price ≤ entry)
• Immediate Placement: Exit plans placed immediately after position fill (no age requirement)
• Real-Time Size Validation: Exit order size validated every 1-second cycle
• Repair Logic:
  • Automatic repair if exit order size mismatches database size
  • Uses 0.05 share threshold to prevent infinite repair loops from exchange rounding
  • Cancels incorrect order and places new one with correct size
• Adoption Logic: Discovers and adopts existing SELL orders on exchange to prevent duplicates

Scale-In Strategy (Dynamic)

• Default SCALE_IN_TIME_LEFT: 450s (7.5 minutes)
• Dynamic early entry timing based on confidence (edge) and midpoint price:
  • 12m left: edge >= 90% and price >= $0.80
  • 9m left: edge >= 80% and price >= $0.70
  • 7m left: edge >= 70% and price >= $0.65
• Uses Market Orders (FAK) to ensure immediate fills
• Multiplier: 1.5x (adds 150% more capital, creating 2.5x total position)

Signal Bonuses

• Trend Agreement Bonus: 1.1x multiplier if Binance and Polymarket trends align
• Lead/Lag Bonus: 1.2x bonus or 0.8x penalty based on cross-exchange consistency

Technical Requirements

• Precision: Use strict 0.0001 threshold for balance syncing
• Minimum Size: Polymarket enforces a 5.0 share minimum for limit orders
• Rounding: Use truncate_float(value, 2) for all order sizes to match exchange precision

Fees & Rebates (15-Minute Crypto Markets)

• Taker Fees: Applied ONLY to 15-minute crypto markets.
• Fee Deduction:
  • BUY: Fee is taken in Tokens from the proceeds.
  • SELL: Fee is taken in USDC from the proceeds.
• Effective Rates:
  • Buying: Peaks at ~1.6% at $0.50 price.
  • Selling: Peaks at ~3.7% at $0.30 price. Selling is generally more expensive because USDC is taken directly.
• Fee Precision: Rounded to 4 decimal places (min 0.0001 USDC). Small trades at extremes might be fee-free.
• Maker Rebates: Distributed daily in USDC to makers who provide liquidity that gets filled.
• Strategy Implications:
  • Prefer Maker orders (Limit orders that add liquidity) to avoid fees and potentially earn rebates.
  • Selling at low prices as a taker is particularly costly.

Common Code Patterns

Market Data

from src.trading.orders import get_midpoint, get_spread, check_liquidity
# Get accurate midpoint price
price = get_midpoint(token_id)
# Check if liquidity is good
if check_liquidity(token_id, size=100, warn_threshold=0.05):
    # Safe to trade

Order Placement

from src.trading.orders import place_batch_orders, place_market_order
# Batch Orders
results = place_batch_orders(orders)
# Market Sell
result = place_market_order(token_id, amount=10.0, side="SELL", order_type="FAK")

Standard Emoji Guide

Position Monitoring

• 👀 Monitoring positions
• 📈 UP side position (winning if PnL positive)
• 📉 DOWN side position (winning if PnL positive)
• 📦 Position size display
• 🧮 PnL percentage display

Position Status

• ⏰ Exit plan active (limit sell order placed)
• ⏳ Exit plan pending (waiting for conditions)
• ⏭️ Exit skipped (position below MIN_SIZE threshold)
• 📊 Scaled in position indicator

Order Lifecycle

• 🚀 Trade execution / Entry
• 🎯 Limit order placement
• ✅ Success / Order filled
• 🧹 Order cancellation
• ❌ Error/Failure

Risk Management

• 🛑 Stop loss triggered
• 🔄 Reversal / Trend flip
• ⚠️ Warning / Validation issue
• 🔧 Position repair/sync

System

• 💰 Money/Balance/Settlement
• 🌍 Geographic restriction
• 🧟 Ghost trade detection