Quickstart

This walkthrough gets you from an API key to a joined price and metrics series for one market.

Prerequisites

A PolymarketData API key from the dashboard
Python 3.10+ (for the examples below)

Python SDK
REST

Install the SDK

pip install polymarketdata-sdk

Optional dataframe helpers:

pip install "polymarketdata-sdk[dataframe]"

Set your API key

Export the key, or pass it directly to the client.

export POLYMARKETDATA_API_KEY="pk_live_your_key_here"

Check health and plan limits

from polymarketdata import PolymarketDataClient

with PolymarketDataClient() as client:
    health = client.utility.health()
    usage = client.utility.usage()
    print(health.status)
    print(usage.plan)
    print(usage.limits.requests_remaining)

Discover a market and pull prices

from polymarketdata import PolymarketDataClient, Resolution

with PolymarketDataClient() as client:
    markets = client.discovery.list_markets(search="bitcoin", limit=5)
    market = markets.data[0]
    market_id = market.slug or market.id

    prices = client.history.get_market_prices(
        market_id,
        start_ts="2026-01-01T00:00:00Z",
        end_ts="2026-01-08T00:00:00Z",
        resolution=Resolution.ONE_MIN,
    )
    print(market_id, len(prices.data))

Confirm the API is up

curl "https://api.polymarketdata.co/v1/health" \
  -H "X-API-Key: pk_live_your_key_here"

Find a market

import os
import requests

API_KEY = os.environ["POLYMARKETDATA_API_KEY"]
BASE = "https://api.polymarketdata.co/v1"
headers = {"X-API-Key": API_KEY}

markets = requests.get(
    f"{BASE}/markets",
    headers=headers,
    params={"search": "bitcoin", "limit": 5},
    timeout=30,
)
markets.raise_for_status()
slug = markets.json()["data"][0]["slug"]
print(slug)

Pull one week of minute prices

prices = requests.get(
    f"{BASE}/markets/{slug}/prices",
    headers=headers,
    params={
        "start_ts": "2026-01-01T00:00:00Z",
        "end_ts": "2026-01-08T00:00:00Z",
        "resolution": "1m",
    },
    timeout=30,
)
prices.raise_for_status()
rows = prices.json()["data"]
print(len(rows))

Next steps

Authentication

Header format, key storage, and 401 responses.

Data model

Series, events, markets, and tokens.

Pagination

Cursor pages for discovery and history.

Python SDK

Namespaces, iterators, retries, and dataframes.

Print row counts and the timestamp range before you model anything. A thin series usually means the market was inactive in that window — pick another market rather than debugging your join.

Getting started

Guides

SDKs

Prerequisites

Next steps

Authentication

Data model

Pagination

Python SDK

​Prerequisites

​Next steps

Authentication

Data model

Pagination

Python SDK

Prerequisites

Next steps