polymarket-backtest 0.1.0

Polymarket API wrapper and strategy backtesting metrics toolkit

polymarket-backtest

Polymarket API 封装与策略回测评估工具包。

功能

• API 封装：Polymarket Gamma API（合约信息）、CLOB API（赔率历史时间序列）
• 内置数据集：BTC 15 分钟市场盘口快照 + Flash Crash / Hedge Arb 策略回测记录
• 回测指标：Sharpe Ratio、最大回撤、胜率、盈亏比、卡玛比率

安装

pip install -e /path/to/polymarket_backtest
# 或
cd /path/to/polymarket_backtest && pip install -e .

快速开始

1. 查询合约信息

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. 拉取赔率历史

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. 加载内置数据集

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. 计算回测指标

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