2026 年的 Polymarket Python SDK（以及如何迁移出 py-clob-client）

这比一次普通的版本升级更重要，原因只有一个：互联网上几乎所有的 Polymarket 代码示例都早于它。博客文章、Stack Overflow 回答、GitHub 示例，以及（因为是用这些材料训练出来的）当你让 AI 助手写一个 Polymarket 机器人时它写出的代码。如果你发现自己在调试根本不存在的导入，这就是原因。

到底变了什么

旧的方式是每个 Polymarket 服务一个客户端。你导入一个 CLOB 客户端处理订单簿，用原始 HTTP 调用 Gamma 发现市场，单独请求 Data API 获取持仓，需要 Relayer 交易时还要引入一个 builder-signing 包。四套心智模型，四种错误格式，四种分页方式。

统一 SDK 把这些合并成一个覆盖所有接口的客户端。

安装

pip install polymarket-client
# uv add polymarket-client
# poetry add polymarket-client

四个客户端：慎重选择

import asyncio
from polymarket import AsyncPublicClient


async def main() -> None:
    async with AsyncPublicClient() as client:
        pages = client.list_markets(closed=False)
        first = await pages.first_page()
        for market in first.items:
            print(market.slug)


asyncio.run(main())

公开数据不需要凭证，所以在引入密钥之前，尽可能对着 AsyncPublicClient 构建和测试一切。市场发现、解析、分页、信号生成和退避都可以在没有任何风险的情况下检验。

分页

所有列表方法共用一个分页器接口。根据你是否关心页面边界，有三种使用方式：

pages = client.list_markets(closed=False, page_size=10)

# 1. Page at a time — use this when you need to control pacing
#    against the tight /markets rate limit (300 req / 10s).
async for page in pages:
    for market in page.items:
        ...

# 2. Item at a time, boundaries ignored.
async for market in pages.iter_items():
    ...

# 3. Manual, resumable.
page = await pages.first_page()
if page.next_cursor:
    nxt = await pages.from_cursor(page.next_cursor).first_page()

类型化模型

方法返回的是真正的类型而不是字典，从顶层包导出：

from polymarket import Event, Market, OrderBook, PriceHistoryPoint

这是最不起眼的改进，却可能是价值最高的。在旧客户端下，一个被重命名或缺失的字段，会在运行时以 KeyError 的形式出现在你策略循环的深处，往往发生在生产环境，往往发生在持仓期间。类型化模型把这种失败移到了它该在的地方。

实时订阅

subscribe() 把多个数据流合并成一个类型化的事件流，相比手动管理多个 WebSocket 连接，这是实实在在的改进。

from polymarket.streams import MarketSpec, SportsSpec

async with await client.subscribe(
    [MarketSpec(token_ids=[token_id]), SportsSpec()],
) as stream:
    async for event in stream:
        # MarketBookEvent | MarketPriceChangeEvent
        # | MarketLastTradePriceEvent | MarketTickSizeChangeEvent
        # | MarketBestBidAskEvent | NewMarketEvent
        # | MarketResolvedEvent | SportsEvent
        handle(event)

SDK 会处理你原本需要自己实现的心跳、帧和重连，包括在原始连接上每 10 秒发送一次 PING 的要求。详见 WebSocket 指南。

下单

market = await client.get_market(slug="<market-slug>")
token_id = market.outcomes.yes.token_id
assert token_id is not None

response = await client.place_market_order(
    token_id=token_id,
    side="BUY",
    amount="10",     # pUSD to spend, not shares to buy
)

if not response.ok:
    raise RuntimeError(response.message)

# Settlement is on-chain and asynchronous.
hashes = await client.wait_for_order_fill_settlement(response)

# Reconcile rather than assuming.
page = await client.list_positions(market=[market.condition_id]).first_page()
position = next((p for p in page.items if p.token_id == token_id), None)

从 py-clob-client 迁移

1. 盘点每一个 Polymarket 调用，包括对 Gamma 和 Data API 的原始 requests 调用。它们也在迁移范围内：统一 SDK 覆盖了它们，把它们并进来就是大部分的收益。
2. 安装 polymarket-client，移除旧包。为了逐步迁移而同时保留两者，容易导入错误的 client 符号。
3. 替换客户端的构造方式。一个 AsyncSecureClient.create(...) 取代了旧的各服务客户端以及它们各自的凭证处理。
4. 把字典访问改为属性访问。market["condition_id"] 变成 market.condition_id。很繁琐，但这正是类型检查器开始发挥价值的地方。
5. 重写分页，改用分页器接口，而不是手动的 offset 或游标循环。
6. 用 subscribe() 替换手写的 WebSocket 代码，并删除你的心跳和重连逻辑。
7. 先重新运行只读路径，对着公开客户端运行，然后再让任何东西下单。

为什么你的 AI 助手会写错

值得直接说一说，因为很多人就是因此来到这里的。让一个 LLM 写 Polymarket 的 Python 代码，你经常会得到 py_clob_client 导入、ClobClient(...) 构造和 OrderArgs 对象。模型并没有出故障：它只是在复现它见过的绝大多数 Polymarket 代码，而这些代码都早于统一 SDK。

• 先检查导入行。from polymarket import ... 是当前的写法；from py_clob_client... 不是。
• 把当前文档粘贴到上下文中。Polymarket 在 docs.polymarket.com/llms.txt 发布了机器可读的 Markdown，每个页面都有 .md 版本。给模型提供真实的文档，胜过和它争论。
• 不要相信那些自信满满却跑不起来的代码。生成的代码经常把新旧 API 混在一起，拼出一个从未存在过的东西。

同样的问题也存在于数据提供商。我们发布了 llms.txt、llms-full.txt 和一份 OpenAPI 规范，并允许 AI 爬虫访问，正是为了让助手无需猜测就能写出正确的 PolyTest 集成。有些提供商屏蔽了这些爬虫，这是合理的选择，但意味着你的助手会自己编造他们的 API 接口。

SDK 仍然做不到的事

统一 SDK 是一个好得多的 Polymarket API 接口。但它并不会改变这些 API 所包含的内容，而机器人开发者最常想要的东西并不在其中。

没有历史订单簿。client.get_market() 会返回已结算市场的元数据，但它的订单簿已经没了：/book 返回 404，prices-history 只保留大约每分钟一个点。没有任何 SDK 方法、套餐或凭证能找回订单簿。

要回测，你需要在市场运行期间记录的快照。PolyTest 为加密货币 Up/Down 市场提供这些快照：240M+ 条时点快照，每边 8 档深度，亚秒级时间戳，已结算的市场也会保留。它是一个普通的 REST API，使用 X-API-Key 请求头，可以直接放进与 SDK 相同的异步代码中。免费开始，或阅读如何构建机器人了解完整流程。