Merge pull request #15 from mlsys-io/claude/polymarket-event-trading-7BkpS

Integrate Polymarket event contract trading and backtesting

Author: tjluyao

alpha/PolymarketFactors.py

@@ -0,0 +1,82 @@
+"""Alpha factors for Polymarket event contract analysis.
+
+Polymarket contracts are probability-priced [0, 1] binary outcomes.
+Traditional momentum/mean-reversion indicators need adaptation:
+- Prices are bounded, so unbounded indicators can mislead
+- Probability space means RSI-like indicators are natural fits
+- Volume spikes often precede resolution or major news
+- Complementary contracts (YES+NO=1) create natural arbitrage signals
+"""
+
+import numpy as np
+from pandas import DataFrame
+
+from alpha.interface import IAlpha
+
+
+class PolymarketAlpha(IAlpha):
+    """Alpha factors tailored for binary outcome prediction market contracts.
+
+    Indicators produced:
+    - prob_momentum: Rate of probability change (smoothed)
+    - prob_rsi: RSI adapted for probability space
+    - volume_surge: Volume relative to rolling average (news detection)
+    - prob_zscore: Z-score of current price vs rolling window
+    - mean_reversion_signal: Distance from rolling mean (mean-reversion)
+    - resolution_proximity: How close price is to 0 or 1 (conviction signal)
+    - prob_ema_fast: Fast EMA of probability
+    - prob_ema_slow: Slow EMA of probability
+    """
+
+    def __init__(self, dataframe: DataFrame, metadata: dict = {}):
+        self.fast_period = 12
+        self.slow_period = 26
+        self.rsi_period = 14
+        self.zscore_period = 20
+        self.volume_period = 20
+        super().__init__(dataframe, metadata)
+
+    def process(self) -> DataFrame:
+        df = self.dataframe
+
+        close = df["close"]
+
+        # --- Probability EMAs ---
+        df["prob_ema_fast"] = close.ewm(span=self.fast_period, adjust=False).mean()
+        df["prob_ema_slow"] = close.ewm(span=self.slow_period, adjust=False).mean()
+
+        # --- Probability Momentum ---
+        # Rate of change in probability, smoothed
+        df["prob_momentum"] = close.diff(5).rolling(3).mean()
+
+        # --- RSI in probability space ---
+        delta = close.diff()
+        gain = delta.clip(lower=0).rolling(self.rsi_period).mean()
+        loss = (-delta.clip(upper=0)).rolling(self.rsi_period).mean()
+        rs = gain / loss.replace(0, np.nan)
+        df["prob_rsi"] = 100 - (100 / (1 + rs))
+        df["prob_rsi"] = df["prob_rsi"].fillna(50)
+
+        # --- Volume Surge ---
+        # Ratio of current volume to rolling average; >2 suggests news
+        mean_vol = df["volume"].rolling(self.volume_period).mean()
+        df["volume_surge"] = df["volume"] / mean_vol.replace(0, 1)
+
+        # --- Z-score of probability ---
+        rolling_mean = close.rolling(self.zscore_period).mean()
+        rolling_std = close.rolling(self.zscore_period).std()
+        df["prob_zscore"] = (close - rolling_mean) / rolling_std.replace(0, np.nan)
+        df["prob_zscore"] = df["prob_zscore"].fillna(0)
+
+        # --- Mean reversion signal ---
+        # Distance from rolling mean, normalized. Positive = above mean
+        df["mean_reversion_signal"] = close - rolling_mean
+
+        # --- Resolution proximity ---
+        # How close to 0 or 1: min(price, 1-price). Low = high conviction
+        df["resolution_proximity"] = np.minimum(close, 1 - close)
+
+        # --- Volume-weighted mean volume for volume filter ---
+        df["mean_volume"] = mean_vol
+
+        return df

freqtrade/exchange/__init__.py

@@ -48,4 +48,5 @@
 from freqtrade.exchange.luno import Luno
 from freqtrade.exchange.modetrade import Modetrade
 from freqtrade.exchange.okx import Myokx, Okx, Okxus
+from freqtrade.exchange.polymarket import Polymarket
 from freqtrade.exchange.portfoliobench import Portfoliobench

freqtrade/exchange/common.py

@@ -65,6 +65,7 @@ def _get_logging_mixin():
     "kraken",
     "okx",
     "myokx",
+    "polymarket",
     "portfoliobench",
 ]
 

freqtrade/exchange/polymarket.py

@@ -0,0 +1,161 @@
+"""Polymarket exchange subclass for event contract trading.
+
+Extends the Portfoliobench exchange to support Polymarket binary outcome
+contracts (YES/NO shares priced $0–$1) for backtesting prediction market
+strategies.
+
+Key differences from crypto/stock trading:
+  - Prices are bounded [0, 1] representing probability of an outcome
+  - Each event has two complementary contracts: YES + NO (prices sum to ~$1)
+  - Contracts settle at exactly $0 or $1 at resolution
+  - There is no "volume" in the traditional sense; liquidity comes from the CLOB
+  - Profit = (settlement_price - entry_price) * shares
+
+Pair convention:  {EVENT_SLUG}-{YES|NO}/USDT
+  e.g. "TRUMP-WIN-YES/USDT", "ETH-10K-NO/USDT"
+"""
+
+import logging
+from copy import deepcopy
+from typing import Any
+
+import ccxt
+
+from freqtrade.exchange.portfoliobench import Portfoliobench
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Contract type constants
+# ---------------------------------------------------------------------------
+CONTRACT_YES = "YES"
+CONTRACT_NO = "NO"
+PRICE_FLOOR = 0.001  # Minimum contract price ($0.001)
+PRICE_CEIL = 0.999   # Maximum contract price ($0.999)
+
+
+def is_polymarket_pair(pair: str) -> bool:
+    """Return True if the pair follows Polymarket naming: *-YES/USDT or *-NO/USDT."""
+    base = pair.split("/")[0] if "/" in pair else pair
+    return base.endswith(f"-{CONTRACT_YES}") or base.endswith(f"-{CONTRACT_NO}")
+
+
+def get_complement_pair(pair: str) -> str:
+    """Return the complementary contract pair (YES <-> NO)."""
+    if f"-{CONTRACT_YES}/" in pair:
+        return pair.replace(f"-{CONTRACT_YES}/", f"-{CONTRACT_NO}/")
+    elif f"-{CONTRACT_NO}/" in pair:
+        return pair.replace(f"-{CONTRACT_NO}/", f"-{CONTRACT_YES}/")
+    return pair
+
+
+def get_event_slug(pair: str) -> str:
+    """Extract the event slug from a Polymarket pair.
+
+    'TRUMP-WIN-YES/USDT' -> 'TRUMP-WIN'
+    """
+    base = pair.split("/")[0]
+    for suffix in (f"-{CONTRACT_YES}", f"-{CONTRACT_NO}"):
+        if base.endswith(suffix):
+            return base[: -len(suffix)]
+    return base
+
+
+def _polymarket_synthetic_market(pair: str) -> dict:
+    """Build a synthetic market entry for a Polymarket event contract.
+
+    Polymarket contracts differ from regular assets:
+    - Prices are bounded [0, 1] (probability)
+    - Amount precision is whole shares (integer)
+    - Minimum order is 1 share
+    """
+    return {
+        "symbol": pair,
+        "base": pair.split("/")[0],
+        "quote": pair.split("/")[1] if "/" in pair else "USDT",
+        "spot": True,
+        "swap": False,
+        "future": False,
+        "linear": True,
+        "type": "spot",
+        "contract": False,
+        "active": True,
+        "precision": {"amount": 0, "price": 4},  # whole shares, 4-decimal prices
+        "limits": {
+            "amount": {"min": 1, "max": 1e8},
+            "price": {"min": PRICE_FLOOR, "max": PRICE_CEIL},
+            "cost": {"min": 0.01, "max": 1e8},
+        },
+        "info": {
+            "polymarket": True,
+            "contract_type": CONTRACT_YES if f"-{CONTRACT_YES}/" in pair else CONTRACT_NO,
+            "event_slug": get_event_slug(pair),
+        },
+    }
+
+
+class Polymarket(Portfoliobench):
+    """Exchange adapter for Polymarket event contract backtesting.
+
+    Extends Portfoliobench to handle:
+    - Binary outcome contract market entries (YES/NO shares)
+    - Price bounds enforcement [0, 1]
+    - Zero trading fees (Polymarket's maker model)
+    - Contract-specific synthetic market injection
+    - Complement pair awareness (YES + NO = $1)
+    """
+
+    _ft_has = {
+        "needs_trading_fees": False,
+    }
+
+    # ------------------------------------------------------------------
+    # ccxt init — reuse binance underneath
+    # ------------------------------------------------------------------
+
+    def _init_ccxt(
+        self, exchange_config: dict[str, Any], sync: bool, ccxt_kwargs: dict[str, Any]
+    ) -> ccxt.Exchange:
+        """Map 'polymarket' back to 'binance' for ccxt initialisation."""
+        patched = deepcopy(exchange_config)
+        patched["name"] = "binance"
+        return super()._init_ccxt(patched, sync, ccxt_kwargs)
+
+    # ------------------------------------------------------------------
+    # Market injection — Polymarket-aware
+    # ------------------------------------------------------------------
+
+    def _inject_synthetic_markets(self) -> None:
+        """Inject synthetic market entries for event contracts and regular pairs."""
+        whitelist = self._config.get("exchange", {}).get("pair_whitelist", [])
+        cli_pairs = self._config.get("pairs", [])
+        for pair in set(whitelist + cli_pairs):
+            if pair not in self._markets:
+                if is_polymarket_pair(pair):
+                    logger.info("Auto-injecting Polymarket contract: %s", pair)
+                    self._markets[pair] = _polymarket_synthetic_market(pair)
+                else:
+                    # Fall back to parent's generic synthetic market
+                    from freqtrade.exchange.portfoliobench import _synthetic_market
+
+                    logger.info("Auto-injecting pair: %s", pair)
+                    self._markets[pair] = _synthetic_market(pair)
+
+    # ------------------------------------------------------------------
+    # Fees — Polymarket uses 0 maker fees
+    # ------------------------------------------------------------------
+
+    def get_fee(
+        self,
+        symbol: str,
+        order_type: str = "",
+        side: str = "",
+        amount: float = 1,
+        price: float = 1,
+        taker_or_maker: str = "maker",
+    ) -> float:
+        """Polymarket charges 0% maker fees; small taker fee on some markets."""
+        if is_polymarket_pair(symbol):
+            return 0.0
+        return super().get_fee(symbol, order_type, side, amount, price, taker_or_maker)

strategy/PolymarketMeanReversionStrategy.py

@@ -0,0 +1,89 @@
+"""Polymarket Mean-Reversion Strategy — fade overreactions in prediction markets.
+
+Trades event contracts by betting against short-term overreactions:
+- Buy when probability drops significantly below its rolling mean (oversold)
+- Sell when probability reverts to mean or overshoots above it
+
+Designed for contracts where sharp moves are driven by noise/overreaction
+rather than fundamental shifts (e.g., speculative events, sentiment spikes).
+"""
+
+import numpy as np
+import pandas as pd
+from datetime import datetime
+from typing import Optional
+
+from freqtrade.strategy import IStrategy, Trade
+
+from alpha.PolymarketFactors import PolymarketAlpha
+
+
+class PolymarketMeanReversionStrategy(IStrategy):
+    INTERFACE_VERSION = 3
+
+    can_short: bool = False
+    minimal_roi = {"0": 0.15}  # Take profit at 15% gain
+    stoploss = -0.30
+    trailing_stop = False
+
+    process_only_new_candles = True
+    use_exit_signal = True
+    exit_profit_only = False
+    ignore_roi_if_entry_signal = False
+    startup_candle_count: int = 30
+
+    def populate_indicators(self, dataframe: pd.DataFrame, metadata: dict) -> pd.DataFrame:
+        dataframe = PolymarketAlpha(dataframe, metadata).process()
+        return dataframe
+
+    def populate_entry_trend(self, dataframe: pd.DataFrame, metadata: dict) -> pd.DataFrame:
+        dataframe.loc[
+            (
+                # Z-score strongly negative (price well below mean)
+                (dataframe["prob_zscore"] < -1.5)
+                # Mean reversion signal confirms (below rolling mean)
+                & (dataframe["mean_reversion_signal"] < -0.03)
+                # Volume surge suggests reactionary move, not fundamental
+                & (dataframe["volume_surge"] > 1.5)
+                # Contract still has room to move (not near resolution)
+                & (dataframe["resolution_proximity"] > 0.10)
+                # Price in tradeable range
+                & (dataframe["close"] > 0.10)
+                & (dataframe["close"] < 0.90)
+            ),
+            "enter_long",
+        ] = 1
+
+        return dataframe
+
+    def populate_exit_trend(self, dataframe: pd.DataFrame, metadata: dict) -> pd.DataFrame:
+        dataframe.loc[
+            (
+                # Price reverted above mean
+                (dataframe["prob_zscore"] > 0.5)
+                # OR momentum shifted positive (reversion complete)
+                | (
+                    (dataframe["mean_reversion_signal"] > 0.02)
+                    & (dataframe["prob_momentum"] > 0)
+                )
+            ),
+            "exit_long",
+        ] = 1
+
+        return dataframe
+
+    def confirm_trade_entry(
+        self,
+        pair: str,
+        order_type: str,
+        amount: float,
+        rate: float,
+        time_in_force: str,
+        current_time: datetime,
+        entry_tag: str | None,
+        side: str,
+        **kwargs,
+    ) -> bool:
+        if rate < 0.05 or rate > 0.95:
+            return False
+        return True