Python SDK

The polymarket-client package is the official Python SDK for building Polymarket integrations.

GitHub

View the Python SDK source.

PyPI Package

Install polymarket-client from PyPI.

See the SDK Changelog for recent Python releases.

Quickstart

Install the SDK

Install the SDK with your preferred package manager.

uv add polymarket-client

pip install polymarket-client

poetry add polymarket-client

Create a Public Client

Create an AsyncPublicClient to access publicly available Polymarket data.

from polymarket import AsyncPublicClient


async with AsyncPublicClient() as client:
    ...

Fetch Active Markets

Fetch a page of active markets to discover trading opportunities.

import asyncio

from polymarket import AsyncPublicClient


async def main() -> None:
    async with AsyncPublicClient() as client:
        pages = client.list_markets(closed=False)
        first_page = await pages.first_page()

        for market in first_page.items:
            # market: Market
            ...


asyncio.run(main())

Async and Sync Interfaces

Public clients access public data. Secure clients add trading and account access. Both client types are available in async and sync forms.

Interface	Public data	Trading and account data
Async	`AsyncPublicClient`	`AsyncSecureClient`
Sync	`PublicClient`	`SecureClient`

Async clients fit services, bots, and applications that already run an event loop. Sync clients are convenient for scripts and notebooks.

from polymarket import AsyncPublicClient


async with AsyncPublicClient() as client:
    pages = client.list_markets(closed=False)
    first_page = await pages.first_page()

from polymarket import PublicClient


with PublicClient() as client:
    pages = client.list_markets(closed=False)
    first_page = pages.first_page()

Some features, including realtime subscriptions, are async-only because they rely on long-lived streams.

Pagination

SDK list methods use a consistent paginator interface. Iterate over the paginator to retrieve every page, or fetch one page at a time when you need to control pacing.

pages = client.list_markets(closed=False, page_size=10)

async for page in pages:
    for market in page.items:
        # market: Market
        ...

pages = client.list_markets(closed=False, page_size=10)

for page in pages:
    for market in page.items:
        # market: Market
        ...

When page boundaries do not matter, iterate over every item directly.

async for market in pages.iter_items():
    # market: Market
    ...

for market in pages.iter_items():
    # market: Market
    ...

page.next_cursor is an opaque SDK cursor. Store it as-is if you want to resume a scan later, and omit it when starting from the first page.

pages = client.list_markets(closed=False, page_size=10)
page = await pages.first_page()

if page.next_cursor:
    second_page = await pages.from_cursor(page.next_cursor).first_page()
    # second_page.items: tuple[Market, ...]

pages = client.list_markets(closed=False, page_size=10)
page = pages.first_page()

if page.next_cursor:
    second_page = pages.from_cursor(page.next_cursor).first_page()
    # second_page.items: tuple[Market, ...]

Types

SDK methods return typed models, and their public types are exported from polymarket.

from polymarket import Event, Market, OrderBook, PriceHistoryPoint

The SDK also uses distinct types for domain identifiers and EVM addresses. Precision-sensitive values use decimal.Decimal, while dates and timestamps use Python’s datetime types.

from polymarket import CtfConditionId, EvmAddress, MarketId, TokenId

Error Handling

All SDK exceptions inherit from PolymarketError. Catch specific exceptions when your application can respond to them, then catch the base exception as a fallback.

from polymarket import PolymarketError, RateLimitError, UserInputError

pages = client.list_markets(closed=False)

try:
    page = await pages.first_page()
    # page.items: tuple[Market, ...]
except RateLimitError:
    # Retry later.
    ...
except UserInputError:
    # Fix the request parameters.
    ...
except PolymarketError:
    # Handle any other SDK error.
    raise

Secure Client

Create an AsyncSecureClient or SecureClient when your integration needs to trade or access account data. The Python SDK creates the signer from a local private key.

import os

from polymarket import AsyncSecureClient


async with await AsyncSecureClient.create(
    private_key=os.environ["POLYMARKET_PRIVATE_KEY"],
) as client:
    ...

import os

from polymarket import SecureClient


with SecureClient.create(
    private_key=os.environ["POLYMARKET_PRIVATE_KEY"],
) as client:
    ...

Continue to Wallets and Authentication to configure the account wallet and gasless transactions.

Realtime Subscriptions

The Python SDK can combine updates from multiple realtime feeds into a single stream of events.

Realtime subscriptions are available only through AsyncPublicClient and AsyncSecureClient. PublicClient and SecureClient do not implement subscribe().

Call subscribe() with one or more subscription specs. Both AsyncPublicClient and AsyncSecureClient support public streams, while AsyncSecureClient also provides private streams for the connected account.

from polymarket.streams import MarketSpec, SportsSpec

token_id = "<token_id>"

async with await client.subscribe(
    [MarketSpec(token_ids=[token_id]), SportsSpec()],
) as stream:
    async for event in stream:
        # event:
        #   MarketBookEvent
        #   | MarketPriceChangeEvent
        #   | MarketLastTradePriceEvent
        #   | MarketTickSizeChangeEvent
        #   | MarketBestBidAskEvent
        #   | NewMarketEvent
        #   | MarketResolvedEvent
        #   | SportsEvent

        if should_close:
            break

from polymarket.streams import MarketSpec, UserSpec

token_id = "<token_id>"

async with await client.subscribe(
    [MarketSpec(token_ids=[token_id]), UserSpec()],
) as stream:
    async for event in stream:
        # event:
        #   MarketBookEvent
        #   | MarketPriceChangeEvent
        #   | MarketLastTradePriceEvent
        #   | MarketTickSizeChangeEvent
        #   | MarketBestBidAskEvent
        #   | NewMarketEvent
        #   | MarketResolvedEvent
        #   | UserEvent

        if should_close:
            break

Narrow event.topic before handling a specific event shape. The examples show a few streams; see Real-Time Data, Real-Time Order Updates, and Perps Realtime Updates for feed-specific options.

DataFrames and Jupyter

Convert pages and paginators directly to a pandas DataFrame, Polars DataFrame, or Apache Arrow Table. Install the pandas, polars, or arrow package extra for the format you use; the quant extra installs all three.

pages = client.list_markets(closed=False)
df = await pages.to_pandas(limit=100)

pages = client.list_markets(closed=False)
df = await pages.to_polars(limit=100)

pages = client.list_markets(closed=False)
table = await pages.to_arrow(limit=100)

Paginator conversions require an explicit limit. Pass limit=None to retrieve every item. Common SDK objects also render as compact cards in Jupyter notebooks. Return an object as the last expression in a cell to display it.

pages = client.list_markets(closed=False)
page = await pages.first_page()
page.items[0]

Next Steps

Read Market Data

Discover markets and work with prices, order books, and historical data.

Subscribe to Real-Time Updates

Stream market and account updates as they happen.

Place Your First Order

Set up an account and complete your first authenticated trade.

Getting Started

Core Concepts

Market Data

Trading

Programs

Resources

GitHub

PyPI Package

Quickstart

Async and Sync Interfaces

Types

Error Handling

Secure Client

Realtime Subscriptions

DataFrames and Jupyter

Next Steps

Read Market Data

Subscribe to Real-Time Updates

Place Your First Order

GitHub

PyPI Package

​Quickstart

​Async and Sync Interfaces

​Pagination

​Types

​Error Handling

​Secure Client

​Realtime Subscriptions

​DataFrames and Jupyter

​Next Steps

Read Market Data

Subscribe to Real-Time Updates

Place Your First Order

Quickstart

Async and Sync Interfaces

Pagination

Types

Error Handling

Secure Client

Realtime Subscriptions

DataFrames and Jupyter

Next Steps