polymarket-skills/polymarket-scanner/references/api-guide.md

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

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