Polymarket API Integration Skill

Overview

This skill provides comprehensive guidance for integrating with Polymarket's APIs and smart contracts.

API Endpoints

CLOB API (Central Limit Order Book)

Base URL: https://clob.polymarket.com

#### Authentication Levels

• Level 0 (Public): Market data, orderbooks, prices

• Level 1 (Signer): Create/derive API keys

• Level 2 (Authenticated): Trading, orders, positions

#### Key Endpoints

GET  /markets              # List all markets

GET  /markets/{token_id}   # Get specific market

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 (Market Metadata)

Base 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 Implementation Patterns

Initialize Client

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 Subscription

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 Client

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()

Order Types

• GTC (Good Till Cancelled): Stays until filled or cancelled

• GTD (Good Till Date): Expires at specified time

• FOK (Fill or Kill): Must fill entirely or cancel

• IOC (Immediate or Cancel): Fill what's available, cancel rest

Price Calculations

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

Error Handling

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

Rate Limits

• Public endpoints: ~100 requests/minute

• Authenticated endpoints: ~1000 requests/minute

• WebSocket: Varies by subscription type

Always implement exponential backoff and request queuing.

Key Contract Addresses (Polygon)

CONTRACTS = {

    "CTF_EXCHANGE": "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E",

    "NEG_RISK_CTF_EXCHANGE": "0xC5d563A36AE78145C45a50134d48A1215220f80a",

    "CONDITIONAL_TOKENS": "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045",

    "USDC": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",

}