如何使用 Polymarket API：开发者完整指南 (2026)

如何使用 Polymarket API：完整开发者指南 (2026)

Polymarket 是全球最大的预测市场平台，允许用户对现实世界事件的结果进行交易。无论您是想构建仪表板、自动化交易策略，还是将市场数据引入您的应用程序，Polymarket API 都能为您提供对平台一切功能的编程访问权限。

本指南将演示 Polymarket API 的完整设置流程，从身份验证到完成第一笔交易，并提供 Python 和 JavaScript 的示例代码。

Polymarket API 概览

Polymarket 提供两个主要的 API：

API	用途	身份验证	速率限制
CLOB API	交易、下单、市场数据	API key + secret	100 次请求/分钟
Gamma API	公开市场数据、事件、元数据	无 (公开)	300 次请求/分钟

CLOB (Central Limit Order Book) API 是进行交易所需的接口。Gamma API 是一个只读的 REST API，用于获取市场信息、事件详情和历史数据，无需身份验证。

第 1 步：获取您的 Polymarket API Key

要使用 CLOB API，您需要一个与您的 Polymarket 钱包绑定的 API key。

1. 访问 polymarket.com 并连接您的钱包或创建账户。
2. 导航至账户设置并找到 API 部分。
3. 生成新的 API key 和 secret。请安全保存这些信息——您将无法再次看到 secret。

对于 Gamma API，不需要身份验证。您可以立即开始发起请求。

第 2 步：使用 Gamma API 获取市场数据

Gamma API 是最简单的入门方式。它返回有关所有活跃市场的结构化数据。

列出所有活跃市场

import requests

# 从 Polymarket Gamma API 获取活跃市场
response = requests.get(
    "https://gamma-api.polymarket.com/markets",
    params={
        "active": "true",
        "limit": 10,
        "order": "volume24hr",
        "ascending": "false"
    }
)

markets = response.json()

for market in markets:
    print(f"问题: {market['question']}")
    print(f"交易量 (24h): ${market.get('volume24hr', 0):,.2f}")
    print(f"流动性: ${market.get('liquidity', 0):,.2f}")
    print("---")

// Node.js / fetch 示例
const response = await fetch(
  "https://gamma-api.polymarket.com/markets?" +
  new URLSearchParams({
    active: "true",
    limit: "10",
    order: "volume24hr",
    ascending: "false"
  })
);

const markets = await response.json();

markets.forEach(market => {
  console.log(`问题: ${market.question}`);
  console.log(`交易量 (24h): $${Number(market.volume24hr || 0).toLocaleString()}`);
  console.log(`流动性: $${Number(market.liquidity || 0).toLocaleString()}`);
  console.log("---");
});

通过 ID 获取特定市场

import requests

market_id = "0x1234..."  # 替换为实际的 condition ID

response = requests.get(
    f"https://gamma-api.polymarket.com/markets/{market_id}"
)

market = response.json()
print(f"问题: {market['question']}")
print(f"描述: {market['description']}")
print(f"结束日期: {market['endDate']}")

通过关键词搜索市场

import requests

response = requests.get(
    "https://gamma-api.polymarket.com/markets",
    params={
        "tag": "politics",
        "active": "true",
        "limit": 5
    }
)

markets = response.json()
for m in markets:
    print(f"{m['question']} — 交易量: ${m.get('volume24hr', 0):,.0f}")

第 3 步：连接到 CLOB API 进行交易

CLOB API 允许您下单和管理订单。它需要使用您的 API 凭据进行加密身份验证。

安装 Python 客户端

pip install py-clob-client

初始化客户端

from py_clob_client.client import ClobClient
from py_clob_client.clob_types import ApiCreds

# 您的凭据
host = "https://clob.polymarket.com"
chain_id = 137  # Polygon 主网
private_key = "0xYOUR_PRIVATE_KEY"

# 初始化客户端
client = ClobClient(
    host,
    key=private_key,
    chain_id=chain_id
)

# 派生 API 凭据
api_creds = client.create_or_derive_api_creds()
client.set_api_creds(api_creds)

print("已连接到 Polymarket CLOB API")

获取订单簿数据

# 获取特定市场的订单簿
token_id = "71321045..."  # 特定结果的 token ID

order_book = client.get_order_book(token_id)

print("买单 (Bids):")
for bid in order_book.bids[:5]:
    print(f"  价格: {bid.price} | 数量: {bid.size}")

print("卖单 (Asks):")
for ask in order_book.asks[:5]:
    print(f"  价格: {ask.price} | 数量: {ask.size}")

发布限价单

from py_clob_client.order_builder.constants import BUY

# 创建并签署限价单
order_args = {
    "token_id": "71321045...",
    "price": 0.55,        # USDC 价格 (0.55 = 55 分 = 55% 概率)
    "size": 100,           # 份数
    "side": BUY,
    "fee_rate_bps": 0,     # 以基点计的费率
}

signed_order = client.create_and_post_order(order_args)
print(f"订单已发布: {signed_order}")

取消订单

# 取消特定订单
order_id = "0xABC123..."
result = client.cancel(order_id)
print(f"订单已取消: {result}")

# 取消所有未成交订单
result = client.cancel_all()
print(f"所有订单已取消: {result}")

第 4 步：使用 WebSocket 流式传输实时数据

Polymarket 提供 WebSocket 连接，用于实时价格更新和订单簿变更。

import asyncio
import websockets
import json

async def stream_market_data():
    uri = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

    async with websockets.connect(uri) as ws:
        # 订阅一个市场
        subscribe_msg = {
            "type": "subscribe",
            "market": "71321045...",  # Token ID
            "channel": "price"
        }
        await ws.send(json.dumps(subscribe_msg))
        print("已订阅价格更新")

        async for message in ws:
            data = json.loads(message)
            print(f"价格更新: {data}")

asyncio.run(stream_market_data())

第 5 步：构建简单的市场仪表板

这是一个实用的示例，获取顶级市场并将其显示在格式化的表格中。

import requests
from tabulate import tabulate

def get_top_markets(limit=10):
    response = requests.get(
        "https://gamma-api.polymarket.com/markets",
        params={
            "active": "true",
            "limit": limit,
            "order": "volume24hr",
            "ascending": "false"
        }
    )
    return response.json()

def format_market_table(markets):
    rows = []
    for m in markets:
        rows.append([
            m["question"][:60],
            f"${float(m.get('volume24hr', 0)):,.0f}",
            f"${float(m.get('liquidity', 0)):,.0f}",
            m.get("endDate", "N/A")[:10]
        ])

    headers = ["市场", "24h 交易量", "流动性", "结束日期"]
    return tabulate(rows, headers=headers, tablefmt="grid")

markets = get_top_markets()
print(format_market_table(markets))

Polymarket API 速率限制与最佳实践

端点	速率限制	建议间隔
Gamma API (公开)	300 次/分钟	请求间距 200ms
CLOB REST API	100 次/分钟	请求间距 600ms
WebSocket	无硬性限制	每 30 秒发送一次心跳 (heartbeat ping)
订单发布	10 单/秒	尽可能使用批量处理

最佳实践

• 缓存市场数据。 市场元数据不会频繁更改。请在本地缓存并在每 5-10 分钟刷新一次。
• 使用 WebSocket 获取实时数据。 轮询 REST API 会浪费速率限制额度。使用 WebSocket 订阅来获取实时价格推送。
• 妥善处理 429 错误。 当达到速率限制时，实施指数退避算法 (exponential backoff)。
• 将 API key 存储在环境变量中。 永远不要在代码中硬编码私钥或 API secret。

import os

# 从环境变量加载
api_key = os.environ.get("POLYMARKET_API_KEY")
api_secret = os.environ.get("POLYMARKET_API_SECRET")
private_key = os.environ.get("POLYMARKET_PRIVATE_KEY")

常见 API 响应代码

代码	含义	采取措施
200	成功	处理响应
400	错误请求	检查参数
401	未授权	验证 API 凭据
404	未找到	检查市场/订单 ID
429	触发速率限制	退避并重试
500	服务器错误	延迟后重试

常见问题解答

Polymarket API 是免费的吗？ 是的。Gamma API 完全免费，无需身份验证。CLOB API 也是免费使用的，但进行交易需要一个注资过的 Polymarket 账户。

Polymarket 使用的是哪种区块链？ Polymarket 在 Polygon（链 ID 137）上运行。您需要 Polygon 上的 USDC 进行交易。

我可以使用 API 运行自动交易机器人吗？ 可以。CLOB API 专为编程交易设计。许多用户都在运行自动化策略。请注意关于市场操纵的服务条款。

是否有沙盒或测试网？ Polymarket 偶尔会为开发者提供测试网环境。请查看他们的 Discord 和官方文档以获取最新信息。

支持哪些编程语言？ 官方客户端库是 Python 版 (py-clob-client)。REST 和 WebSocket API 可用于任何支持 HTTP 请求的语言。

总结

Polymarket API 是目前最易访问的预测市场 API 之一。公开的 Gamma API 无需任何设置即可读取市场数据，而 CLOB API 通过 Python 客户端支持为您提供完整的交易能力。

如果您正在构建整合预测市场数据的 AI 驱动型应用程序或生成式媒体，免费试用 Hypereal AI —— 35 个积分，无需信用卡。它为图像、视频和头像生成提供简单的 API，能够与数据驱动型应用程序完美配合。