polymarket-trader

核心用法

Polymarket Trader 是一套专为 Polymarket 平台 BTC 1小时涨跌预测市场设计的策略开发与调试工具。其核心工作流围绕"锚定-计算-交易-验证"四步展开：首先确认目标市场类型为 bitcoin-up-or-down-* 1小时市场；随后从 Binance BTCUSDT 获取1分钟K线数据，计算波动率（sigma）和到期时间，转换为涨跌的公平概率；仅在公平概率与市场价格的差值（edge）超过阈值时入场，并设置方向性保护避免逆势操作；最后根据入场模式（模型驱动或均值回归）执行对应的退出逻辑，并通过 events.jsonl 和 state.json 日志验证每笔交易的合理性。

工具包含三个配套脚本：：binance_klines.py 用于获取Binance K线数据；binance_regime.py 计算5/15分钟收益率和10周期斜率等市场状态指标；explain_fills.py 则解析交易记录，输出包含公平概率、Z分数和趋势判断的明细表，帮助快速定位问题交易。

显著优点

1. 数据源权威性：直接锚定 Binance——Polymarket BTC 1h 市场的官方结算来源，消除价格源不一致带来的系统性偏差。
2. 策略透明度高：完整的数学模型文档（strategy.md）和可审计的 Python 脚本，便于理解、修改和回测。
3. 零外部依赖：仅使用 Python 标准库，无 pip 包管理风险，部署简单且可复现。
4. 调试友好：explain_fills.py 将复杂交易记录转化为结构化表格，显著缩短策略迭代周期。
5. 模块化设计：数据获取、状态计算、交易解释三个脚本解耦，可独立使用或嵌入更大工作流。

潜在缺点与局限性

• 市场单一性：当前仅优化于 BTC 1h Up/Down 市场，其他资产或时间周期需自行调整参数。
• 非实时交易：脚本设计为离线分析和参数扫描，不直接对接 Polymarket 或 Binance 交易 API，生产环境需额外开发。
• 简化假设：公平概率模型基于历史波动率外推，未纳入订单簿深度、资金费率、新闻事件等微观结构因素。
• 路径硬编码：explain_fills.py 默认读取固定路径的 events.jsonl，跨平台或自定义目录时需手动修改。

适合的目标群体

• 量化策略研究员：需要快速验证 Polymarket 预测市场定价效率的学术或业余研究者。
• Polymarket 活跃交易者：希望系统化分析历史交易、识别边缘衰减模式的进阶用户。
• Crypto 衍生品开发者：探索将 CEX 数据作为 DEX/预测市场定价锚点的工程团队。
• 策略回测爱好者：偏好本地离线分析、对代码可控性要求高的个人投资者。

使用风险

• 财务风险：策略回测表现不代表未来收益，Polymarket 存在无常损失和流动性风险，脚本本身不提供资金管理建议。
• API 限制：Binance 公开 API 有速率限制（约1200请求/分钟），高频参数扫描可能触发限流。
• 网络依赖：脚本运行需稳定访问 Binance API，网络中断或 IP 封禁将导致数据获取失败。
• 数据时效性：1分钟K线数据存在发布延迟，极端行情下锚定价格可能与实际结算价偏离。
• 来源可信度：代码来自个人开发者账号（T3），虽经安全审计，但长期维护和漏洞响应能力未经验证。

核心功能与用法

polymarket-trader 是一套专为Polymarket BTC 1小时Up/Down市场设计的量化交易策略开发与调试工具。其核心工作流围绕"锚定定价"展开：以Binance BTCUSDT作为分辨率来源（resolution source），构建公平概率模型，识别市场错价机会。

典型使用场景：

• 策略设计阶段：构建错价/边缘模型，对比公平概率（fair probability）与市场价格的差异
• 信号增强：添加趋势/震荡状态过滤器（regime filters），避免在不利市况中交易
• 交易复盘：通过events.jsonl/state.json日志分析坏单成因，验证entry/exit逻辑
• 离线优化：利用捆绑脚本进行快速回测与参数扫描

核心工作流（必须按序执行）：
1. 确认市场类型（bitcoin-up-or-down-* 1h）
2. 计算锚定信号：获取Binance 1分钟K线+1小时开盘价，计算波动率σ与剩余时间，转换为公平概率
3. 仅当可测量边缘存在时交易：edge = fair_prob - market_price 超过阈值，且不做与z-score符号相反的押注
4. 根据入场模式选择退出逻辑：模型入场按边缘衰减/模型反转退出；均值回归入场按回归目标退出，并严格限制换手
5. 日志验证：每笔可疑交易需通过reason/entry_mode、公平概率+z、退出区块触发情况三要素解释

捆绑脚本说明：

• binance_klines.py：获取Binance K线数据
• binance_regime.py：计算ret5/ret15/slope10及"稳定化"布尔指标
• explain_fills.py：读取paperbot events.jsonl，输出最近N笔成交的摘要表（方向/结果/价格/原因/公平概率/z-score/趋势对抗标志）

显著优点

1. 来源透明可信

• 代码完全开源托管于GitHub（clawdbot/skills），维护者身份明确，commit历史可追溯
• 通过CLS安全认证（S+等级，98/100分），静态分析99分，依赖审计满分

2. 极致安全设计

• 只读架构：仅访问Binance公共API（/api/v3/klines, /api/v3/ticker/price），无需API Key
• 零第三方依赖：纯Python标准库实现（urllib, json, math, datetime等），无供应链攻击风险
• 无敏感操作：不涉及资金转账、账户修改、系统命令执行或持久化数据存储

3. 专业金融工程方法论

• 锚定定价（anchor pricing）设计：以分辨率来源本身作为定价基准，避免外部数据源偏差
• 明确的边缘计算框架：fair_prob - market_price > threshold，配合z-score方向性保护
• 双模式退出逻辑：区分模型驱动与均值回归驱动的不同风险管理需求

4. 工程实用性

• 本地日志解析能力：直接对接paperbot事件流，支持交易级归因分析
• 跨平台脚本设计：除一处硬编码Windows路径外，具备良好的可移植性
• 参数化接口：支持命令行参数覆盖默认配置

局限性与潜在风险

1. 平台兼容性瑕疵

• explain_fills.py第80行包含硬编码Windows路径：C:\Users\domin\.openclaw\workspace...
• 影响：非Windows用户需手动指定--events参数
• 缓解：已提供参数覆盖机制，实际可用性损失有限

2. 网络鲁棒性待增强

• 当前实现为单请求无重试设计，网络波动时可能失败
• Binance API偶尔会出现503/超时，缺乏指数退避机制

3. 策略本身的市场风险（非工具风险）

• 本skill仅提供分析框架，不保证策略盈利性
• BTC 1h波动率预测的内在困难：跳跃扩散、交易所特异性价格变动、Polymarket分辨率延迟
• 过度拟合风险：参数扫描可能产生虚假边缘，需样本外验证

4. 输入验证缺口

• dateparser.parse()返回None时缺乏显式处理
• 极端行情下σ计算可能产生数值不稳定（未观察到但实际存在理论可能）

适合人群

核心用户画像：

• 量化交易开发者：需要快速搭建事件驱动型衍生品定价原型
• Polymarket做市商/策略交易者：现有策略的日志分析与性能归因
• 加密货币研究员：研究CEX-DEX价格发现差异的学术用途
• Python金融工程学习者：学习波动率模型与边缘计算的标准化实现

不建议使用场景：

• 完全无编程基础的用户（需理解概率模型与命令行操作）
• 寻求"一键赚钱"方案的非专业投资者
• 需要实时自动交易执行的场景（本skill为分析工具，非交易机器人）

常规风险总结

| 风险类别 | 等级 | 说明 |

|---------|------|------|

| 代码执行安全 | 🟢 极低 | 无eval/exec/subprocess，纯标准库 |

| 资金安全 | 🟢 无 | 只读API，不涉及私钥或交易签名 |

| 数据隐私 | 🟢 无 | 不收集用户数据，仅获取公开市场价格 |

| 网络依赖 | 🟡 低 | Binance API可用性，可通过参数调整缓解 |

| 策略盈亏 | 🔴 高 | 工具本身安全，但策略应用存在市场风险 |

综合评估：polymarket-trader是一个设计精良、安全可信的量化分析基础设施，其风险完全集中在"如何使用工具"而非"工具本身"。建议用户在模拟环境中充分验证策略逻辑后再考虑实盘应用。