Polymarket¶

Summary¶

Polymarket is a decentralized prediction market built on the Polygon blockchain where users trade shares in the outcomes of events. Each market has a binary outcome (e.g., "Team A wins the World Cup: Yes/No") priced between $0 and $1, reflecting the crowd's collective probability estimate. Polymarket has grown to become the largest prediction market by volume, offering markets across sports, politics, crypto, and world events.

The platform provides a public REST API for reading market data — current prices, volumes, liquidity, and historical price history. There is no official cost to access public market data via the API. Trading requires cryptocurrency (USDC on Polygon), but researchers and modelers can extract probability information without trading.

Polymarket prices are often cited as a benchmark for aggregate crowd wisdom and are useful for comparing against model predictions — similar to using betting exchange odds.

Key Concepts¶

• Market: A question about a future event with a binary or categorical outcome
• Share price: Probability of outcome (0.60 = 60% implied probability, $0.60 price)
• Volume: Total amount traded on a market — indicates market activity and confidence
• CLOB: Central limit order book — Polymarket uses a hybrid CLOB model for price discovery
• Settlement: Markets resolve based on documented rules; prices pay out $1.00 if correct, $0.00 if wrong

API Overview¶

Polymarket provides a public REST API at https://gamma-api.polymarket.com. Key endpoints:

No API key is required for public read access in most cases.

Example: Fetching Sports Market Prices¶

import requests
import json

# Get active sports markets
url = "https://gamma-api.polymarket.com/markets"
params = {
    "category": "sports",
    "closed": "false",
    "limit": 50,
}
response = requests.get(url, params=params)
markets = response.json()

for m in markets:
    question = m["question"]
    outcome_prices = json.loads(m["outcomePrices"])
    print(f"{question}: {outcome_prices}")
    print(f"  Volume: ${float(m['volume']):,.0f}")
    print(f"  Liquidity: ${float(m['liquidity']):,.0f}")

Using Polymarket Prices in Models¶

def market_prob(market_prices, outcome_index):
    """Convert Polymarket outcome prices to probabilities."""
    # Prices are stored as JSON array, e.g. ['0.35', '0.65']
    prices = json.loads(market_prices)
    return float(prices[outcome_index])

def market_clv(model_prob, market_price):
    """
    Compare model probability to Polymarket implied probability.
    market_price is the Polymarket share price (0 to 1).
    """
    return model_prob - float(market_price)

# Example: World Cup winner model says Brazil 25%, Polymarket says 20%
model_prob = 0.25
market_price = 0.20
clv = market_clv(model_prob, market_price)
print(f"Model edge vs Polymarket: {clv:.1%}")  # +5% edge

Notes¶

• Polymarket prices reflect real-money trading — more credible than survey polls or sentiment indices
• Market liquidity varies widely; high-volume markets (World Cup winner, election outcomes) are very efficient; low-volume markets can be mispriced
• Prices include the platform fee (spread built into the AMM); true probabilities are slightly different from displayed prices — apply a small correction if precision matters
• Markets resolve with real-world truth; disputes are resolved by Polymarket's oracle system — check resolution rules before trusting data for a specific market
• Good for cross-validation: if your model strongly disagrees with Polymarket on a high-liquidity market, either your model or the market may be wrong
• No historical data endpoint directly — price history can be scraped or accessed via third-party data aggregators (Bitquery, Apify)