Polymarket API Guide

Two APIs

Polymarket exposes two separate APIs for different purposes:

1. Gamma API (Market Metadata)

Base URL: https://gamma-api.polymarket.com
Auth: None required
Purpose: Market discovery, metadata, search, and filtering

Key Endpoints

GET /markets — List and search markets

Parameter	Type	Description
`limit`	int	Max results (up to 100)
`offset`	int	Pagination offset
`active`	bool	Filter active markets
`closed`	bool	Filter closed markets
`order`	string	Sort field: `volume24hr`, `liquidity`, `endDate`, `startDate`, `createdAt`
`ascending`	bool	Sort direction
`tag_slug`	string	Filter by category tag
`slug`	string	Exact match on market slug
`id`	string	Exact match on market ID

Example request:

GET https://gamma-api.polymarket.com/markets?limit=5&active=true&closed=false&order=volume24hr&ascending=false

Example response (array of objects):

[
  {
    "id": "572481",
    "question": "Will Trump nominate Scott Bessent as the next Fed chair?",
    "slug": "will-trump-nominate-scott-bessent-as-the-next-fed-chair",
    "outcomes": "[\"Yes\", \"No\"]",
    "outcomePrices": "[\"0.0015\", \"0.9985\"]",
    "clobTokenIds": "[\"10749...\", \"88386...\"]",
    "volume24hr": 11394218.4,
    "volumeNum": 35997330.32,
    "liquidityNum": 1270782.68,
    "endDate": "2026-12-31T00:00:00Z",
    "active": true,
    "closed": false,
    "acceptingOrders": true,
    "negRisk": true,
    "description": "...",
    "conditionId": "0x...",
    "orderPriceMinTickSize": 0.001,
    "orderMinSize": 5
  }
]

Note: outcomes, outcomePrices, and clobTokenIds are JSON-encoded strings that need to be parsed.

2. CLOB API (Prices and Order Books)

Base URL: https://clob.polymarket.com
Auth: None for read-only; L1/L2 wallet auth for trading
Purpose: Real-time prices, order books, trade execution

Python Client

from py_clob_client.client import ClobClient
from py_clob_client.clob_types import BookParams

client = ClobClient("https://clob.polymarket.com")

Read-Only Methods (No Auth)

Method	Arguments	Returns
`get_midpoint(token_id)`	str	`{"mid": "0.55"}`
`get_spread(token_id)`	str	`{"spread": "0.02"}`
`get_price(token_id, side)`	str, "BUY"/"SELL"	`{"price": "0.54"}`
`get_last_trade_price(token_id)`	str	`{"price": "0.55", "side": "BUY"}`
`get_order_book(token_id)`	str	OrderBookSummary object

Batch Methods

from py_clob_client.clob_types import BookParams

params = [BookParams(token_id=id1), BookParams(token_id=id2)]
client.get_midpoints(params)     # {id1: "0.55", id2: "0.45"}
client.get_spreads(params)       # {id1: "0.02", id2: "0.01"}
client.get_last_trades_prices(params)  # {id1: {"price": ..., "side": ...}, ...}

OrderBookSummary Object

ob = client.get_order_book(token_id)
ob.market      # condition ID
ob.asset_id    # token ID
ob.bids        # list of OrderSummary(price="0.54", size="100")
ob.asks        # list of OrderSummary(price="0.56", size="200")
ob.timestamp   # server timestamp

Rate Limits

Gamma API: No published rate limit, but excessive requests may be throttled. Use reasonable limits (1-2 requests/second).
CLOB API: Read-only endpoints are generous. Trading endpoints have stricter limits tied to API key tier.

Error Handling

HTTP Code	Meaning	Action
200	Success	Parse response
400	Bad request	Check parameters
404	Not found	Token ID or slug may be invalid
429	Rate limited	Back off and retry after delay
500	Server error	Retry with exponential backoff

Token IDs

Token IDs are long numeric strings (70+ digits) that uniquely identify each outcome in a market. A binary YES/NO market has 2 token IDs. Multi-outcome markets have one per outcome.

The token ID is the primary key for interacting with the CLOB API. Get them from the Gamma API's clobTokenIds field or the CLOB API's get_markets() method.

Connecting the APIs

Gamma API for discovery: search/filter markets, get metadata and token IDs
CLOB API for pricing: use token IDs from Gamma to query live prices, order books, and spreads

/polymarket-scanner

referencesapi-guide.md