Polymarket API 指南 - 在 2026 年构建你的第一个交易机器人

第 27 章，共 33 章

简短版本

Polymarket 提供 三个公开 API：CLOB（交易）、Gamma（市场发现）和 Data（分析）。官方 Python SDK 是 py-clob-client 0.34.6。认证使用 API key + ECDSA 签名，订单通过 Polygon 代理钱包使用 EIP-712 进行签名。速率限制将你限制在每个 key 约 60 个订单/分钟。新开发者最大的坑是 Gamma 和 CLOB 之间的 condition_id → token_id 映射问题 - 先把这个解决，其他事情就会顺理成章。Polymarket 上每月大约有 4000 万美元/月 的流动性奖励和机器人捕获的价差被赚走，几乎全部由 API 用户获得。

第1部分: 三个 API

Polymarket 将职责清晰地拆分到三个不同的服务中。针对每项任务使用正确的 API，能让你的机器人保持快速、简单，并且不超出速率限制。

典型的机器人循环会使用 Gamma 来寻找市场，使用 CLOB 来获取订单簿并执行交易，使用 Data 在离线环境中回测策略表现。可以把 Gamma 看作“目录”，把 CLOB 看作“交易所”，把 Data 看作“仓库”。

第 2 部分：身份验证与代理钱包模型

Polymarket 不会用你的主钱包私钥为交易签名。相反，它使用一个类似 Gnosis Safe 的代理钱包：你的主钱包授权一个代理，代理在 Polygon 上执行所有交易。你的 API 机器人与该代理通信。

你需要什么

• API key - 在 Polymarket 设置 → 开发者中生成
• Private key - 你的交易钱包的密钥（不是你的主 MetaMask 助记词）
• Funder address - 你的代理钱包地址（在 设置 → 钱包 中显示）
• Chain ID - 137（Polygon 主网）
• Signature type - 1（POLY_PROXY，面向零售用户的标准类型）

第 3 部分：安装 py-clob-client

官方 Python SDK 是从零到第一笔订单最快的方式。我们将使用 0.34.6 版本，这是截至 2026 年 4 月的当前版本。

# 先创建虚拟环境
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# 安装 SDK
pip install py-clob-client==0.34.6 requests websocket-client python-dotenv

基础客户端配置

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON

load_dotenv()

client = ClobClient(
 host="https://clob.polymarket.com",
 key=os.environ["POLY_PRIVATE_KEY"],
 chain_id=POLYGON, # 137
 signature_type=1, # POLY_PROXY
 funder=os.environ["POLY_FUNDER"],
)

# 仅需一次：派生并缓存 API 凭证
client.set_api_creds(client.create_or_derive_api_creds())

create_or_derive_api_creds() 调用会使用你的私钥对消息签名，并将其换取 API 密钥、密钥和密码短语。首次运行后，请将这些信息缓存到你的 .env 中，这样每次启动时就不必都去调用派生端点。

第 4 部分：通过 Gamma 发现市场

在你开始交易之前，需要先找到值得交易的市场。Gamma 会返回包含 Polymarket UI 展示的一切内容的 JSON：问题、结果、价格、24 小时成交量、到期时间、标签和图片。

import requests

resp = requests.get(
 "https://gamma-api.polymarket.com/markets",
 params={
 "active": "true",
 "closed": "false",
 "tag_slug": "politics",
 "limit": 20,
 "order": "volume24hr",
 "ascending": "false",
 },
 timeout=10,
)
resp.raise_for_status()
markets = resp.json()

for m in markets:
 print(f"{m['slug']:50} Yes ${float(m['outcomePrices'][0]):.3f} Vol24h ${m.get('volume24hr', 0):,.0f}")

有用的 Gamma 查询参数

第 5 部分：condition_id → token_id 映射

这是 Polymarket 机器人开发中的头号痛点。Gamma 会返回一个 condition_id（每个市场一个）。CLOB 交易使用 token_id（每个结果一个）。你总是需要两者。

# Each Gamma market object contains 'clobTokenIds' - a JSON string array
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # First outcome
no_token = token_ids[1] # Second outcome

# Alternative: ask CLOB directly using condition_id
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

结果顺序陷阱

Gamma 的 outcomes 数组和 clobTokenIds 数组在索引上是一一对应的。务必先读取结果标签，而不要假设索引 0 就是 "Yes." 在多结果市场（NegRisk、奥斯卡、选举）中，索引 0 可能是 "Kamala Harris" 或 "Taylor Swift" - 顺序是确定的，但取决于具体市场。

第 6 部分: 读取订单簿

book = client.get_order_book(token_id=yes_token)

best_bid = float(book.bids[0].price) if book.bids else None
best_ask = float(book.asks[0].price) if book.asks else None
mid = (best_bid + best_ask) / 2 if best_bid and best_ask else None
spread = best_ask - best_bid if best_bid and best_ask else None

print(f"Bid {best_bid} Ask {best_ask} Mid {mid:.4f} Spread {spread:.4f}")

订单簿以排序后的数组返回（bids 递减，asks 递增）。每一档都有 price 和 size。要估算更大订单的滑点，沿着订单簿逐档遍历并累加名义金额，直到消耗完你的目标数量。

第 7 部分: 下单

限价单 (GTC - 默认)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # 股数，不是美元。100 股 @ $0.45 = 最高成本 $45。
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

create_order 调用会用你的私钥签署一条 EIP-712 结构化消息。post_order 会将其提交到 CLOB。你永远不会在网络中传输原始私钥 - 只会传输已签名的订单。

订单类型

取消

# 单个订单
client.cancel(order_id="0xabc...")

# 取消特定市场上的所有订单
client.cancel_market_orders(market=market['conditionId'])

# 终极选项: 取消全部
client.cancel_all()

第 8 部分：WebSocket 流式传输

每秒轮询 Gamma 是一种浪费，而且你很快就会碰到速率限制。WebSocket 数据流会以亚秒级延迟实时推送订单簿和交易更新。

import json, websocket

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

def on_open(ws):
 ws.send(json.dumps({
 "type": "market",
 "assets_ids": [yes_token, no_token],
 }))

def on_message(ws, message):
 event = json.loads(message)
 if event.get("event_type") == "price_change":
 print(f"{event['market']} {event['side']} {event['price']} size={event['size']}")

ws = websocket.WebSocketApp(
 WS_URL,
 on_open=on_open,
 on_message=on_message,
)
ws.run_forever(ping_interval=20)

共有两个数据流：/market 数据流（公开订单簿 + 交易）和 /user 数据流（你自己的订单和成交事件，需认证）。生产环境中的机器人通常会同时连接这两个数据流，在断开连接时自动重连，并将 WebSocket 视为当前簿状态的事实来源。

第9部分：速率限制与退避

当你遇到 HTTP 429 时，服务器会返回一个 Retry-After 标头。请实现带抖动的指数退避：

import random, time

def post_with_backoff(fn, *args, max_retries=6):
 for attempt in range(max_retries):
 try:
 return fn(*args)
 except Exception as e:
 if "429" in str(e):
 sleep = (2 ** attempt) + random.random()
 time.sleep(min(sleep, 30))
 continue
 raise
 raise RuntimeError("Too many retries")

第 10 部分：参考机器人架构

每个稳健的 Polymarket 机器人都具有相同的六个组件。将每个组件作为独立模块构建；保持它们松耦合。

第 11 部分：常见故障模式

• 过时的 WebSocket 数据 - 跟踪每个资产的最后一条消息时间；如果某个活跃市场超过 30 秒没有更新，则强制进行 REST 刷新。
• Nonce 冲突 - py-clob-client 会替你处理订单 nonce，但如果你自己实现签名器，就要在每笔订单上递增 nonce。
• 余额不足 - 下单前始终检查 pUSD 余额；订单簿可能显示你的订单，但撮合会拒绝它。
• 市场暂停或进入结算 - 交易前检查 market.active && !market.closed。Gamma 在结算附近的更新会比 CLOB 慢几秒。
• NegRisk 适配器不匹配 - 多结果市场通过单独的 NegRisk 适配器路由。SDK 会处理它，但要确认你的订单去了正确的场所。

第 12 部分：通过 API 获取流动性奖励

Polymarket 每月发放约 500 万美元的一般流动性奖励，以及每月 500 万美元以上的体育专项奖励（见 流动性奖励）。绝大部分奖励流向 API 驱动的做市商，他们能够在成千上万的市场中维持紧密的双边报价。

奖励公式会奖励接近中间价的订单、订单规模以及挂单时长。一个最小化的做市循环：

1. 读取目标市场的订单簿
2. 计算公平的中间价（例如，买卖双方前 3 档的 VWAP）
3. 在 mid - spread_target/2 挂出买单，在 mid + spread_target/2 挂出卖单
4. 每次 WebSocket 更新时，如果你的报价偏离目标超过一个 tick，就重新定价
5. 如果订单簿变薄或有新闻突发，就取消并退出

第 13 部分：投入生产

• 托管：欧洲或美国东部一台每月 6 美元的 VPS（Hetzner、DigitalOcean）对大多数机器人都足够。如果你需要低于 10 毫秒的延迟，就与 Polygon RPC 共置。
• RPC：使用 Alchemy、Infura 或 QuickNode 获取可靠的 Polygon RPC。免费套餐在你每分钟下单数百笔之前都够用。
• 监控：使用 Prometheus + Grafana 做指标监控；用 Telegram 机器人做告警。记录你发送的每个订单 ID 和收到的每次成交。
• 备份：每分钟持久化状态。如果 VPS 在成交中途宕机，你希望能在几秒内恢复，而不是手工对账。
• 税务：你的日志器也是你的审计轨迹 - 见 税务指南。

第 14 部分 - Polymarket API 已验证的专业建议

情境 -> 操作速查表

接下来是什么？

• 工具与资源 - 补充 API 的第三方仪表板、分析工具和数据馈送
• 高级策略 - 适合机器人使用的多腿套利和类期权结构
• 流动性奖励 - 赚取做市返利的精确公式
• 订单簿指南 - 在你开始编写对接代码之前，更深入地理解如何阅读订单簿
• 术语表 - 本指南中每个术语的通俗定义