polymarket-client 0.1.0b1

Official Python client for Polymarket

Polymarket Python SDK

Official Python SDK for Polymarket.

The SDK gives Python developers one coherent, workflow-oriented interface for building on Polymarket, starting with public data access and expanding toward authenticated account, trading, builder attribution, and relayer-backed workflows.

Installation

uv add polymarket-client

or:

pip install polymarket-client

Usage

Synchronous client:

from polymarket import Market, PublicClient

with PublicClient() as client:
    market: Market = client.get_market(url="https://polymarket.com/event/example-market")

Asynchronous client:

import asyncio

from polymarket import AsyncPublicClient, Market


async def main() -> None:
    async with AsyncPublicClient() as client:
        market: Market = await client.get_market(
            url="https://polymarket.com/event/example-market"
        )


asyncio.run(main())

API Design

See SDK Direction for public API design principles and developer-experience decisions.

Development

Install dependencies:

make sync

Run checks:

make check

Build package artifacts:

make build

The Makefile is a thin convenience wrapper around uv. Running the underlying commands directly is also fine.

Testing

Unit tests run by default:

make test

Run unit tests in watch mode:

make test-watch

This runs the tests once immediately, then reruns them when Python files change.

Integration tests are opt-in:

make test-integration

Integration tests can load local secrets from a gitignored .env copied from .env.example:

cp .env.example .env

See .env.example for the supported local and CI secret names.

Tests that require credentials should use the require_env fixture so they skip when secrets are unavailable:

import pytest


@pytest.mark.integration
def test_authenticated_flow(require_env):
    private_key = require_env("POLYMARKET_PRIVATE_KEY")
    builder_api_key = require_env("POLYMARKET_BUILDER_API_KEY")

    assert private_key
    assert builder_api_key

The SDK does not load .env files at runtime. The integration test fixture loads .env only for tests that request credentials, and existing environment variables take precedence over local .env values.

Tests that place orders, spend funds, or mutate live state must also use @pytest.mark.metered. Metered tests are skipped unless POLYMARKET_RUN_METERED_TESTS=1 is set:

import pytest


@pytest.mark.integration
@pytest.mark.metered
def test_order_lifecycle(require_env):
    private_key = require_env("POLYMARKET_PRIVATE_KEY")

    assert private_key

POLYMARKET_RUN_METERED_TESTS=1 make test-integration