摘要
如果你搜索了 Polymarket API 文档，你可能想做三件事之一：读取实时市场和事件数据、流式获取订单簿和交易，或者以编程方式下单和管理订单。这些任务由不同的 API 提供，最快的路径是在阅读任何端点参考之前，先确定哪个 API 与你的工作负载匹配。
在高层次上，Polymarket 的表面分为公共读取侧（市场、事件、系列、订单簿、价格历史、搜索）和认证交易侧（订单、投资组合、余额和私有 WebSocket 流）。第三方数据产品也存在于历史和分析用例中。每个都有自己的基础 URL、认证模型和速率行为，因此混淆它们是最常见的困惑来源。
还有一个链上层。Polymarket 活动在 Polygon 上结算，这意味着需要验证结算、索引钱包活动或核对自身记录的团队最终需要在 REST API 之外使用 Polygon RPC 端点。OnFinality 为 Polygon 和其他支持的网络提供 RPC API 访问和专用节点基础设施，当你的集成超出公共端点时。
本页映射了文档景观，展示了如何为你的工作负载选择正确的 API，并涵盖了参考文档假设你已经知道的运营细节——密钥、分页、WebSocket 和 Polygon RPC。
关键要点
- Polymarket 提供用于市场、事件和订单簿的公共读取 API，以及用于订单、投资组合和余额的认证 API——首先决定你的应用属于哪一侧。
- 实时订单簿和交易数据通过 WebSocket 流传递，这需要与 REST 轮询不同的重连和背压处理。
- 第三方数据 API 和 SDK 可以简化分析工作，但在依赖它们之前，应确认新鲜度、覆盖范围和许可。
- Polymarket 结算发生在 Polygon 上，因此大多数严肃的集成还需要一个可靠的 Polygon RPC 端点来进行验证和索引。
- 将 API 密钥、分页限制和速率行为视为设计约束，而不是事后考虑——它们塑造你的缓存和重试逻辑。
- 对于生产工作负载，根据你的读取量、归档需求和故障转移要求评估托管 RPC 和专用节点。
哪个 Polymarket API 适合你的工作负载？
文档集看起来很大，因为它涵盖了多个不同的产品。在阅读端点参考之前，决定你的应用程序实际使用 Polymarket 数据做什么。这个单一决定消除了大部分文档。
使用下表作为路由指南。它不是官方参考的替代品，但它告诉你首先打开哪个参考。
- 如果你在显示数据，从公共读取 API 开始；它从你的第一个原型中移除了认证。
- 仅当你需要账户范围的操作时，才添加认证 API。
- 如果你的 UI 显示实时价格，尽早规划 WebSocket——后期改造流式传输比设计时考虑更费力。
| 标准 | 检查内容 | 为什么重要 |
|---|---|---|
| 读取市场和事件数据 | 公共读取 API（市场、事件、系列、订单簿、价格历史、搜索） | 浏览不需要 API 密钥，因此你可以立即原型设计并积极缓存。 |
| 下单或管理订单 | 需要 API 密钥设置的认证交易 API | 每个请求都绑定到账户，因此密钥处理、权限和错误处理成为设计的一部分。 |
| 流式获取实时价格和交易 | 用于订单簿和交易的公共 WebSocket 通道 | 流式传输避免了轮询成本，但需要重连逻辑和消息顺序处理。 |
| 流式获取私有账户更新 | 用于订单、头寸、余额的认证 WebSocket 通道 | 这些通道携带账户状态，因此认证和会话生命周期比原始吞吐量更重要。 |
| 历史分析和研究 | 第三方数据 API 和社区 SDK | 覆盖范围、更新频率和条款因提供商而异；在构建产品之前进行验证。 |
| 验证链上结算 | 用于日志、收据和合约读取的 Polygon RPC 端点 | REST API 描述平台状态；链是结算和核对的真相来源。 |
公共读取 API：无需密钥即可获得的内容
文档的公共侧涵盖发现和市场数据：列出市场和事件、获取订单簿和最佳买卖报价、结算价格、价格历史以及跨事件和市场的全文搜索。由于不需要密钥，这是开始任何只读集成的正确位置。
这里的实际约束不是认证而是量。市场和事件列表不断变化，对大型列表进行简单的轮询会耗尽你的请求预算。为列表端点设计具有短生存时间的缓存层，为历史数据设计更长的生存时间，并对任何必须近实时更新的内容优先使用 WebSocket 流。
- 缓存列表端点；它们是大多数只读应用中调用量最高的。
- 有意识地使用分页——只获取你的 UI 实际渲染的页面。
- 将历史价格查询与实时价格查询分开，以便你可以独立调整每个。
认证交易 API：密钥、作用域和故障处理
认证 API 是订单、投资组合、余额和购买力所在的地方。每个请求都携带 API 密钥，因此文档的认证页面是首先要读的——而不是订单端点。密钥发放、环境分离和权限范围决定了你如何构建服务。
将交易调用视为状态改变操作。这意味着在 API 支持的地方使用幂等性，显式处理被拒绝和部分成交的订单，并记录捕获请求标识符的日志，以便支持人员可以追踪问题。永远不要将密钥嵌入客户端代码；通过你控制的后端服务路由交易调用。
- 将密钥存储在秘密管理器中，而不是提交到仓库的环境文件中。
- 如果平台允许，将读和写凭据分开。
- 为每个订单操作记录请求和响应标识符——在事件审查期间你会需要它们。
WebSocket 流与 REST 轮询
平台的公共侧和认证侧都暴露 WebSocket 端点，在流式传输和轮询之间选择是 Polymarket 集成中最大的架构决策之一。轮询实现更简单，调试更容易；流式传输在大规模下更便宜，并提供更新鲜的数据。
如果你使用流式传输，为连接生命周期工作预留时间：带退避的重连、重连后重新订阅、通过心跳检测陈旧连接，并在状态减速器中处理乱序或重复消息。静默死亡的流比轮询更糟糕，因为你的 UI 会继续显示陈旧价格而没有任何错误。
- 添加心跳检查，在定义的静默窗口后将流标记为不健康。
- 每次重连后显式重新订阅；不要假设服务器恢复订阅。
- 为关键视图保留 REST 回退，以便流中断时优雅降级。
| 标准 | 检查内容 | 为什么重要 |
|---|---|---|
| 数据新鲜度 | 价格和订单簿使用流式传输；静态元数据可接受轮询 | 陈旧价格会误导用户并可能触发错误的自动决策。 |
| 成本概况 | 流式传输减少请求量；轮询随用户线性扩展 | 请求预算和速率行为塑造你的基础设施账单。 |
| 故障可见性 | 流上的心跳和陈旧检测 | 静默流死亡是流式应用中最常见的生产事件。 |
| 复杂性 | 重连、重新订阅和消息去重逻辑 | 低估这项工作通常是延迟发布的原因。 |
Polygon RPC 在哪里进入画面
Polymarket 活动在 Polygon 上结算。REST 和 WebSocket API 告诉你平台报告的内容；链告诉你实际发生了什么。如果你核对成交、验证结算交易、索引钱包活动或构建基于链上事件的分析，你需要在 Polymarket API 之外使用 Polygon RPC 端点。
对于轻量验证，托管 RPC 端点通常就足够了。对于日志密集型索引、长范围归档查询或跟踪式调试，专用节点为你提供隔离容量和可预测行为。OnFinality 提供 RPC API 访问和专用节点，你可以查看 Polygon 网络页面了解端点详情，并在承诺前查看 RPC 定价。
- 使用 RPC 获取收据、日志和合约读取——而不是市场元数据，REST API 已经提供了这些。
- 批处理和缓存 eth_getLogs 查询；宽块范围是超时最常见的原因。
- 将你的 RPC 提供商与数据提供商分开，以便一次中断不会同时拖垮两条路径。
生产就绪检查清单
一旦你的集成在沙盒中工作，剩下的工作是运营。使用此清单决定你是否准备好发布，以及哪些基础设施决策仍需做出。
- 使用真实的列表分页进行负载测试，而不仅仅是单记录获取。
- 运行故障演练：杀死一个流和一个主 RPC 端点，确认你的应用干净地降级。
| 标准 | 检查内容 | 为什么重要 |
|---|---|---|
| 密钥管理 | 秘密集中存储、按计划轮换、按服务划分范围 | 泄露的交易密钥是直接的财务风险。 |
| 速率行为 | 客户端节流、带退避的重试和突发流量队列 | 不受控制的重试会放大中断而不是从中恢复。 |
| 流健康 | 心跳、陈旧警报和自动重新订阅 | 在用户看到错误价格之前检测静默故障。 |
| 链上验证 | 具有故障转移和日志查询限制理解的 RPC 端点 | 如果 RPC 调用超时，结算核对会静默失败。 |
| 可观测性 | 仪表板上的请求延迟、错误率和流重连计数 | 你无法调试你没有测量的东西。 |
| 回退路径 | 流的 REST 回退、读取的辅助 RPC | 在部分中断期间保持核心视图工作。 |
常见文档陷阱及如何避免
围绕 Polymarket API 文档的大多数困惑来自混合环境和产品。美国文档、国际文档和第三方数据产品描述了不同的表面，具有不同的基础 URL 和认证模型。将其中一个的片段复制到为另一个构建的项目中是导致令人困惑的 401 或 404 的最快方式。
第二个陷阱是将社区 gist 和 SDK 包装器视为权威。它们对定位有用，但端点路径、参数和限制可能会漂移。根据你实际集成的产品的官方参考确认你依赖的任何内容，并固定你的 SDK 版本，以便上游更改不会在一夜之间破坏你的构建。
- 在代码注释中记录每个端点来自哪个文档产品。
- 在锁文件中固定 SDK 和客户端库版本。
- 在主要版本发布前重新阅读变更日志；API 表面会演变。
常见问题
有官方的 Polymarket API 吗？
是的。Polymarket 发布了公共读取 API 的文档，涵盖市场、事件和订单簿，以及认证 API 的文档，涵盖订单、投资组合和账户数据，还有用于实时更新的 WebSocket 流。始终根据你正在集成的产品和地区的官方参考确认细节。
我需要 API 密钥来读取 Polymarket 市场数据吗？
用于市场、事件、系列、订单簿和搜索的公共读取端点设计为无需 API 密钥即可使用。用于交易和账户状态的认证端点需要密钥设置。检查当前文档以了解适用于未认证流量的任何限制。
我可以获取实时 Polymarket 数据吗？
是的，通过 WebSocket 端点。公共通道流式传输订单簿和交易更新，而认证通道流式传输私有订单、头寸和余额变化。从一开始就规划重连、重新订阅和陈旧检测。
为什么 Polymarket 集成需要 Polygon RPC 端点？
Polymarket 在 Polygon 上结算。如果你需要验证结算交易、索引链上事件或根据链核对自身记录，你需要在 Polymarket REST 和 WebSocket API 之外访问 Polygon 的 RPC。
第三方 Polymarket 数据 API 对于生产足够可靠吗？
它们对于历史分析和研究可能有用，但覆盖范围、新鲜度和条款因提供商而异。在依赖第三方来源用于任何面向用户的内容之前，根据官方 API 或链上记录验证数据。
Ethereum
Solana
Polygon
Base
Arbitrum
BNB链
Polkadot
Optimism
