polymarket-backtest 0.1.0__py3-none-any.whl

polymarket_backtest/__init__.py

@@ -0,0 +1,35 @@
+"""
+polymarket-backtest
+===================
+
+Polymarket API 封装与策略回测评估工具包。
+
+快速开始：
+    # 1. 查询市场信息
+    from polymarket_backtest.api import GammaClient, ClobClient
+
+    gamma = GammaClient()
+    market = gamma.get_market_info("BTC")
+    print(market.slug, market.up_price)
+
+    # 2. 拉取赔率历史
+    clob = ClobClient()
+    history = clob.get_price_history(market.up_token_id, interval="1d")
+    print(f"{len(history)} 个价格点")
+
+    # 3. 加载内置示例数据集
+    from polymarket_backtest.data import load_trades, load_orderbook
+
+    trades = load_trades("flash_crash")
+    ob = load_orderbook("BTC")
+
+    # 4. 计算回测指标
+    from polymarket_backtest.backtest import summary
+
+    pnl = trades["gross_pnl"].dropna().tolist()
+    result = summary(pnl)
+    print(result)
+    # {'net_pnl': 47.92, 'win_rate': 0.143, 'sharpe_ratio': 0.85, 'max_drawdown': 12.5, ...}
+"""
+
+__version__ = "0.1.0"

polymarket_backtest/api/__init__.py

@@ -0,0 +1,13 @@
+"""Polymarket API 封装模块。"""
+
+from .clob import ClobClient
+from .gamma import GammaClient
+from .models import MarketInfo, OddsHistory, PricePoint
+
+__all__ = [
+    "GammaClient",
+    "ClobClient",
+    "MarketInfo",
+    "PricePoint",
+    "OddsHistory",
+]

polymarket_backtest/api/clob.py

@@ -0,0 +1,136 @@
+"""
+Polymarket CLOB API 客户端（只读）
+
+封装赔率历史数据查询。无需认证。
+
+用法示例：
+    from polymarket_backtest.api import GammaClient, ClobClient
+
+    gamma = GammaClient()
+    clob  = ClobClient()
+
+    market = gamma.get_market_info("BTC")
+    history = clob.get_price_history(market.up_token_id, interval="1d")
+
+    for point in history.points:
+        print(point.timestamp, point.price)
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import requests
+
+from .models import OddsHistory, PricePoint
+
+Interval = Literal["1m", "1h", "6h", "1d", "1w", "max"]
+
+
+class ClobClient:
+    """
+    Polymarket CLOB API 客户端（只读子集）。
+
+    提供赔率历史查询，无需 API 密钥。
+    """
+
+    BASE_URL = "https://clob.polymarket.com"
+
+    def __init__(self, base_url: str = BASE_URL, timeout: int = 15):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+
+    # ------------------------------------------------------------------
+    # 公开接口
+    # ------------------------------------------------------------------
+
+    def get_price_history(
+        self,
+        token_id: str,
+        interval: Interval | None = "1d",
+        fidelity: int = 60,
+        start_ts: int | None = None,
+        end_ts: int | None = None,
+    ) -> OddsHistory:
+        """
+        拉取某 token 的赔率历史时间序列。
+
+        参数：
+            token_id: CLOB token ID（从 GammaClient 获取）
+            interval: 时间窗口（"1m","1h","6h","1d","1w","max"）
+                      与 start_ts/end_ts 互斥
+            fidelity: 数据分辨率（分钟），例如 60 = 每小时一个点
+            start_ts: 开始时间 Unix 时间戳（UTC）
+            end_ts:   结束时间 Unix 时间戳（UTC）
+
+        返回：
+            OddsHistory 对象，包含时间戳和对应价格列表
+
+        示例：
+            # 拉取最近 1 天数据，每小时一个点
+            history = clob.get_price_history(token_id, interval="1d", fidelity=60)
+
+            # 拉取指定时间范围
+            history = clob.get_price_history(
+                token_id,
+                start_ts=1697875200,
+                end_ts=1697961600,
+                fidelity=5,
+            )
+        """
+        params: dict = {"market": token_id, "fidelity": fidelity}
+
+        if start_ts is not None or end_ts is not None:
+            if start_ts is not None:
+                params["startTs"] = start_ts
+            if end_ts is not None:
+                params["endTs"] = end_ts
+        elif interval is not None:
+            params["interval"] = interval
+
+        url = f"{self.base_url}/prices-history"
+        resp = self._session.get(url, params=params, timeout=self.timeout)
+        resp.raise_for_status()
+
+        data = resp.json()
+        raw_points = data.get("history", [])
+        points = [PricePoint(timestamp=int(p["t"]), price=float(p["p"])) for p in raw_points]
+
+        return OddsHistory(
+            token_id=token_id,
+            interval=interval or "custom",
+            fidelity=fidelity,
+            points=points,
+        )
+
+    def get_price_history_df(
+        self,
+        token_id: str,
+        interval: Interval | None = "1d",
+        fidelity: int = 60,
+        start_ts: int | None = None,
+        end_ts: int | None = None,
+    ):
+        """
+        同 get_price_history，但直接返回 pandas DataFrame。
+
+        DataFrame 列：timestamp（Unix）、price、datetime（UTC）
+        """
+        import pandas as pd
+
+        history = self.get_price_history(
+            token_id,
+            interval=interval,
+            fidelity=fidelity,
+            start_ts=start_ts,
+            end_ts=end_ts,
+        )
+        if not history.points:
+            return pd.DataFrame(columns=["timestamp", "price", "datetime"])
+
+        df = pd.DataFrame(
+            {"timestamp": history.timestamps(), "price": history.prices()}
+        )
+        df["datetime"] = pd.to_datetime(df["timestamp"], unit="s", utc=True)
+        return df

polymarket_backtest/api/gamma.py

@@ -0,0 +1,194 @@
+"""
+Polymarket Gamma API 客户端
+
+封装市场发现与合约信息查询，支持 BTC/ETH/SOL/XRP 的 15 分钟涨跌市场。
+
+用法示例：
+    from polymarket_backtest.api import GammaClient
+
+    client = GammaClient()
+    market = client.get_market_info("ETH")
+    print(market.slug, market.up_price, market.down_price)
+
+    # 列出近期市场
+    markets = client.list_recent_markets("BTC", n=5)
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+import requests
+
+from .models import MarketInfo
+
+
+class GammaClient:
+    """
+    Polymarket Gamma API 客户端。
+
+    用于发现市场和获取市场元数据（无需认证）。
+    """
+
+    BASE_URL = "https://gamma-api.polymarket.com"
+
+    COIN_SLUGS: dict[str, str] = {
+        "BTC": "btc-updown-15m",
+        "ETH": "eth-updown-15m",
+        "SOL": "sol-updown-15m",
+        "XRP": "xrp-updown-15m",
+    }
+    SUPPORTED_COINS = list(COIN_SLUGS.keys())
+
+    def __init__(self, base_url: str = BASE_URL, timeout: int = 10):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+
+    # ------------------------------------------------------------------
+    # 公开接口
+    # ------------------------------------------------------------------
+
+    def get_market_info(self, coin: str) -> MarketInfo | None:
+        """
+        获取某币种当前活跃的 15 分钟市场信息。
+
+        参数：
+            coin: 币种符号（BTC / ETH / SOL / XRP，不区分大小写）
+
+        返回：
+            MarketInfo 对象，无活跃市场时返回 None
+        """
+        market = self._get_active_market(coin.upper())
+        if not market:
+            return None
+        return self._parse_market(market, coin.upper())
+
+    def get_market_by_slug(self, slug: str) -> MarketInfo | None:
+        """
+        通过 slug 精确查询市场。
+
+        参数：
+            slug: 市场 slug，例如 "eth-updown-15m-1775035200"
+
+        返回：
+            MarketInfo 对象，未找到时返回 None
+        """
+        coin = self._coin_from_slug(slug)
+        raw = self._fetch_by_slug(slug)
+        if not raw:
+            return None
+        return self._parse_market(raw, coin)
+
+    def list_recent_markets(self, coin: str, n: int = 10) -> list[MarketInfo]:
+        """
+        列出某币种最近 n 个市场（从当前窗口往前推算）。
+
+        参数：
+            coin: 币种符号
+            n: 返回的市场数量
+
+        返回：
+            MarketInfo 列表（按时间从新到旧排列）
+        """
+        coin = coin.upper()
+        self._check_coin(coin)
+        prefix = self.COIN_SLUGS[coin]
+
+        now = datetime.now(timezone.utc)
+        minute = (now.minute // 15) * 15
+        current_ts = int(now.replace(minute=minute, second=0, microsecond=0).timestamp())
+
+        results: list[MarketInfo] = []
+        ts = current_ts
+        while len(results) < n:
+            slug = f"{prefix}-{ts}"
+            raw = self._fetch_by_slug(slug)
+            if raw:
+                results.append(self._parse_market(raw, coin))
+            ts -= 900  # 往前 15 分钟
+            if ts < current_ts - 900 * 200:  # 最多往前 200 个窗口（约 2 天）
+                break
+
+        return results
+
+    # ------------------------------------------------------------------
+    # 内部方法
+    # ------------------------------------------------------------------
+
+    def _get_active_market(self, coin: str) -> dict[str, Any] | None:
+        """尝试当前、下一个、上一个窗口，找到 acceptingOrders 的市场。"""
+        self._check_coin(coin)
+        prefix = self.COIN_SLUGS[coin]
+
+        now = datetime.now(timezone.utc)
+        minute = (now.minute // 15) * 15
+        current_ts = int(now.replace(minute=minute, second=0, microsecond=0).timestamp())
+
+        for offset in [0, 900, -900]:
+            ts = current_ts + offset
+            raw = self._fetch_by_slug(f"{prefix}-{ts}")
+            if raw and raw.get("acceptingOrders"):
+                return raw
+        return None
+
+    def _fetch_by_slug(self, slug: str, retries: int = 3) -> dict[str, Any] | None:
+        """GET /markets/slug/{slug}，SSL 错误时自动重试。"""
+        url = f"{self.base_url}/markets/slug/{slug}"
+        for attempt in range(retries):
+            try:
+                resp = self._session.get(url, timeout=self.timeout)
+                if resp.status_code == 200:
+                    return resp.json()
+                return None
+            except Exception as e:
+                err = str(e).lower()
+                is_network = any(k in err for k in ("ssl", "eof", "tls", "connection"))
+                if is_network and attempt < retries - 1:
+                    time.sleep(0.5 * (attempt + 1))
+                    continue
+                return None
+        return None
+
+    def _parse_market(self, raw: dict[str, Any], coin: str) -> MarketInfo:
+        """将原始 API 响应解析为 MarketInfo。"""
+        outcomes = self._parse_json_field(raw.get("outcomes", '["Up", "Down"]'))
+        token_ids_raw = self._parse_json_field(raw.get("clobTokenIds", "[]"))
+        prices_raw = self._parse_json_field(raw.get("outcomePrices", '["0.5", "0.5"]'))
+
+        token_ids = {str(o).lower(): str(v) for o, v in zip(outcomes, token_ids_raw)}
+        prices = {str(o).lower(): float(v) for o, v in zip(outcomes, prices_raw)}
+
+        return MarketInfo(
+            slug=raw.get("slug", ""),
+            question=raw.get("question", ""),
+            coin=coin,
+            end_date=raw.get("endDate", ""),
+            token_ids=token_ids,
+            prices=prices,
+            accepting_orders=bool(raw.get("acceptingOrders", False)),
+            raw=raw,
+        )
+
+    @staticmethod
+    def _parse_json_field(value: Any) -> list:
+        if isinstance(value, str):
+            return json.loads(value)
+        return list(value)
+
+    def _check_coin(self, coin: str) -> None:
+        if coin not in self.COIN_SLUGS:
+            raise ValueError(
+                f"不支持的币种: {coin!r}。支持: {self.SUPPORTED_COINS}"
+            )
+
+    @staticmethod
+    def _coin_from_slug(slug: str) -> str:
+        slug_lower = slug.lower()
+        for coin, prefix in GammaClient.COIN_SLUGS.items():
+            if slug_lower.startswith(prefix):
+                return coin
+        return "UNKNOWN"

polymarket_backtest/api/models.py

@@ -0,0 +1,69 @@
+"""
+Polymarket API 数据模型
+
+定义 API 调用的输入输出数据结构。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class MarketInfo:
+    """Polymarket 市场信息。"""
+
+    slug: str
+    question: str
+    coin: str
+    end_date: str
+    token_ids: dict[str, str]    # {"up": "token_id", "down": "token_id"}
+    prices: dict[str, float]     # {"up": 0.52, "down": 0.48}
+    accepting_orders: bool
+    raw: dict = field(default_factory=dict, repr=False)
+
+    @property
+    def up_token_id(self) -> str | None:
+        return self.token_ids.get("up")
+
+    @property
+    def down_token_id(self) -> str | None:
+        return self.token_ids.get("down")
+
+    @property
+    def up_price(self) -> float:
+        return self.prices.get("up", 0.5)
+
+    @property
+    def down_price(self) -> float:
+        return self.prices.get("down", 0.5)
+
+
+@dataclass
+class PricePoint:
+    """单个历史价格点。"""
+
+    timestamp: int    # Unix UTC
+    price: float
+
+    def __repr__(self) -> str:
+        return f"PricePoint(t={self.timestamp}, p={self.price:.4f})"
+
+
+@dataclass
+class OddsHistory:
+    """某 token 的赔率历史时间序列。"""
+
+    token_id: str
+    interval: str
+    fidelity: int                # 分辨率（分钟）
+    points: list[PricePoint] = field(default_factory=list)
+
+    def __len__(self) -> int:
+        return len(self.points)
+
+    def prices(self) -> list[float]:
+        return [p.price for p in self.points]
+
+    def timestamps(self) -> list[int]:
+        return [p.timestamp for p in self.points]

polymarket_backtest/backtest/__init__.py

@@ -0,0 +1,21 @@
+"""策略回测评估模块。"""
+
+from .metrics import (
+    calmar_ratio,
+    max_drawdown,
+    profit_factor,
+    sharpe_ratio,
+    summary,
+    summary_from_df,
+    win_rate,
+)
+
+__all__ = [
+    "sharpe_ratio",
+    "max_drawdown",
+    "win_rate",
+    "profit_factor",
+    "calmar_ratio",
+    "summary",
+    "summary_from_df",
+]