摘要
Polymarket API 并不是一个单一的端点。它是一组 HTTP 和 WebSocket 接口，构建在部署于 Polygon 上的预测市场之上。开发者通常接触两个层面：市场数据层（Gamma 风格的 REST 端点，用于事件、市场和元数据）和交易层（CLOB API，用于订单簿、订单、交易和经过身份验证的账户操作）。两者都有 Polymarket 的文档，并且都与用于读取底层合约的区块链 RPC 分开。
这种分离很重要。如果你正在构建仪表板、研究管道或交易机器人，你可能会调用市场数据和 CLOB API 来获取报价和订单流，而在需要验证结算、读取链上仓位、监视代币转账或将 API 报告的内容与链状态进行核对时，你会调用 Polygon RPC 端点。混淆两者是团队首次集成 Polymarket 时最常见的困惑来源。
本页解释了每个层的用途、如何决定你的工作负载需要哪一个，以及可靠的 Polygon RPC 端点适合放在哪里。OnFinality 为 Polygon 和许多其他网络提供 RPC API 访问和专用节点基础设施，当你的 Polymarket 集成需要生产量级的链上读取时，这一点很重要。
关键要点
- Polymarket API 是分层的：市场数据 REST 端点、CLOB 交易 API 和 WebSocket 流，所有这些都与 Polygon 链本身分开。
- 使用 CLOB 和市场数据 API 获取报价、订单簿和订单管理；使用 Polygon RPC 端点进行链上验证和合约读取。
- 经过身份验证的交易端点需要凭证和谨慎的密钥处理；公共市场数据端点则不需要。
- WebSocket 流用于实时订单簿和交易更新，不能替代历史查询或链上核对。
- 速率限制、分页和重试行为因层而异，因此请针对每一层分别设计客户端。
- 当你的集成需要高容量或归档深度的 Polygon 读取时，请比较 RPC API 和专用节点选项，而不是依赖共享的公共端点。
你的项目实际需要哪个 Polymarket API 层？
在编写代码之前，先确定你的应用程序要做什么。围绕 Polymarket API 的大多数困惑来自于将其视为一个产品，而它实际上是三个具有不同认证模型、不同数据形状和不同故障模式的表面。
使用这个快速映射来选择你首先需要的层，然后仅在工作负载需要时添加其他层。
- 从满足你功能的最小层开始，然后扩展。
- 将市场数据和交易客户端分开，这样交易中断不会破坏只读页面。
- 将链上 RPC 层视为验证路径，而不是 CLOB API 的替代品。
| 标准 | 检查内容 | 为什么重要 |
|---|---|---|
| 市场数据（事件、市场、元数据） | 你是否只需要显示市场、价格、赔率或搜索结果？ | 公共读取端点通常不需要凭证，因此你可以立即进行原型设计，而无需管理密钥。 |
| CLOB 交易（订单、交易、订单簿） | 你的系统是否会下单、修改或取消订单，或读取实时订单簿深度？ | 交易端点需要身份验证和谨慎的密钥处理；泄露的密钥会带来直接的财务风险。 |
| WebSocket 流 | 你是否需要将实时订单簿或交易更新推送到你的应用？ | 流减少了轮询负载，但需要重连逻辑和套接字断开时的回退路径。 |
| 链上 RPC（Polygon） | 你是否需要验证结算、读取合约状态或将 API 数据与链上事件进行核对？ | API 报告平台所知的内容；链是余额和结算的真相来源。 |
CLOB API 和市场数据 API 在实践中如何不同
CLOB（中央限价订单簿）API 是交易表面。它暴露订单放置、取消、订单状态、交易历史和订单簿深度。请求经过身份验证，确切的认证方案在 Polymarket 自己的文档中定义，因此请遵循该文档，而不是猜测标头格式。
市场数据表面是读取侧：事件、市场、系列和搜索。它专为显示和研究工作负载而设计，通常不需要凭证。如果你正在构建仪表板或研究管道，这里将是你大部分调用的地方。
两个层都是链下服务。两者都不是区块链节点。当你需要知道在 Polygon 上实际结算了什么时，你查询链。
- 经过身份验证的调用应放在后端，绝不要放在浏览器代码中。
- 积极缓存市场元数据；它的变化频率远低于价格。
- 记录请求 ID 和时间戳，以便以后将 API 响应与链上交易关联起来。
Polygon RPC 端点在 Polymarket 集成中的位置
Polymarket 在 Polygon 上结算，因此任何涉及资金、仓位或结算的集成最终都需要 Polygon RPC 端点。典型用途包括读取抵押代币的 ERC-20 余额、监视合约事件以获取成交和赎回，以及确认你提交的交易是否实际被包含。
这就是 RPC 质量比大多数团队预期更重要的地方。每隔几秒核对仓位的交易机器人与每分钟刷新一次的仪表板是非常不同的工作负载。共享公共端点适合探索，但当你频繁轮询或需要历史状态时，它们会成为瓶颈。
OnFinality 在许多网络（包括 Polygon）上提供 RPC API 访问和专用节点基础设施。如果你的 Polymarket 集成依赖于稳定的链上读取，那么在扩展之前，值得比较托管 RPC API 与专用节点。请参阅 RPC 定价 和 支持的 RPC 网络 了解当前选项。
读取当前区块号的最小 JSON-RPC 调用如下所示：
- 使用
eth_call进行只读合约状态查询，例如余额和授权额度。 - 使用
eth_getLogs并设置紧凑的区块范围进行事件核对；宽范围开销大且经常被拒绝。 - 使用 JSON-RPC 批量请求将独立的读取操作批处理，以减少往返次数。
在负载下经得起考验的请求模式
Polymarket 集成往往以可预测的方式失败：过多的小请求、无限制的日志查询以及没有重试策略。修复通常是架构性的，而不是更换提供商。
将读路径与写路径分开。市场数据轮询、链上读取和订单提交具有不同的延迟容忍度，不应共享一个具有全局超时的单一客户端。
对于链上读取，优先使用少量批处理调用而不是许多单独调用。对于事件核对，持久化最后处理的区块，以便重启时恢复而不是从创世区块重新扫描。
- 为每个客户端设置明确的超时，而不是一个全局值。
- 在传输错误时使用退避重试，而不是在验证错误时。
- 将区块号与任何链上结果一起记录，以便以后解释。
| 标准 | 检查内容 | 为什么重要 |
|---|---|---|
| 轮询市场数据 | 间隔、缓存 TTL 以及是否需要每个字段 | 大多数元数据很少变化；过度获取会浪费配额并增加延迟。 |
| 链上余额读取 | 批处理大小以及是否需要最新区块或特定区块 | 固定区块使结果可重现并避免不一致的快照。 |
| 事件日志查询 | 每个请求的区块范围以及地址/主题过滤器 | 窄过滤器保持响应小并减少超时的可能性。 |
| 订单提交 | 幂等键和重试语义 | 没有幂等性的重试订单可能会重复意图。 |
调试路径：当 Polymarket API 调用与链上读取不一致时
API 返回的内容与链上显示的内容不一致通常是时间问题，而不是任一系统的错误。在假设某些东西坏了之前，按顺序完成以下检查。
首先，确认你在同一时间比较的是同一件事。API 响应反映请求时平台的视图；链上读取反映特定区块。固定区块并重新运行比较。
其次，检查交易是否仍在待处理。提交的订单或赎回可能尚未被包含，RPC 节点在交易被包含之前会正确报告交易前状态。
- 始终将区块号与链上结果一起记录。
- 当结果看起来不可能时，与第二个 RPC 端点进行比较。
- 不要盲目重试非幂等写入。
| 标准 | 检查内容 | 为什么重要 |
|---|---|---|
| 症状：余额看起来不对 | 读取使用的区块号，以及是否存在待处理交易 | 在待处理交易期间读取 latest 会给出过时但正确的答案。 |
| 症状：缺少成交 | 日志过滤器地址、主题和区块范围 | 错误的主题或过窄的范围会静默返回空结果。 |
| 症状：间歇性 429 或超时 | 请求速率、批处理大小和重试策略 | 突发客户端会触及稳定客户端从未见过的限制。 |
| 症状：WebSocket 断开连接 | 重连逻辑、心跳和重新订阅行为 | 流会断开；没有重新订阅，你会静默停止接收更新。 |
为链上侧选择基础设施
如果你的 Polymarket 集成在 Polygon 上读取密集，决策主要关乎一致性和余量。托管 RPC API 通常是最快的路径：你获得一个端点，无需运行节点，并且可以随着应用增长扩展请求量。
当你需要隔离容量、自定义配置或用于历史分析的归档深度访问时，专用节点是有意义的。这需要更多的运维工作，但消除了吵闹邻居效应。
使用 RPC 提供商选择指南 来组织比较，并查看 Polygon 网络页面 了解端点详情。如果你预计持续负载，请在确定计划之前查看 RPC 定价。
- 托管 RPC API：启动最快，适合大多数应用的默认选择。
- 专用节点：更适合持续高容量或归档工作负载。
- 混合：主要托管端点，第二提供商作为故障转移。
关键要点
Polymarket API 是一个分层系统，你需要的层取决于你是在读取市场数据、交易、流式更新还是验证链上状态。在架构中保持这些关注点分离，大多数集成问题都会变得可处理。
对于链上层，将你的 Polygon RPC 端点视为生产基础设施：批处理读取、固定区块号并计划故障转移。OnFinality 的 RPC API 和专用节点产品覆盖 Polygon 和许多其他网络，网络页面 列出了当前支持的内容。
- 首先确定你的层：市场数据、CLOB、WebSocket 或链上 RPC。
- 将经过身份验证的交易调用保留在后端。
- 固定区块号以实现可重现的链上读取。
- 显式设计重试和重连。
- 在扩展链上读取之前比较托管 RPC 和专用节点。
常见问题
Polymarket API 与 Polygon RPC 端点相同吗？
不相同。Polymarket API 通过链下 HTTP 和 WebSocket 服务涵盖市场数据、订单簿和交易。Polygon RPC 端点让你直接读取区块链，这是结算验证、合约状态和事件核对所需要的。
读取 Polymarket 市场数据需要 API 密钥吗？
公共市场数据端点通常无需凭证即可读取，而交易和账户端点需要身份验证。请查看 Polymarket 的当前文档以了解确切的方案，因为认证细节可能会变化。
我可以为 Polymarket 机器人使用公共 Polygon RPC 端点吗？
测试时可以使用，但公共端点是共享的，可能会限制突发流量。对于持续轮询或事件核对，托管 RPC API 或专用节点通常更可预测。
如何将 Polymarket API 数据与链上状态进行核对？
为你的链上读取固定一个区块号，将其与大约同一时间捕获的 API 响应进行比较，并检查待处理交易。将区块号与结果一起记录，以便以后解释差异。
OnFinality 提供 Polygon RPC 访问吗？
OnFinality 在许多网络上提供 RPC API 访问和专用节点基础设施。请查看支持的网络页面和 Polygon 网络页面以了解当前端点和计划详情。
Ethereum
Solana
Polygon
Base
Arbitrum
BNB链
Polkadot
Optimism
