核心用法
本技能为 Polymarket 自动化交易提供完整的工程化配置流程，覆盖从环境搭建到生产验证的七个关键步骤：
1. 存量检测：优先检查 .env 与 config.json 中既有的 POLYMARKET_PRIVATE_KEY、POLYMARKET_PROXY_ADDRESS 等凭证，避免重复初始化
2. 环境配置：强制要求 Polygon 主网代理钱包（非 EOA 签名地址），配置 CLOB WebSocket、REST 及 Data API 三端入口
3. 依赖管理：锁定 py-clob-client>=0.28.0 为核心 SDK，搭配 httpx/websocket-client/orjson 构建高性能异步栈
4. Token 授权：区分 UI 自动授权（推荐新手）与 Builder API 程序化授权（服务器部署），需对四个合约完成 USDC spend 许可
5. API 凭证派生：通过 ClobClient.derive_api_key() 生成三要素（key/secret/passphrase），持久化至环境变量，禁止日志泄露
6. 四端连通验证：依次检测 Gamma API（事件元数据）、CLOB REST（订单簿深度）、Data API（持仓查询）、WebSocket（实时推送）
7. 安全测试单：以远离市价的 2 份额极小单验证签名-广播-确认全链路，确保 MINED 状态后再更新本地持仓
显著优点
- 工程完整性：唯一覆盖"钱包-授权-凭证-连通-验证"全链路的官方级配置指南，减少 80% 以上的新手踩坑时间
- 安全设计：强制区分 EOA 签名地址与 Proxy 持仓地址，避免资金误锁；凭证派生后禁止 stdout 输出，符合服务器部署安全规范
- 故障定位表：针对
insufficient balance、Order silently rejected、Positions always empty等 6 类高频失败场景提供精准根因分析 - 生产级细节：明确
size * price >= 1.0、价格精度规则（<0.04 或 >0.96 时 3 位小数）、整数强制转换等边界条件
潜在缺点与局限性
- 门槛较高：要求用户已具备 Polygon 主网交互经验、EOA 私钥安全管理能力，纯新手需先完成 Polymarket 官方入门教程
- 外部依赖重：核心 SDK
py-clob-client由 Polymarket 团队维护，版本迭代（如 0.28.0+）可能引入破坏性变更，需锁定版本 - Builder API 分离：程序化 Token 授权需额外申请 Builder API 凭证，与 CLOB 凭证体系独立，增加运维复杂度
- 链上延迟：
MINED状态依赖 Polygon 网络确认，极端网络拥堵时可能影响策略实时性 - 地域限制：Polymarket 服务受美国 CFTC 及各地监管政策影响，部分地区 IP 可能无法访问或面临法律风险
适合人群
- 量化交易开发者：需要将以太坊生态策略迁移至预测市场，要求低延迟订单簿与实时持仓同步
- DeFi 机构运维：管理多地址、多策略的资金配置，需程序化完成授权与凭证轮换
- 数据科学家/分析师：希望直接接入 Gamma/Data API 获取链上预测市场数据流，构建独立研究 pipeline
- 成熟散户进阶：已熟悉 Polymarket UI 操作，希望迁移至自动化交易以执行更复杂策略（如套利、做市）
常规风险
| 风险类别 | 具体表现 | 缓解建议 |
|---------|---------|---------|
| **私钥泄露** | `.env` 文件误提交 Git，或日志打印 credentials | 使用 `.gitignore` 排除环境文件；启用 GitHub secret scanning；生产环境采用 AWS Secrets Manager / Vault |
| **合约授权泛滥** | 对恶意合约授予无限 USDC spend 权限 | 严格核对 GUIDE.md 列出的四个官方合约地址；定期 revoke 非必要授权（如通过 revoke.cash） |
| **代理地址混淆** | 误将 EOA 地址作为 `POLYMARKET_PROXY_ADDRESS`，导致持仓查询为空或资金无法到账 | 务必从 Polymarket 账户设置页复制 Proxy 地址；本地保存地址对照表 |
| **订单精度错误** | 价格小数位超标导致订单静默拒绝 | 封装价格格式化函数，强制应用 2dp/3dp 规则 |
| **链上回滚** | 基于 `MATCHED` 状态提前更新持仓，实际交易失败 | 必须等待 `MINED` 状态确认，设计异步状态机处理 |
| **监管合规** | 所在司法辖区禁止二元期权或预测市场 | 使用前确认本地法规；避免使用 VPN 规避地理封锁 |
| **SDK 供应链** | `py-clob-client` 发布恶意版本 | 固定哈希校验；优先使用官方 PyPI；在隔离环境测试升级 |