polymarket-api

Polymarket API 集成技能

概述

本技能全面介绍如何集成 Polymarket 的 API 和智能合约。

API 端点

CLOB API（中央限价订单簿）

基础 URL：https://clob.polymarket.com

身份验证级别

• 级别 0（公开）：市场数据、订单簿、价格
• 级别 1（签名者）：创建／派生 API 密钥
• 级别 2（已验证身份）：交易、订单、持仓

主要端点

GET  /markets              # List all markets
GET  /markets/{condition_id}  # Get specific market (condition_id is the
                               # MARKET key; token_id is the per-outcome
                               # BOOK key used by /price, /midpoint, /book
                               # below — the two are not interchangeable)
GET  /price?token_id=X     # Get current price
GET  /midpoint?token_id=X  # Get midpoint price
GET  /book?token_id=X      # Get orderbook
GET  /trades               # Get user trades
POST /order                # Place order
DELETE /order/{id}         # Cancel order
GET  /positions            # Get positions

Gamma API（市场元数据）

基础 URL：https://gamma-api.polymarket.com

GET /events              # List events
GET /events/{slug}       # Get event details
GET /markets             # List markets
GET /markets/{id}        # Get market details

Python 实现模式

初始化客户端

from py_clob_client.client import ClobClient
from py_clob_client.clob_types import OrderArgs, OrderType
import os

class PolymarketService:
    def __init__(self):
        self.client = ClobClient(
            host="https://clob.polymarket.com",
            key=os.getenv("POLYMARKET_PRIVATE_KEY"),
            chain_id=137,
            signature_type=1,
            funder=os.getenv("POLYMARKET_FUNDER_ADDRESS")
        )
        self.client.set_api_creds(
            self.client.create_or_derive_api_creds()
        )
    
    async def get_market_data(self, token_id: str) -> dict:
        """Fetch comprehensive market data."""
        return {
            "price": self.client.get_price(token_id, "BUY"),
            "midpoint": self.client.get_midpoint(token_id),
            "book": self.client.get_order_book(token_id),
            "spread": self.client.get_spread(token_id),
        }
    
    async def place_order(
        self,
        token_id: str,
        side: str,
        price: float,
        size: float,
        order_type: str = "GTC"
    ) -> dict:
        """Place a limit order."""
        order = self.client.create_order(
            OrderArgs(
                token_id=token_id,
                price=price,
                size=size,
                side=side,
            )
        )
        return self.client.post_order(order, order_type)

WebSocket 订阅

import asyncio
import websockets
import json

async def subscribe_market_updates(token_ids: list[str]):
    """Subscribe to real-time market updates."""
    uri = "wss://ws-subscriptions-clob.polymarket.com/ws/market"
    
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "type": "subscribe",
            "markets": token_ids
        }))
        
        async for message in ws:
            data = json.loads(message)
            yield data

Gamma API 客户端

import httpx

class GammaClient:
    BASE_URL = "https://gamma-api.polymarket.com"
    
    def __init__(self):
        self.client = httpx.AsyncClient(base_url=self.BASE_URL)
    
    async def get_active_markets(self) -> list[dict]:
        """Fetch all active markets."""
        response = await self.client.get("/markets", params={"active": True})
        return response.json()
    
    async def get_event(self, slug: str) -> dict:
        """Fetch event with all markets."""
        response = await self.client.get(f"/events/{slug}")
        return response.json()

订单类型

• GTC（撤销前有效）：持续有效，直到成交或撤销
• GTD（指定日期前有效）：在指定时间到期
• FOK（全部成交或撤销）：必须全部成交，否则撤销
• IOC（立即成交或撤销）：成交可用部分，其余撤销

费用模型

Polymarket 仅向吃单方收费的公式（docs.polymarket.com/trading/fees，获取于 2026-09-04）：

fee = C × rate × p × (1 − p)

其中：

• C = 合约数量（结算时每份合约价值 $1）
• rate = 吃单费率（因类别而异，挂单方始终不付费）
• p = 成交价格，即 [0, 1] 范围内的概率
• (1 − p) = 费用项；在 p=0.5（抛硬币）时达到最大值，在尾部（p→0 或 p→1）趋近于零

各类别的吃单费率（以 USDC 收取）：

类别	费率
加密货币	0.07
体育 / 经济 / 文化 / 天气 / 其他	0.05
金融 / 政治 / 提及 / 科技	0.04
地缘政治	0.00

单个市场的覆盖值：CLOB 市场载荷可能包含 maker_base_fee/taker_base_fee（历史字段名称）；如果存在，这些字段优先于类别费率表。这些字段的单位是基点，而非无量纲费率——taker_base_fee=700 表示 0.07，而不是 700。构建 FeeSchedule 时，应先除以 10_000，将其转换为 FeeSchedule 所需的费率（app/venues/polymarket/adapter.py 在读取这些字段的两个位置都执行了此操作），然后从载荷（source="clob_market"）而非 category_rate() 构建 FeeSchedule。如果漏掉除法，费用就会出错 10,000 倍。

挂单费：Polymarket CLOB 始终为 0；该平台仅向吃单方收费。

价格计算

def calculate_implied_probability(price: float) -> float:
    """Convert price to implied probability."""
    return price  # Prices ARE probabilities (0-1)

def calculate_cost(price: float, shares: float) -> float:
    """Calculate cost to buy shares."""
    return price * shares

def calculate_pnl(
    entry_price: float,
    current_price: float,
    shares: float,
    side: str
) -> float:
    """Calculate unrealized P&L."""
    if side == "BUY":
        return (current_price - entry_price) * shares
    return (entry_price - current_price) * shares

错误处理

from py_clob_client.exceptions import PolymarketException

try:
    result = client.post_order(order)
except PolymarketException as e:
    if "INSUFFICIENT_BALANCE" in str(e):
        # Handle insufficient funds
        pass
    elif "INVALID_PRICE" in str(e):
        # Handle price out of range
        pass
    raise

速率限制

• 公开端点：约 100 次请求／分钟
• 已验证身份的端点：约 1000 次请求／分钟
• WebSocket：因订阅类型而异

务必实现指数退避和请求排队。

主要合约地址（Polygon）

CONTRACTS = {
    "CTF_EXCHANGE": "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E",
    "NEG_RISK_CTF_EXCHANGE": "0xC5d563A36AE78145C45a50134d48A1215220f80a",
    "CONDITIONAL_TOKENS": "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045",
    "USDC": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
}