polymarket-backtest 0.1.0__tar.gz

polymarket_backtest-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: polymarket-backtest
+Version: 0.1.0
+Summary: Polymarket API wrapper and strategy backtesting metrics toolkit
+Author-email: Your Name <you@example.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yourname/polymarket-backtest
+Project-URL: Repository, https://github.com/yourname/polymarket-backtest
+Project-URL: Issues, https://github.com/yourname/polymarket-backtest/issues
+Keywords: polymarket,prediction-market,backtest,trading,quantitative
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# polymarket-backtest
+
+Polymarket API 封装与策略回测评估工具包。
+
+## 功能
+
+- **API 封装**：Polymarket Gamma API（合约信息）、CLOB API（赔率历史时间序列）
+- **内置数据集**：BTC 15 分钟市场盘口快照 + Flash Crash / Hedge Arb 策略回测记录
+- **回测指标**：Sharpe Ratio、最大回撤、胜率、盈亏比、卡玛比率
+
+## 安装
+
+```bash
+pip install -e /path/to/polymarket_backtest
+# 或
+cd /path/to/polymarket_backtest && pip install -e .
+```
+
+## 快速开始
+
+### 1. 查询合约信息
+
+```python
+from polymarket_backtest.api import GammaClient
+
+gamma = GammaClient()
+
+# 获取当前活跃的 BTC 15 分钟市场
+market = gamma.get_market_info("BTC")
+print(market.slug)          # "btc-updown-15m-1775035200"
+print(market.up_price)      # 0.52
+print(market.down_price)    # 0.48
+print(market.up_token_id)   # "229931..."
+
+# 列出最近 5 个市场
+markets = gamma.list_recent_markets("ETH", n=5)
+for m in markets:
+    print(m.slug, m.end_date)
+```
+
+### 2. 拉取赔率历史
+
+```python
+from polymarket_backtest.api import GammaClient, ClobClient
+
+gamma = GammaClient()
+clob = ClobClient()
+
+market = gamma.get_market_info("BTC")
+
+# 拉取最近 1 天数据（每小时 1 个点）
+history = clob.get_price_history(
+    market.up_token_id,
+    interval="1d",
+    fidelity=60,
+)
+print(f"获取到 {len(history)} 个价格点")
+
+for point in history.points[:3]:
+    print(point.timestamp, point.price)
+
+# 直接返回 DataFrame
+df = clob.get_price_history_df(market.up_token_id, interval="1w", fidelity=60)
+print(df.head())
+#    timestamp  price                   datetime
+# 0  1697875200  0.520  2023-10-21 08:00:00+00:00
+```
+
+### 3. 加载内置数据集
+
+```python
+from polymarket_backtest.data import list_datasets, load_orderbook, load_trades, load_summary
+
+# 查看可用数据集
+for ds in list_datasets():
+    print(f"  {ds['name']}: {ds['description']}")
+
+# 加载 BTC 盘口快照（~13750 行）
+ob = load_orderbook("BTC")
+print(ob.columns.tolist())
+# ['recorded_at_ts', 'market_slug', 'coin', 'up_bid', 'up_ask', ...]
+
+# 加载 Flash Crash 策略交易记录
+trades = load_trades("flash_crash")
+print(trades[["coin", "side", "gross_pnl", "exit_reason"]].head())
+
+# 加载 Hedge Arb 策略交易记录
+hedge_trades = load_trades("hedge_arb")
+```
+
+### 4. 计算回测指标
+
+```python
+from polymarket_backtest.backtest import summary, sharpe_ratio, max_drawdown, win_rate
+from polymarket_backtest.data import load_trades
+
+# 加载回测数据
+trades = load_trades("flash_crash")
+pnl = trades["gross_pnl"].dropna().tolist()
+
+# 综合摘要
+result = summary(pnl)
+print(result)
+# {
+#   'total_trades': 22,
+#   'net_pnl': 47.92,
+#   'avg_pnl': 2.18,
+#   'std_pnl': 5.67,
+#   'win_rate': 0.143,
+#   'profit_factor': 1.08,
+#   'sharpe_ratio': 0.384,
+#   'max_drawdown': 18.5,
+#   'max_drawdown_pct': 22.3,
+#   'calmar_ratio': 2.59
+# }
+
+# 单独计算各指标
+print("Sharpe Ratio:", sharpe_ratio(pnl))
+print("年化 Sharpe (15m 市场):", sharpe_ratio(pnl, periods_per_year=35040))
+
+dd = max_drawdown(pnl)
+print(f"最大回撤: {dd['max_drawdown']:.2f} USDC ({dd['max_drawdown_pct']:.1f}%)")
+
+print("胜率:", win_rate(pnl))
+
+# 直接从 DataFrame 计算
+from polymarket_backtest.backtest import summary_from_df
+result2 = summary_from_df(trades, pnl_col="gross_pnl")
+```
+
+## API 参考
+
+### `GammaClient`
+
+| 方法 | 说明 |
+|------|------|
+| `get_market_info(coin)` | 获取当前活跃的 15 分钟市场信息 |
+| `get_market_by_slug(slug)` | 通过 slug 精确查询 |
+| `list_recent_markets(coin, n=10)` | 列出最近 n 个市场 |
+
+### `ClobClient`
+
+| 方法 | 说明 |
+|------|------|
+| `get_price_history(token_id, interval, fidelity, ...)` | 拉取赔率历史，返回 `OddsHistory` |
+| `get_price_history_df(token_id, ...)` | 同上，返回 `pd.DataFrame` |
+
+**interval 参数**：`"1m"` / `"1h"` / `"6h"` / `"1d"` / `"1w"` / `"max"`
+
+### 内置数据集
+
+| 名称 | 描述 |
+|------|------|
+| `btc_orderbook` | BTC 15 分钟盘口快照，~13750 行 |
+| `flash_crash_trades` | Flash Crash 策略逐笔交易 |
+| `flash_crash_summary` | Flash Crash 策略汇总统计 |
+| `hedge_arb_trades` | Hedge Arbitrage 策略逐笔交易 |
+
+### 回测指标
+
+| 函数 | 说明 |
+|------|------|
+| `sharpe_ratio(pnl, periods_per_year=None)` | 夏普比率，可选年化 |
+| `max_drawdown(pnl)` | 最大回撤（金额 + 百分比） |
+| `win_rate(pnl)` | 胜率 [0, 1] |
+| `profit_factor(pnl)` | 盈亏比 |
+| `calmar_ratio(pnl)` | 卡玛比率 |
+| `summary(pnl, periods_per_year=None)` | 综合统计摘要 |
+| `summary_from_df(df, pnl_col="net_pnl")` | 直接从 DataFrame 计算 |
+
+## 数据说明
+
+盘口数据字段说明：
+
+| 字段 | 说明 |
+|------|------|
+| `recorded_at_ts` | UNIX 时间戳（秒） |
+| `up_bid / up_ask / up_mid` | UP 方向的买/卖/中间价 |
+| `down_bid / down_ask / down_mid` | DOWN 方向的买/卖/中间价 |
+| `remaining_seconds` | 距市场结束的秒数 |
+| `elapsed_seconds` | 市场已进行的秒数 |
+
+## 依赖
+
+- Python >= 3.10
+- `requests` >= 2.28
+- `numpy` >= 1.24（可选，如未安装则用纯标准库计算）
+- `pandas` >= 2.0

polymarket_backtest-0.1.0/README.md

@@ -0,0 +1,188 @@
+# polymarket-backtest
+
+Polymarket API 封装与策略回测评估工具包。
+
+## 功能
+
+- **API 封装**：Polymarket Gamma API（合约信息）、CLOB API（赔率历史时间序列）
+- **内置数据集**：BTC 15 分钟市场盘口快照 + Flash Crash / Hedge Arb 策略回测记录
+- **回测指标**：Sharpe Ratio、最大回撤、胜率、盈亏比、卡玛比率
+
+## 安装
+
+```bash
+pip install -e /path/to/polymarket_backtest
+# 或
+cd /path/to/polymarket_backtest && pip install -e .
+```
+
+## 快速开始
+
+### 1. 查询合约信息
+
+```python
+from polymarket_backtest.api import GammaClient
+
+gamma = GammaClient()
+
+# 获取当前活跃的 BTC 15 分钟市场
+market = gamma.get_market_info("BTC")
+print(market.slug)          # "btc-updown-15m-1775035200"
+print(market.up_price)      # 0.52
+print(market.down_price)    # 0.48
+print(market.up_token_id)   # "229931..."
+
+# 列出最近 5 个市场
+markets = gamma.list_recent_markets("ETH", n=5)
+for m in markets:
+    print(m.slug, m.end_date)
+```
+
+### 2. 拉取赔率历史
+
+```python
+from polymarket_backtest.api import GammaClient, ClobClient
+
+gamma = GammaClient()
+clob = ClobClient()
+
+market = gamma.get_market_info("BTC")
+
+# 拉取最近 1 天数据（每小时 1 个点）
+history = clob.get_price_history(
+    market.up_token_id,
+    interval="1d",
+    fidelity=60,
+)
+print(f"获取到 {len(history)} 个价格点")
+
+for point in history.points[:3]:
+    print(point.timestamp, point.price)
+
+# 直接返回 DataFrame
+df = clob.get_price_history_df(market.up_token_id, interval="1w", fidelity=60)
+print(df.head())
+#    timestamp  price                   datetime
+# 0  1697875200  0.520  2023-10-21 08:00:00+00:00
+```
+
+### 3. 加载内置数据集
+
+```python
+from polymarket_backtest.data import list_datasets, load_orderbook, load_trades, load_summary
+
+# 查看可用数据集
+for ds in list_datasets():
+    print(f"  {ds['name']}: {ds['description']}")
+
+# 加载 BTC 盘口快照（~13750 行）
+ob = load_orderbook("BTC")
+print(ob.columns.tolist())
+# ['recorded_at_ts', 'market_slug', 'coin', 'up_bid', 'up_ask', ...]
+
+# 加载 Flash Crash 策略交易记录
+trades = load_trades("flash_crash")
+print(trades[["coin", "side", "gross_pnl", "exit_reason"]].head())
+
+# 加载 Hedge Arb 策略交易记录
+hedge_trades = load_trades("hedge_arb")
+```
+
+### 4. 计算回测指标
+
+```python
+from polymarket_backtest.backtest import summary, sharpe_ratio, max_drawdown, win_rate
+from polymarket_backtest.data import load_trades
+
+# 加载回测数据
+trades = load_trades("flash_crash")
+pnl = trades["gross_pnl"].dropna().tolist()
+
+# 综合摘要
+result = summary(pnl)
+print(result)
+# {
+#   'total_trades': 22,
+#   'net_pnl': 47.92,
+#   'avg_pnl': 2.18,
+#   'std_pnl': 5.67,
+#   'win_rate': 0.143,
+#   'profit_factor': 1.08,
+#   'sharpe_ratio': 0.384,
+#   'max_drawdown': 18.5,
+#   'max_drawdown_pct': 22.3,
+#   'calmar_ratio': 2.59
+# }
+
+# 单独计算各指标
+print("Sharpe Ratio:", sharpe_ratio(pnl))
+print("年化 Sharpe (15m 市场):", sharpe_ratio(pnl, periods_per_year=35040))
+
+dd = max_drawdown(pnl)
+print(f"最大回撤: {dd['max_drawdown']:.2f} USDC ({dd['max_drawdown_pct']:.1f}%)")
+
+print("胜率:", win_rate(pnl))
+
+# 直接从 DataFrame 计算
+from polymarket_backtest.backtest import summary_from_df
+result2 = summary_from_df(trades, pnl_col="gross_pnl")
+```
+
+## API 参考
+
+### `GammaClient`
+
+| 方法 | 说明 |
+|------|------|
+| `get_market_info(coin)` | 获取当前活跃的 15 分钟市场信息 |
+| `get_market_by_slug(slug)` | 通过 slug 精确查询 |
+| `list_recent_markets(coin, n=10)` | 列出最近 n 个市场 |
+
+### `ClobClient`
+
+| 方法 | 说明 |
+|------|------|
+| `get_price_history(token_id, interval, fidelity, ...)` | 拉取赔率历史，返回 `OddsHistory` |
+| `get_price_history_df(token_id, ...)` | 同上，返回 `pd.DataFrame` |
+
+**interval 参数**：`"1m"` / `"1h"` / `"6h"` / `"1d"` / `"1w"` / `"max"`
+
+### 内置数据集
+
+| 名称 | 描述 |
+|------|------|
+| `btc_orderbook` | BTC 15 分钟盘口快照，~13750 行 |
+| `flash_crash_trades` | Flash Crash 策略逐笔交易 |
+| `flash_crash_summary` | Flash Crash 策略汇总统计 |
+| `hedge_arb_trades` | Hedge Arbitrage 策略逐笔交易 |
+
+### 回测指标
+
+| 函数 | 说明 |
+|------|------|
+| `sharpe_ratio(pnl, periods_per_year=None)` | 夏普比率，可选年化 |
+| `max_drawdown(pnl)` | 最大回撤（金额 + 百分比） |
+| `win_rate(pnl)` | 胜率 [0, 1] |
+| `profit_factor(pnl)` | 盈亏比 |
+| `calmar_ratio(pnl)` | 卡玛比率 |
+| `summary(pnl, periods_per_year=None)` | 综合统计摘要 |
+| `summary_from_df(df, pnl_col="net_pnl")` | 直接从 DataFrame 计算 |
+
+## 数据说明
+
+盘口数据字段说明：
+
+| 字段 | 说明 |
+|------|------|
+| `recorded_at_ts` | UNIX 时间戳（秒） |
+| `up_bid / up_ask / up_mid` | UP 方向的买/卖/中间价 |
+| `down_bid / down_ask / down_mid` | DOWN 方向的买/卖/中间价 |
+| `remaining_seconds` | 距市场结束的秒数 |
+| `elapsed_seconds` | 市场已进行的秒数 |
+
+## 依赖
+
+- Python >= 3.10
+- `requests` >= 2.28
+- `numpy` >= 1.24（可选，如未安装则用纯标准库计算）
+- `pandas` >= 2.0

polymarket_backtest-0.1.0/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-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-0.1.0/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