PolyLedger：用SQL查询Polymarket链上交易的开源索引器

PolyLedger 是一个可断点续传的 Polymarket 索引器，将 CLOB 市场元数据与 Polygon 链上 OrderFilled 交易统一写入单个 DuckDB 文件。它通过 HyperSync 流式抓取数据，支持幂等写入、双版本合约解析和 Parquet 导出，让预测市场数据分析像写 SQL 一样简单。

适用人群：1. 量化交易员与数据分析师：需要研究 Polymarket 预测市场价格、流动性与交易行为的人群；2. 链上数据工程师：对 Polygon 链上事件索引、断点续传架构感兴趣的技术人员；3. 学术研究者与记者：关注预测市场数据、需要可复现数据集进行实证分析的研究者。

适用场景：1. 预测市场策略回测：通过 SQL 查询历史 OrderFilled 事件，分析市场定价偏差与套利机会；2. 链上数据仪表盘构建：将 DuckDB 文件接入 BI 工具或 Notebook，实时监控 Polymarket 交易量、活跃市场与资金流向；3. 学术研究与数据新闻：导出 Parquet 后使用 pandas/polars 进行统计分析，验证预测市场有效性假说。

推荐理由：PolyLedger 解决了 Polymarket 数据分析中最痛的环节：数据获取与整合。它用 DuckDB 单文件存储降低了门槛，断点续传与幂等写入保证了工程可靠性，双版本合约解析体现了对历史数据的尊重。对于任何想认真研究预测市场的人来说，这是一个值得收藏的基础设施级工具。

项目定位与背景

Polymarket 是目前最大的去中心化预测市场之一，其 CLOB 订单簿与 Polygon 链上结算产生了海量数据。然而，官方 API 只提供市场元数据，链上交易则需要自行解析事件日志。PolyLedger 正是为填补这一空白而生：它把 CLOB 市场元数据与链上 OrderFilled 事件汇聚到一个 DuckDB 文件中，让分析师用 SQL 就能完成复杂查询。项目由 nahrek 开发，Python 编写，目前获得 623 Stars，属于预测市场数据工具中少有的工程化作品。

核心功能与技术架构

PolyLedger 的数据流分为两条主线。第一条通过 Polymarket CLOB API 拉取全部市场元数据，包括 token id、问题描述、结算规则等；第二条通过 Envio HyperSync 流式抓取 Polygon 链上的 OrderFilled 事件，覆盖 V2 和 V1 两代合约布局。所有数据写入单个 DuckDB 文件，利用列式压缩、真实类型和索引，无需服务器即可完成 SQL 连接查询。

工程可靠性是该项目的一大卖点。行数据与区块游标在同一事务中提交，中断后可从精确位置恢复；order_fills 表以 (transaction_hash, log_index) 为主键，配合 ON CONFLICT DO NOTHING 实现幂等写入，重复运行同一区间不会产生副作用。网络层实现了带抖动的指数退避、Retry-After 支持以及跨 REST 源的共享令牌桶限流器。此外，每个 API 响应都经过 Pydantic 模型校验，上游格式变更会立即报错，而不是静默写入空值。

创新点与亮点

第一，断点续传与幂等写入的组合在同类索引器中并不常见，这直接解决了长时回填任务容易失败、重跑成本高的问题。第二，双版本合约解析意味着用户无需关心 Polymarket 合约升级带来的数据断裂，V1 和 V2 的 OrderFilled 事件被统一解码到同一张表。第三，缺口恢复机制会标记 CLOB 列表中缺失的 token id，并从 Gamma API 回填，避免数据静默丢失。第四，Parquet 导出命令让数据可以无缝接入 pandas、polars 或 Spark 生态，兼顾了 SQL 即时查询与大数据处理两种工作流。

与同类项目对比

与 Dune Analytics 等平台相比，PolyLedger 的优势在于本地化与可编程性：数据在本地 DuckDB 文件中，查询无延迟、无额度限制，且可以自由导出。与自行编写 Web3.py 脚本相比，PolyLedger 提供了完整的错误处理、限流、校验和断点续传，省去了大量重复工程。与 SubQuery 或 The Graph 等索引框架相比，PolyLedger 更轻量、更专注，不需要部署节点或编写 GraphQL schema，适合个人分析师快速上手。

上手指南与快速开始

使用 PolyLedger 需要 Python 3.11+ 和一个 HyperSync API token（免费层足够）。安装方式为克隆仓库后 pip install -e .，然后在 .env 中设置 HYPERSYNC_BEARER_TOKEN。首次全量同步在免费层可能需要数小时到数天，但可以随时中断。建议先用 polyledger markets 验证元数据拉取，再用 polyledger chain --max-blocks 200000 测试小范围链上数据，确认无误后执行 polyledger sync 完成全量索引。后续增量运行只需几秒。

总结与展望

PolyLedger 是一个定位清晰、工程扎实的数据基础设施项目。它没有追求大而全，而是把 Polymarket 数据索引这一件事做到了可靠、可复现、可查询。对于预测市场研究者、量化交易员和链上数据分析师来说，这是一个能显著降低数据获取成本的开源工具。未来若能在增量更新频率、更多事件类型（如订单取消、流动性变化）以及可视化示例上继续扩展，其价值会进一步提升。当前的主要限制是首次回填耗时较长，且依赖 HyperSync 的免费额度，但这并不影响它作为预测市场数据管道的首选方案之一。

查看 GitHub 项目 →