Polymarket V2 数据指南

1. V2 升级：发生了什么变化及其重要性

Polymarket 是 Polygon 上全球最大的去中心化预测市场，2026 年 3 月的月交易量突破 100 亿美元，仅当月就处理了超过 1.92 亿笔交易。这一增长暴露了 V1 基础设施的局限性：继承 Polygon 桥风险的桥接抵押品、携带协议不再需要的字段的订单结构、智能合约钱包缺乏清晰的路径，以及费用逻辑嵌入单个订单而非在匹配时计算。

2026 年 4 月 28 日，Polymarket 发布了自启动以来最大的协议变更：CLOB V2。这是一次协调升级，涉及所有三个核心层：新的 Exchange 智能合约、重写的订单簿后端，以及名为 pUSD（Polymarket USD）的新抵押品代币。V1 在切换时完全弃用，不提供向后兼容性。

如果你之前为 Polymarket 编写数据查询或构建机器人，你了解的一些内容仍然适用。但合约地址、订单结构、抵押品代币和费用模型都已改变。本指南将引导数据专业人员了解处理 V2 数据所需的一切知识。

2. 五个核心 V2 合约地址

所有 Polymarket 合约都部署在 Polygon 主网（链 ID：137）上。在 V2 中，交易所合约和抵押品代币是新的。CTF（条件代币框架）合约和 Neg Risk 适配器保持不变。

1. pUSD（0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb）：新的 ERC-20 抵押品代币，取代 USDC.e。
2. Conditional Tokens（0x4D97DCd97eC945f40cF65F87097ACe5EA0476045）：ERC-1155 结果份额合约，与 V1 相同。
3. CTF Exchange V2（0xe111180000d2663c0091e4f400237545b87b996b）：二元市场的核心匹配引擎。
4. Neg Risk CTF Exchange V2（0xe2222d279d744050d28e00520010520000310F59）：多结果市场的订单匹配。
5. Neg Risk Adapter（0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296）：跨结果转换“No”代币，与 V1 相同。

对分析师而言至关重要：如果你有使用旧 CTF Exchange 地址（0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E）过滤的 Dune 查询，这些查询将捕获所有 V1 交易历史，但会错过 2026 年 4 月 28 日之后的所有 V2 交易。你需要在过滤条件中添加新的 V2 合约地址。始终通过 docs.polymarket.com/resources/contracts 验证当前地址，这是官方来源。

3. pUSD：新的抵押品代币

V2 中影响最大的数据变更是从 USDC.e 切换到 pUSD 作为结算资产。

USDC.e 是 Polygon 上 USDC 的桥接版本，并非 Circle 原生发行的 USDC，这带来了桥接风险，并使结算变得稍微复杂。pUSD（Polymarket USD）是 Polygon 上的标准 ERC-20，由 USDC 1:1 支持，且智能合约在链上强制执行支持机制。无算法锚定，无部分准备金。一个 pUSD 始终可以无手续费地精确兑换为一个 USDC。

这对数据工作的意义：

• 所有新的交易量以 pUSD 计价，而非 USDC.e。你的交易量指标需要跟踪 pUSD 转账，而非 USDC.e。
• pUSD 仍为 6 位小数，与 USDC.e 相同，因此原始整数到可读数字的转换计算不变。
• CollateralOnramp 合约处理 USDC 或 USDC.e 包装为 pUSD。CollateralOfframp 处理 pUSD 解包为 USDC。这些都是新的 V2 合约事件，如果你在跟踪资金流动，值得索引。
• 历史比较：4 月 28 日之前的交易量是 USDC.e；之后是 pUSD。由于两者都与 USDC 1:1 锚定，经济上等价，但你的查询在跨时间聚合时需要处理两个不同的代币地址。

4. V2 订单结构：移除与新增的内容

订单结构是 Polymarket 上每一笔交易的基本数据单元。无论你是解析原始链上事件，还是使用 CLOB API，理解该结构都至关重要。

V1 有而 V2 移除的内容

• nonce：替换为 timestamp（毫秒），简化了订单管理
• feeRateBps：费用不再嵌入订单中，而是由操作者在匹配时设置
• taker：移除，因为 V2 默认开放匹配

V2 新增的内容

• timestamp：订单创建时间（毫秒），替换 nonce 用于唯一性和排序
• metadata：哈希后的任意元数据字段，用于更丰富的订单归因
• builder：链上构建者代码，用于第三方集成商归因（见下文 Builder 计划）

OrderFilled 事件模式（V2）

在 V1 中，交易方向是通过 makerAssetId 和 takerAssetId 推断的；如果其中任何一个等于 0，表示该方持有抵押品（USDC.e）。V2 完全移除了这种模式。不再有 makerAssetId、takerAssetId 或 AssetId 字段。取而代之的是，事件携带一个单一的 side 整数来描述 maker 的头寸，外加明确的 makerAmountFilled 和 takerAmountFilled 金额。

完整模式可在以下 Dune 表中找到：

polymarket_v2_polygon.ctfexchange_evt_orderfilled

通过 side 读取交易方向

• side = 0 → BUY：maker 正在购买结果代币，支付 pUSD。makerAmountFilled 是支付的 pUSD；takerAmountFilled 是收到的结果代币。
• side = 1 → SELL：maker 正在出售结果代币，接收 pUSD。makerAmountFilled 是出售的结果代币；takerAmountFilled 是收到的 pUSD。

V2 中的价格计算

价格始终以每个结果代币份额的 pUSD 表示。由于 side 字段指示哪个金额是抵押品、哪个是代币：

CASE
  WHEN side = 0  -- maker 正在购买代币
    THEN CAST(makerAmountFilled AS DOUBLE) / CAST(takerAmountFilled AS DOUBLE)
  WHEN side = 1  -- maker 正在出售代币
    THEN CAST(takerAmountFilled AS DOUBLE) / CAST(makerAmountFilled AS DOUBLE)
END AS price

示例：一个 maker 通过支付 4,000,000 原始 pUSD 单位购买了 40,000,000 原始代币单位：

side = 0
price = 4,000,000 / 40,000,000 = 0.10  →  每股 0.10 美元

两个金额都使用 6 位小数，因此比例中相互抵消——价格计算无需调整小数位数。

5. 新的费用模型

在 V1 中，费用作为 feeRateBps 嵌入每个订单中并由交易者签名。这意味着在订单下达时就必须知道费用。

在 V2 中，费用由操作者在匹配时设置，不属于已签名的订单结构。这对数据有三个重要影响：

1. 费用是 OrderFilled 上的一个明确列。每个成交事件都携带一个 fee 字段（uint256，6 位小数），显示实际收取的费用。不再需要从份额数量差异中反向推导费用。
2. 费用以 pUSD 收取，而不是从份额中扣除。你的交易历史显示抵押品成本和费用作为独立值。
3. 你可以通过 CLOB API 的费用端点查询当前费用参数，而无需从单个订单中读取。

-- 单个 OrderFilled 行的总成交额与净成交额（side = 0 示例）
makerAmountFilled / 1e6 AS gross_volume_usd
(makerAmountFilled - fee) / 1e6 AS net_volume_usd
fee / 1e6 AS fee_usd

对于聚合交易量指标，请事先决定你想要总成交额（转移的全部抵押品）还是净成交额（抵押品减去费用）。有了明确的费用列，现在只需一行代码。

6. V2 链上事件参考

V1 中存在的相同核心事件在 V2 中仍然被触发。以下是每个事件的含义及其变化的更新参考。

PositionSplit

当新的结果代币被铸造时，由 CTF 合约触发。发生在两种场景：

• 买方和卖方匹配成功，且他们的合并价格等于 1.00 美元——协议为双方铸造代币
• 用户直接存入 pUSD 并调用 Split 以同时获得 Yes 和 No 代币

数据说明：拆分会增加市场的总未平仓合约。partition: [1, 2] 字段表明这是否是一个二元拆分（1 = Yes，2 = No）。pUSD 有 6 位小数。

PositionMerge

与 Split 相反——等量的 Yes 和 No 代币被销毁（转移到空地址），pUSD 返还给持有者。减少未平仓合约。

PositionsConverted（仅 NegRisk）

当持有者销毁选定结果中的“No”代币并在剩余结果上收到“Yes”代币时，由 Neg Risk Adapter 触发。indexSet 字段是位掩码：将其从十进制转换为二进制以识别哪些结果被转换。amount 字段以原始代币单位表示（记住：6 位小数）。

OrderFilled

用于交易量和价格分析的主要表。每个 maker 订单成交触发一次。每一行代表一个 maker 的订单被匹配，包含以下关键字段：side（0 = BUY，1 = SELL）、makerAmountFilled、takerAmountFilled、fee、tokenId、builder、orderHash。

交易量计算：始终仅从 maker 的抵押品侧衡量——切勿在同一查询中同时求和 makerAmountFilled 和 takerAmountFilled，因为这会重复计算同一笔交易。

SUM(CASE 
    WHEN side = 0 THEN (CAST(makerAmountFilled AS DOUBLE) + CAST(fee AS DOUBLE)) / 1e6 
    WHEN side = 1 THEN CAST(takerAmountFilled AS DOUBLE) / 1e6
END) AS trade_volume_usd

由于每一行是一个唯一的 maker 订单，对所有行求和即可得到总交易量，而不会重复计算。

OrdersMatched

每匹配一次触发一个事件。用于交易计数和匹配级别分析（例如，一天内发生了多少次离散匹配）。

PayoutRedemption

当获胜代币持有者在市场结算后赎回 pUSD 时触发。金额以 pUSD 为单位（6 位小数）。用于跟踪市场结算流程并计算有效投资回报率。

7. Builder 计划和 builderCode

V2 将链上构建者归因作为一级特性引入。在 V1 中，构建者使用 HMAC 头部（POLY_BUILDER_*）和一个独立的签名 SDK 来将交易量与其集成相关联。在 V2 中，构建者直接将 builder 字段嵌入签名的订单结构中。

对数据分析师而言，这意义重大：你现在可以通过读取链上订单数据中的 builder 字段，识别给定交易是由哪个第三方平台或机器人生成的。这支持：

• 生态系统分析：哪些构建者在推动交易量
• 按集成归因的 maker/taker 行为分析
• 基于原始链上数据的构建者排行榜构建

builder 字段是通过 docs.polymarket.com/builders/api-keys 分配的代码，并在 Polygonscan 事件日志中可见，适用于每一笔 V2 交易。

8. EIP-712 签名更改

如果你手动签署订单（不使用 SDK），V2 的 EIP-712 域版本已从 "1" 更改为 "2"。verifyingContract 字段也必须指向 V2 交易所地址。如果你在链上或数据管道中验证订单真实性，这会影响原始订单验证。

V2 还增加了 EIP-1271 签名支持，允许智能合约钱包（Gnosis Safe、账户抽象钱包）签署并提交订单。对于数据工作，这意味着你可能会看到交易归属于多签或合约地址，而非 EOA——在进行交易者画像或钱包级别分析时，请将此考虑在内。

9. CLOB API 更改

生产环境 CLOB 端点不变——V2 在切换后仍运行于相同的 URL。与数据工作相关的关键 API 变更：

• POST /submit 现在立即返回 { transactionID, state: "STATE_NEW" }。transactionHash 字段已从提交响应中移除。要获取链上哈希，请轮询 GET /transaction/{transactionID}。
• GET /markets/keyset 现在最大限制为 100（从更高值减少）。使用 after_cursor / next_cursor 进行分页。
• CLOB WebSocket 价格变化消息格式已于 2025 年 9 月更新。如果你有实时订阅价格通道的数据源，请确认你正在使用更新的模式。

10. 何处寻找 Polymarket V2 数据

• Polygonscan（polygonscan.com）：任何链上调查的起点。按合约地址搜索以浏览事件日志。适用于抽查单个交易。
• Goldsky：提供 Polymarket 链上活动的实时流管道，可导入你自己的数据库或数据仓库。
• Allium：区块链分析平台，可通过 SQL 查询 Polymarket 交易、余额和头寸数据。参见 docs.allium.so/historical-data/predictions。
• Dune Analytics（dune.com）：社区资源最丰富的选项。官方维护的入门查询：
• Sungraph：Polymarket 维护一个子图，用于索引市场和头寸数据。参见 docs.polymarket.com/market-data/subgraph。

11. 分析人员实用说明

时间序列分析中处理 V1/V2 分界：跨 2026 年 4 月 28 日前后时间段的交易量查询需要合并 V1 和 V2 合约地址的结果。由于 USDC.e 和 pUSD 均与 USDC 1:1 锚定，在构建累计交易量序列时，你可以将它们视为经济上等价——只需确保覆盖两个代币地址。

未平仓合约计算：OI 仍由 PositionSplit（增加 OI）减去 PositionMerge（减少 OI），再减去 PayoutRedemption（最终结算流出）的净值驱动。CTF 合约地址未变，因此现有的按 CTF 事件过滤的 OI 查询应可继续运行，无需修改。

• 原文链接： x.com/0xtobey/status/205...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～