Polyoxide

Python SDK for Polymarket APIs, powered by Rust via PyO3 and maturin.

Every client comes in async and sync variants. Async methods return Python awaitables; sync methods block via an internal Tokio runtime and release the GIL while waiting.

Installation

pip install polyoxide

Wheels are published for Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64).

Quick Start

Async (Gamma -- market data)

import asyncio
from polyoxide import Gamma

async def main():
    gamma = Gamma()
    markets = await gamma.markets().list(limit=5, open=True)
    for m in markets:
        print(f"{m.question}  --  {m.slug}")

asyncio.run(main())

Sync (Gamma)

from polyoxide import GammaSync

gamma = GammaSync()
markets = gamma.markets().list(limit=5, open=True)
for m in markets:
    print(f"{m.question}  --  {m.slug}")

CLOB (order book data)

from polyoxide import ClobClientSync

clob = ClobClientSync()
book = clob.markets().order_book("TOKEN_ID")
print(book.bids, book.asks)

spread = clob.markets().spread("TOKEN_ID")
print(spread)

Data API (user positions and leaderboard)

import asyncio
from polyoxide import DataApi

async def main():
    data = DataApi()

    # Leaderboard
    leaders = await data.leaderboard().get(limit=10, time_period="WEEK")
    for t in leaders:
        print(t.user_name, t.pnl)

    # User positions
    positions = await data.user("0xADDRESS").list_positions(limit=5)
    for p in positions:
        print(p.title, p.size)

asyncio.run(main())

Data API v2 (cursor pages)

DataApi().v2() and DataApiSync().v2() expose the /v2 routes: snake_case fields, cursor-only paging, and errors with a stable code. Their result classes live in polyoxide.v2, since several share a name with a v1 class.

from polyoxide import DataApiSync, v2

data = DataApiSync().v2()

# One page, and the cursor for the next one
page = data.trades(limit=50)
print(len(page), page.pagination.next_cursor)

# Every page, re-sending the same filters each time
for page in data.iter_activity("0xADDRESS", types=["TRADE"], limit=500):
    for row in page.data:
        print(row.activity_type, row.usdc_size)

# None, not an error, for a wallet the API does not know
stats = data.user_stats("0xADDRESS")

Async walks use async for page in DataApi().v2().iter_trades(...). Enum arguments take the exact wire spelling (time_period="week", sort_direction="DESC"), and a value the route does not accept raises ValueError before any request is sent.

Client API Reference

Gamma / GammaSync

Constructed with optional base_url, timeout_ms, and pool_size keyword arguments.

ClobClient / ClobClientSync

No arguments required (uses public/unauthenticated endpoints).

DataApi / DataApiSync

Constructed with optional base_url, timeout_ms, and pool_size keyword arguments.

Result Objects

All response objects expose named properties matching the upstream JSON fields, plus:

• .to_dict() -- convert to a plain Python dict
• str(obj) -- JSON string representation
• repr(obj) -- type-annotated representation

Error Handling

All exceptions inherit from PolyoxideError:

from polyoxide import PolyoxideError, ApiError, RateLimitError

try:
    markets = gamma.markets().list()
except RateLimitError:
    print("slow down")
except ApiError as e:
    print(f"API error: {e}")
except PolyoxideError as e:
    print(f"something else: {e}")

A Data API v2 error maps by its code: invalid_request to ValidationError, rate_limited to RateLimitError, request_timeout to TimeoutError, and any other code to ApiError. Every exception also carries status, code, retryable, trace_id, parameter and retry_after, which are None unless the error came from a v2 route.

Async Support

Async clients (Gamma, ClobClient, DataApi) use pyo3-async-runtimes to bridge Rust futures into Python awaitables. They work with asyncio.run(), await, and any asyncio-compatible event loop.

Sync clients (GammaSync, ClobClientSync, DataApiSync) execute on a shared background Tokio runtime and release the GIL while blocking, so they are safe to use from threaded Python code.

Type Stubs

.pyi stub files are included at python/polyoxide/__init__.pyi and python/polyoxide/v2.pyi for editor autocomplete and type checking.

Building from Source

Requires Rust and Python 3.9+.

pip install maturin
maturin develop --release

License

Licensed under either of MIT or Apache-2.0 at your option.