Polymarket Clob Api

Authentication Levels

Source: https://docs.polymarket.com/developers/CLOB/authentication

For research and analysis, only Public methods are needed.

Public REST Endpoints (No Auth Required)

Source: https://docs.polymarket.com/developers/CLOB/clients/methods-public

Single-Token Endpoints

GET /price — Current Price

Ref: https://docs.polymarket.com/api-reference/market-data/get-market-price

curl "https://clob.polymarket.com/price?token_id=YOUR_TOKEN_ID&side=buy"

Response: { "price": "0.65" }

GET /book — Orderbook

Ref: https://docs.polymarket.com/api-reference/market-data/get-order-book

curl "https://clob.polymarket.com/book?token_id=YOUR_TOKEN_ID"

Response:

{
  "market": "0x1b6f76e5...",
  "asset_id": "YOUR_TOKEN_ID",
  "timestamp": "1706000000000",
  "hash": "0xabc123...",
  "bids": [
    { "price": "0.64", "size": "500" },
    { "price": "0.63", "size": "1200" }
  ],
  "asks": [
    { "price": "0.66", "size": "300" },
    { "price": "0.67", "size": "800" }
  ],
  "min_order_size": "5",
  "tick_size": "0.001",
  "neg_risk": true,
  "last_trade_price": "0.65"
}

GET /midpoint — Midpoint Price

Ref: https://docs.polymarket.com/api-reference/data/get-midpoint-price

curl "https://clob.polymarket.com/midpoint?token_id=YOUR_TOKEN_ID"

Response: { "mid": "0.65" }

GET /spread — Bid-Ask Spread

Ref: https://docs.polymarket.com/api-reference/market-data/get-spread

curl "https://clob.polymarket.com/spread?token_id=YOUR_TOKEN_ID"

GET /last-trade-price — Last Trade

Ref: https://docs.polymarket.com/api-reference/market-data/get-last-trade-price

curl "https://clob.polymarket.com/last-trade-price?token_id=YOUR_TOKEN_ID"

Response: { "price": "0.65", "side": "BUY" }

GET /tick-size — Tick Size

Ref: https://docs.polymarket.com/api-reference/market-data/get-tick-size

curl "https://clob.polymarket.com/tick-size?token_id=YOUR_TOKEN_ID"

Response: { "minimum_tick_size": 0.001 }

Tick sizes: 0.1, 0.01, 0.001, or 0.0001. Changes dynamically when price > 0.96 or price < 0.04.

GET /fee-rate — Fee Rate

Ref: https://docs.polymarket.com/api-reference/market-data/get-fee-rate

curl "https://clob.polymarket.com/fee-rate?token_id=YOUR_TOKEN_ID"

GET /neg-risk — Negative Risk Check

curl "https://clob.polymarket.com/neg-risk?token_id=YOUR_TOKEN_ID"

Batch Endpoints (Multiple Tokens)

These let you query multiple tokens in a single request:

Ref: https://docs.polymarket.com/api-reference/market-data/get-order-books-request-body

# POST body example for /books
curl -X POST "https://clob.polymarket.com/books" \
  -H "Content-Type: application/json" \
  -d '[{"token_id": "TOKEN_1"}, {"token_id": "TOKEN_2"}]'

CLOB Market Endpoints

GET /markets — CLOB Market List

Source: https://docs.polymarket.com/developers/CLOB/clients/methods-public

Returns markets as seen by the CLOB (different schema than Gamma). Paginated.

curl "https://clob.polymarket.com/markets?next_cursor=xxx"

CLOB Market Object:

interface Market {
  accepting_order_timestamp: string | null;
  accepting_orders: boolean;
  active: boolean;
  archived: boolean;
  closed: boolean;
  condition_id: string;
  description: string;
  enable_order_book: boolean;
  end_date_iso: string;
  game_start_time: string;
  icon: string;
  image: string;
  is_50_50_outcome: boolean;
  maker_base_fee: number;
  market_slug: string;
  minimum_order_size: number;
  minimum_tick_size: number;
  neg_risk: boolean;
  neg_risk_market_id: string;
  neg_risk_request_id: string;
  notifications_enabled: boolean;
  question: string;
  question_id: string;
  rewards: { max_spread: number; min_size: number; rates: any | null };
  seconds_delay: number;
  tags: string[];
  taker_base_fee: number;
  tokens: MarketToken[];
}

interface MarketToken {
  outcome: string;
  price: number;
  token_id: string;
  winner: boolean;
}

GET /sampling-markets and /sampling-simplified-markets

Lighter-weight market list endpoints for high-frequency polling.

Historical Timeseries Data

GET /prices-history — Price History

Ref: https://docs.polymarket.com/api-reference/markets/get-prices-history

curl "https://clob.polymarket.com/prices-history?market=TOKEN_ID&interval=1d&fidelity=60"

Response:

{
  "history": [
    { "t": 1771413619, "p": 0.015 },
    { "t": 1771414220, "p": 0.016 }
  ]
}

Note: Use the token_id from Gamma API's clobTokenIds, not the condition_id.

WebSocket (Real-Time Updates)

Source: https://docs.polymarket.com/developers/CLOB/websocket/market-channel

URL: wss://ws-subscriptions-clob.polymarket.com/ws/market

Market Channel (Public — No Auth)

Subscribe to real-time orderbook and price updates:

{
  "assets_ids": ["TOKEN_ID_1", "TOKEN_ID_2"],
  "type": "market",
  "custom_feature_enabled": true
}

Set custom_feature_enabled: true to receive additional event types.

Event types received:

Each message includes an event_type field identifying the event.

User Channel (Authenticated)

Source: https://docs.polymarket.com/developers/CLOB/websocket/user-channel

Subscribe to order status updates. Requires WSS authentication headers.

Sports WebSocket

Dedicated sports data channel — see docs for details.

RTDS (Real-Time Data Stream)

Source: https://docs.polymarket.com/developers/RTDS/RTDS-overview

Low-latency data stream optimized for market makers. Includes:

• RTDS Crypto Prices: real-time crypto price feeds
• RTDS Comments: real-time comment streaming

Fees

Source: https://docs.polymarket.com/trading/fees

Overview

Most Polymarket markets are completely fee-free. Taker fees apply only to specific market types and are redistributed to market makers as rebates.

Fee Formula

fee = C × feeRate × (p × (1 - p))^exponent

Where:

• C = number of shares traded
• p = share price
• feeRate and exponent vary by market type

Fee Parameters by Market Type

Notes:

• Fees decrease symmetrically toward price extremes (0 or 1)
• Minimum fee charged: 0.0001 USDC (smaller amounts round to zero)
• No separate maker fees—only taker fees with daily rebate distributions

Check maker_base_fee and taker_base_fee on market objects or use GET /fee-rate for current rates.

Order Management (Authenticated — L2)

Source: https://docs.polymarket.com/developers/CLOB/clients/methods-l2

These endpoints require API credentials (key, secret, passphrase).

POST /order — Place Order

All orders are limit orders. For market-like execution, set price to cross the spread.

Order Types:

• GTC (Good Till Cancelled) — default, rests on book until filled or cancelled
• GTD (Good Till Date) — expires at a specified time
• FOK (Fill Or Kill) — must fill entirely immediately or cancel
• FAK (Fill And Kill) — fills what it can immediately, cancels the rest

Post Only: Orders can be set to reject if they would immediately match (prevents paying taker fees).

Using Python SDK:

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

api_creds = ApiCreds(
    api_key=os.getenv("API_KEY"),
    api_secret=os.getenv("SECRET"),
    api_passphrase=os.getenv("PASSPHRASE")
)

client = ClobClient(
    host="https://clob.polymarket.com",
    chain_id=137,
    key=os.getenv("PRIVATE_KEY"),
    creds=api_creds,
    signature_type=2,              # Deployed Safe proxy wallet
    funder=os.getenv("FUNDER_ADDRESS")
)

# Place a single order
resp = await client.create_and_post_order(
    {"tokenID": "YOUR_TOKEN_ID", "price": 0.50, "size": 100.0, "side": "BUY"}
)

POST /orders — Place Multiple Orders (Batch)

Source: https://docs.polymarket.com/changelog/changelog

Up to 15 orders per batch request.

DELETE /order — Cancel Order

DELETE /orders — Cancel Multiple Orders

DELETE /cancel-all — Cancel All Orders

DELETE /cancel-market-orders — Cancel All Orders for a Market

GET /order/{id} — Get Single Order

GET /orders — Get Active Orders

GET /data/trades — Get Your Trades (L2 Auth Required)

Source: https://docs.polymarket.com/developers/CLOB/trades/trades

NOTE: This CLOB endpoint requires L2 authentication. For public trade data, use the Data API instead.

SDKs

Source: https://docs.polymarket.com/api-reference/clients-sdks

GitHub repos:

• TS: https://github.com/Polymarket/clob-client
• Python: https://github.com/Polymarket/py-clob-client
• Rust: https://github.com/Polymarket/rs-clob-client

Rate Limits

Source: https://docs.polymarket.com/api-reference/rate-limits

Rate limits use Cloudflare throttling (delayed/queued, not rejected). Burst allowances on trading.

Market Data

Ledger

Trading (Burst + Sustained)

Authentication

Key Concepts for Arbitrage Analysis

Complementary Token Pricing

In a binary market, YES + NO should equal $1.00:

• If YES price + NO price < $1.00 → potential buy-both arbitrage
• If YES price + NO price > $1.00 → overpriced (rare)

Orderbook Depth Analysis

Use /book to assess:

• Spread — gap between best bid and best ask (wider = less efficient = more opportunity)
• Depth — total size at each price level (thin = slippage risk)
• Imbalance — ratio of bid vs ask depth (signals directional pressure)

Linking Gamma → CLOB

1. Get event from Gamma: GET /events/slug/your-event
2. Extract clobTokenIds from market objects (parse the JSON string)
3. Use token IDs with CLOB: GET /price?token_id=TOKEN_YES_ID&side=buy
4. Get orderbook: GET /book?token_id=TOKEN_YES_ID

Multi-Outcome Sum Analysis

For negRisk events with N markets:

total = sum(float(json.loads(m["outcomePrices"])[0]) for m in event["markets"])
if total < 0.98:  # account for spread
    print(f"Potential arbitrage: buy all YES for ${total:.2f}, guaranteed $1 payout")

Best Practices

1. Use WebSocket for real-time monitoring — REST polling adds latency
2. Always check accepting_orders before attempting trades
3. Check tick_size — orders must be priced at valid tick increments
4. Check minimum_order_size — orders below this will be rejected
5. Use seconds_delay — some markets delay order acceptance after creation
6. Use Post Only for limit orders you don't want to cross the spread
7. Use batch endpoints (/prices, /books, /midpoints) to reduce API calls
8. Check fee rates on specific markets — some sports/crypto markets have taker fees