POLYMARKET API DOCUMENTATION

Complete guide to integrating with Polymarket's Gamma API for real-time prediction market data. This documentation covers all endpoints, WebSocket connections, and provides testing examples.

Base URL: https://gamma-api.polymarket.com

Rate Limits: No authentication required for public endpoints

GAMMA API OVERVIEW

The Gamma API provides access to Polymarket's prediction markets, events, and real-time market data. All responses are returned in JSON format with comprehensive market information.

Key Features

Real-time market prices and probabilities
Market volume and liquidity data
Event metadata and descriptions
Historical market data
WebSocket support for live updates

MARKETS ENDPOINT

Retrieve all active prediction markets with full details including outcomes, volume, and probabilities.

ENDPOINT GET

GET /markets

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	100	Maximum number of markets to return
`offset`	integer	0	Number of markets to skip
`active`	boolean	true	Filter for active/inactive markets
`closed`	boolean	false	Include closed markets

Response Example

[
  {
    "id": "0x123...",
    "question": "Will Bitcoin reach $100,000 by December 31, 2025?",
    "description": "This market will resolve to Yes if...",
    "outcomes": [
      {
        "name": "Yes",
        "price": 0.65,
        "index": 0
      },
      {
        "name": "No",
        "price": 0.35,
        "index": 1
      }
    ],
    "volume": "1234567.89",
    "liquidity": "500000.00",
    "active": true,
    "closed": false,
    "end_date_iso": "2025-12-31T23:59:59Z",
    "category": "Crypto"
  }
]

SIMPLIFIED MARKETS

Get a streamlined version of markets data with only essential fields for faster response times.

ENDPOINT GET

GET /markets?_format=simplified

Response Structure

[
  {
    "question": "Will Ethereum reach $5,000 in 2025?",
    "yes_price": 0.52,
    "no_price": 0.48,
    "volume_24h": "45000.00",
    "category": "Crypto"
  }
]

Pro Tip: Use simplified format when you only need basic market data to reduce bandwidth and improve performance.

EVENTS ENDPOINT

Events group related markets together. Use this endpoint to discover trending events and their associated markets.

ENDPOINT GET

GET /events

Response Example

[
  {
    "id": "event_123",
    "title": "2024 Presidential Election",
    "description": "Markets related to the 2024 election",
    "markets": ["0x123...", "0x456..."],
    "category": "Politics",
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-11-05T23:59:59Z"
  }
]

WEBSOCKET API

Subscribe to real-time market updates using WebSocket connections for live price changes.

CONNECTION

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

Subscribe to Market Updates

JAVASCRIPT

const ws = new WebSocket('wss://ws-subscriptions-clob.polymarket.com/ws/market');

ws.onopen = () => {
    ws.send(JSON.stringify({
        type: 'subscribe',
        market_id: '0x123...'
    }));
};

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Market update:', data);
};

Note: WebSocket connections may timeout after periods of inactivity. Implement reconnection logic in production applications.

CODE EXAMPLES

Python Example

PYTHON

import requests

# Fetch active markets
response = requests.get(
    'https://gamma-api.polymarket.com/markets',
    params={
        'limit': 10,
        'active': True
    }
)

markets = response.json()
for market in markets:
    print(f"Question: {market['question']}")
    print(f"Volume: ${market['volume']}")
    print(f"Yes Price: {market['outcomes'][0]['price']}")
    print("---")

JavaScript/Node.js Example

JAVASCRIPT

async function fetchMarkets() {
    const response = await fetch(
        'https://gamma-api.polymarket.com/markets?limit=10'
    );
    const markets = await response.json();
    
    markets.forEach(market => {
        console.log(`Question: ${market.question}`);
        console.log(`Volume: $${market.volume}`);
        console.log(`Yes Price: ${market.outcomes[0].price}`);
        console.log('---');
    });
}

fetchMarkets();

cURL Example

BASH

curl -X GET "https://gamma-api.polymarket.com/markets?limit=5&active=true" \
     -H "Accept: application/json" | jq '.'

API TESTING

Test the Polymarket API directly from your browser or terminal using these examples.

Test in Browser Console

BROWSER CONSOLE

// Test basic markets endpoint
fetch('https://gamma-api.polymarket.com/markets?limit=5')
    .then(res => res.json())
    .then(data => console.table(data))
    .catch(err => console.error('Error:', err));

// Test specific market by ID
fetch('https://gamma-api.polymarket.com/markets/0x123...')
    .then(res => res.json())
    .then(data => console.log(data))
    .catch(err => console.error('Error:', err));

Integration with SEREIN

Our backend automatically fetches and caches Polymarket data every 5 seconds:

BACKEND/POLYMARKET.PY

async def fetch_polymarket_data():
    """Fetch trending markets from Polymarket Gamma API"""
    url = "https://gamma-api.polymarket.com/markets"
    params = {
        "limit": 20,
        "active": True,
        "closed": False
    }
    
    async with aiohttp.ClientSession() as session:
        async with session.get(url, params=params) as response:
            markets = await response.json()
            return process_markets(markets)

Local Testing: Access live market data from SEREIN at http://localhost:8000/market