polymarket-api

Polymarket API 統合スキル

概要

このスキルは、Polymarket の API とスマートコントラクトとの統合に関する包括的なガイダンスを提供します。

API エンドポイント

CLOB API (Central Limit Order Book)

ベース 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 (Good Till Cancelled): 約定またはキャンセルされるまで有効
• GTD (Good Till Date): 指定された時刻に失効
• FOK (Fill or Kill): 全量約定しなければキャンセル
• IOC (Immediate or Cancel): 約定可能な分を約定し、残りはキャンセル

手数料モデル

Polymarket のテイカーのみの計算式 (docs.polymarket.com/trading/fees、2026-09-04 取得):

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

ここで:

• C = コントラクト数 (解決時に 1 コントラクトあたり $1)
• rate = テイカー手数料率 (カテゴリ依存、メイカーは支払い不要)
• p = 約定価格、[0, 1] の範囲の確率
• (1 − p) = 手数料項。p=0.5 (コイントス) で最大となり、裾 (p→0 または p→1) では消滅します

カテゴリ別テイカー手数料率 (USDC で請求):

カテゴリ	手数料率
Crypto	0.07
Sports / Economics / Culture / Weather / Other	0.05
Finance / Politics / Mentions / Tech	0.04
Geopolitics	0.00

マーケットごとのオーバーライド: CLOB のマーケットペイロードには maker_base_fee/taker_base_fee (歴史的なフィールド名) が含まれる場合があり、存在する場合はカテゴリテーブルよりも優先されます。これらのフィールドは無次元の手数料率ではなくベーシスポイントです — taker_base_fee=700 は 700 ではなく 0.07 を意味します。FeeSchedule が期待する手数料率を得るには 10_000 で割ってください (app/venues/polymarket/adapter.py はこれらのフィールドを読み取る 2 か所でこれを行っています)。そのうえで、category_rate() からではなくペイロードから (source="clob_market" として) 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",
}