Polymarket 自动量化交易（通过 codexbot）实施方案

目标：基于 Polymarket 的官方 API/SDK 搭建一个可长期运行的自动量化交易系统（数据→信号→下单→风控→监控），并给出可落地的工程方案与最小可运行骨架代码。

合规提醒：Polymarket International（polymarket.com）存在明确的地理限制/封锁；不要尝试绕过限制。若你/服务器位于受限地区，仅能做“只读研究/模拟”，或转向其面向美国用户的产品线（见“Polymarket US”章节）。

1) 你要研究的到底是哪一套 Polymarket？

Polymarket 目前至少有两套面向不同用户/地区的 API 体系：

  1. Polymarket International（polymarket.com）

    • 主要开发文档：https://docs.polymarket.com/
    • 交易接口：CLOB（Central Limit Order Book） API + WebSocket
    • 市场发现/元数据：Gamma API
    • 数据聚合：Data API
    • 重要：官方文档列出多个地区被封锁（含美国等），下单前必须做地理限制校验。

  2. Polymarket US（polymarket.us）

    • 文档：https://docs.polymarket.us/
    • 认证方式与国际站不同（文档显示为 Ed25519 签名鉴权），且还存在“Exchange Gateway”等更偏机构/直连接入的路径。

本方案将以 International（polymarket.com）为主线 给出可执行架构，同时给出 US 线路的对接建议。

2) Polymarket（International）关键接口全景图

2.1 三类 HTTP API（强烈建议分层封装）

  • CLOB API（交易/盘口/用户订单）

    • Host：https://clob.polymarket.com
    • 用途：下单/撤单、查订单、查盘口、查成交、查余额/持仓等

  • Gamma API（找市场：事件/市场列表、tokenId、tickSize、minSize、negRisk 等）

    • Host：https://gamma-api.polymarket.com
    • 用途：抓取“哪些市场可交易”、每个 market 的 conditionId、clobTokenIds、最小 tick、最小下单量等

  • Data API（聚合数据/历史数据方向）

    • Host：https://data-api.polymarket.com
    • 用途：若你要做回测/研究，通常需要比 CLOB 更“面向分析”的数据接口

2.2 WebSocket（实时盘口/成交/订单状态）

官方 WS 端点（International）：

  • Market：wss://ws-subscriptions-clob.polymarket.com/ws/market
  • User：wss://ws-subscriptions-clob.polymarket.com/ws/user

建议：

  • 行情优先用 WS（减少轮询、降低延迟、避免 rate limit）。
  • 交易/风控层需要一个“行情新鲜度”指标：WS 断线或长时间无更新时，暂停下单或改用 REST 复核。
  • 处理官方的 application-layer heartbeat：收到 event_type=heartbeat 后发送 {"type":"pong"}（不要只依赖 WebSocket 协议层 ping/pong）。

2.3 Rate Limits（必须做：限速 + 退避 + 断路器）

官方对 REST/WS 都有频率与订阅数限制（并且可能随时间调整），量化系统要把“限速”当成基础设施：

  • REST：按 endpoint 做 token-bucket，遇到 429 立刻指数退避
  • WS：控制订阅资产数量、消息处理耗时与重连节奏

参考：https://docs.polymarket.com/api-reference/rate-limits

2.4 官方 SDK（优先用官方库，少踩签名/精度坑）

官方文档列出多语言客户端与工具（建议优先选官方实现）：

  • TypeScript：@polymarket/clob-client、@polymarket/order-utils、@polymarket/sdk、@polymarket/agents
  • Python：py-clob-client、py-order-utils
  • 若要做“gasless/托管钱包/智能合约钱包”一类更复杂钱包形态：重点关注 Builder Signing SDK 与 Relayer Client

参考：https://docs.polymarket.com/developers/clients-and-sdks

3) 认证与密钥：量化交易最常踩坑的地方

3.1 CLOB 的三种访问级别（L0/L1/L2）

  • L0：无鉴权，只能访问公开端点（例如 get_order_book、服务器时间等）
  • L1：需要链上签名能力（用于签订单等）
  • L2：需要 API key/secret/passphrase（用于访问更完整的账户/交易端点）

工程上建议：

  • 用一个 AuthContext 统一管理：
    • private_key（或远程签名器）
    • api_key / api_secret / api_passphrase
    • signatureType + funder（见下）

3.2 Signature Type 与 Funder（非常关键）

官方文档将订单签名分为几类（概念上）：

  • 0：EOA（外部账户）：资金地址=签名地址（最简单，建议量化首选）
  • 1：Polymarket 代理/托管钱包（如 email/Magic）：签名地址 ≠ 资金地址，需要传 funder
  • 2：Browser wallet proxy：同样需要 funder 概念

如果你的资金实际在另一个地址（代理钱包/智能合约钱包），而你签名用的是不同地址：

  • 下单会失败或订单无法归属到正确资金账户
  • 你会遇到“看起来下单成功但账户没变化/持仓不对”的一类问题

3.3 地理限制（不要绕过）

官方文档提供 geoblock 列表；International 线路对多地存在下单限制（含美国）。

量化系统必须有 pre-flight checks：

  • 启动时：检查当前出口 IP/地区是否允许下单
  • 运行中：周期性复核（云机/代理/网络变更会导致地区变化）
  • 若被限制：自动降级为“只读模式”（研究/监控/记录数据），并报警

3.4 API key/secret/passphrase 的获取与轮换

实操上建议直接使用官方 SDK（Python/TS）提供的“创建或派生 API 凭证”的方法（例如 createOrDeriveApiKey / create_or_derive_api_creds 一类接口），并将得到的：

  • api_key
  • api_secret
  • api_passphrase

存放在仅运行环境可读的 secret 管理里（环境变量/密钥管理服务），不要写入仓库与日志。

4) 资金与链上前置：Polygon + USDC.e + Allowances

4.1 你需要准备的资产

  • 网络：Polygon（chainId=137）
  • 交易抵押资产：文档与官方客户端示例强调 USDC.e
  • Gas：Polygon 的原生 gas token（钱包里可能显示为 MATIC/POL；官方文档示例里写 POL）

4.2 Allowances（EOA/MetaMask/硬件钱包尤其要注意）

若你用 EOA（自己掌控私钥）并且不是 Polymarket 的 email/Magic 托管方式，通常需要先做 ERC20/CTF 的 approve/setApprovalForAll。

官方 Python 客户端 README 给出了常见合约/地址（Polygon）示例：

  • USDC（文档示例地址）：0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174
  • Conditional Tokens（CTF）：0x4D97DCd97eC945f40cF65F87097ACe5EA0476045
  • Exchange contracts：
    • Main：0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E
    • Neg risk：0xC5d563A36AE78145C45a50134d48A1215220f80a
    • Neg risk adapter：0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296

风控建议：

  • 只给“专用交易钱包”做 approve（不要用主钱包）
  • approve 不要无限额（根据交易规模设一个上限），并定期复核/撤销

4.3 可选：Gasless / Relayer（更高级的钱包形态）

如果你打算用智能合约钱包、或希望把链上操作（部署钱包、approve、CTF 操作等）通过官方 relayer 以更“gasless”的方式完成，通常需要：

  • 加入/使用官方的 Builder 体系（会有单独的 builder API credentials）
  • 使用 relayer endpoint（文档示例：https://relayer-v2.polymarket.com/）

这条路线复杂度更高，但对“生产化/多人协作/更安全的密钥形态”有价值；建议在 EOA 跑通 M1 后再考虑。

5) 市场发现 → 可交易标的（token_id）提取

量化系统需要把“人类看到的市场（URL/slug）”映射成“可下单的 token_id（asset_id）”：

  1. 用 Gamma API 拉 event/market 列表（建议分页缓存到本地库）
  2. 对每个 market 读取：
    • conditionId
    • clobTokenIds（通常是 Yes/No 两个 token id 的列表）
    • orderPriceMinTickSize（最小价格步进）
    • orderMinSize（最小下单 shares）
    • negRisk（决定走哪个 exchange 合约/适配器）

工程上建议做一个“Market Catalog 服务”：

  • 每 1~5 分钟刷新一次 Gamma（不用太频繁）
  • 实时行情只依赖 WS（CLOB）

6) 下单与执行：从策略输出到订单生命周期

6.1 订单类型与“市场单”的实现方式

官方说明（International）要点：

  • CLOB 只有“限价单”语义；所谓“市价单”本质是用 可成交价格 的限价单实现
  • 常见订单类型：GTC / GTD / FOK / FAK
  • “市场单”金额语义：
    • BUY：amount 按美元计（你要买入多少美元的 shares）
    • SELL：amount 按 shares 计（你要卖出多少 shares）

6.2 执行层（Executor）建议职责

Executor 不应该由策略直接调用 HTTP/SDK；建议做统一执行层，职责包括：

  • 校验 tick size / min size / negRisk
  • 统一限速（rate limit）与重试（指数退避 + 断路器）
  • 订单幂等：避免断线重连导致重复下单
  • 按账户维度做“最大挂单数/最大未成交风险敞口”控制
  • 对每个 market 维护“目标订单集合”→ 自动 diff（该撤就撤，该改就改）

6.3 订单/成交状态回流

务必订阅 User WS（或定期轮询）以获得：

  • 订单 open/partial/filled/canceled 的状态变化
  • 成交明细（用于 PnL、风控、回测标注）

6.4 Tick size 变化与报价精度（别踩“价格无效”）

要点：

  • 每个 market 有最小 tick（Gamma 的 orderPriceMinTickSize），下单价格必须按 tick 对齐（向下/向最近取整取决于你的策略与方向）
  • WS Market channel 会推送 tick_size_change 事件；当 tick 变化时，你的挂单策略应立即重算并撤改单

7) 系统架构（推荐：事件驱动 + 插件化策略）

7.1 模块拆分（建议）

  • catalog/：Gamma 拉市场、标准化 market 元数据
  • md/：行情（WS+REST 兜底），维护 orderbook/bbo/mid
  • exec/：下单、撤单、订单管理、限速与重试
  • portfolio/：余额、持仓、敞口、PnL（从 User channel/REST 对账）
  • risk/：全局/单市场/单事件风险上限、kill-switch、异常检测
  • strategies/：策略插件（读 state → 输出目标订单/目标仓位）
  • storage/：SQLite/Postgres（快照、订单、成交、指标）
  • ops/：日志、指标、告警、健康检查、自动重启

7.2 运行形态

最稳妥的生产运行形态：

  • 单实例（先从 1 台机器开始）+ systemd/docker 守护
  • state 持久化到 DB，支持重启恢复
  • 单独的“配置中心”（yaml/env），支持热更新（谨慎）

8) 策略层建议（从低风险到高复杂度）

  1. 只读研究：抓 WS 行情 + 记录到 DB（先把数据链路跑通）
  2. 简单做市：围绕 mid 挂双边单，做 inventory 控制（注意 fee + tick + min size）
  3. 跨市场约束套利：
    • 二元互补（Yes/No）价格不应同时偏离过大
    • 多 outcome 事件的概率和约束（注意 negRisk 市场）
  4. 事件驱动/信息套利：需要外部数据源（新闻/链上/宏观指标），复杂度最高

9) codexbot 如何落地执行（你可以让 codexbot 做什么）

把 codexbot 当作“自动化研发 + 运维执行器”：

  • 自动生成/迭代策略与执行模块
  • 自动跑回测/回放（如果数据齐全）
  • 自动部署到 VPS、配置 systemd、监控日志、异常报警
  • 交易前自动做 pre-flight（geoblock、余额、allowance、WS 连通性）

10) 建议交付里程碑（可按 3~7 天迭代）

  • M0（1 天）：只读行情系统（Gamma 拉市场 + WS 订阅 + DB 落盘 + dashboard/日志）
  • M1（2~3 天）：最小交易闭环（单市场、单策略、限额极小、手动 kill switch）
  • M2（3~7 天）：多市场并发 + 统一执行层 + 风控完善 + 自动对账
  • M3（2 周+）：策略库、回测/回放、自动参数调优、告警体系完善

11) 参考链接（官方优先）

International（polymarket.com）

  • Docs：https://docs.polymarket.com/
  • Quickstart：https://docs.polymarket.com/developers/quickstart
  • Auth：https://docs.polymarket.com/developers/authentication
  • WS：https://docs.polymarket.com/api-reference/ws-overview
  • Gamma API：https://docs.polymarket.com/developers/gamma-markets-api
  • Geoblock：https://docs.polymarket.com/api-reference/geoblock
  • Rate limits：https://docs.polymarket.com/api-reference/rate-limits
  • SDKs：https://docs.polymarket.com/developers/clients-and-sdks

Polymarket US

  • Docs：https://docs.polymarket.us/

Python 官方客户端

  • py-clob-client：https://github.com/Polymarket/py-clob-client
本文发表日期：