Polymarket data in Python: markets, a wallet's trades, and live fills

Which API answers what

Polymarket's Gamma API describes markets and events — slugs, questions, condition IDs, token IDs, flags. Its Data API returns a wallet's trades, activity and positions. The CLOB API is the order book, and is what you use to place orders; Polymarket publishes an official Python client for it, py-clob-client. None of the three ranks traders or pushes another wallet's fills as they happen, which is what the PMWallets API adds.

Markets and a wallet's history, no key needed

Both Gamma and the Data API are public. Query the Data API with the profile address — the smart-contract wallet, not the signer. Two details save time: outcomes and clobTokenIds come back as JSON-encoded strings, and each trade's asset field is the token ID.

import json, requests

# markets and events — Gamma API
m = requests.get("https://gamma-api.polymarket.com/markets", params={"slug": "<market-slug>"}).json()[0]
token_ids = json.loads(m["clobTokenIds"])           # a JSON string; same order as json.loads(m["outcomes"])

# a wallet's trades, activity and positions — Data API (use the profile / proxy wallet address)
W = "0x..."
trades    = requests.get("https://data-api.polymarket.com/trades",    params={"user": W, "limit": 100}).json()
activity  = requests.get("https://data-api.polymarket.com/activity",  params={"user": W, "limit": 100}).json()
positions = requests.get("https://data-api.polymarket.com/positions", params={"user": W}).json()
for t in trades[:5]:
    print(t["timestamp"], t["side"], t["outcome"], t["price"], t["size"], t["title"])

The limits of polling

The Data API is pull-only: to watch a wallet you ask again and again, one request per address per poll. It answers for one address at a time, so a trader using several wallets needs each of them, and its trade endpoint returns at most 10,000 historical trades per wallet. For a handful of wallets and minutes of delay that is fine; for a bot that must see every fill of the traders it follows, it is not.

Ranked traders and live fills: the pmwallets SDK

The open-source pmwallets SDK (pip install pmwallets, MIT) reads the PMWallets leaderboard — traders clustered across their wallets, win rates with confidence intervals — and streams the fills of the entities you subscribe to over WebSocket, typically within a second of the block. It detects gaps by session and sequence number, replays them, and de-duplicates by event ID, so a restart resumes exactly where it stopped.

# pip install pmwallets
import asyncio
from pmwallets import AsyncClient, Client, FillStream, FileStateStore

with Client(api_key="pmw_...") as pmw:
    board = pmw.leaderboard(minWinLo=0.55, minEligible=30, style="taker", status="active", limit=50)
    pmw.subscribe(board["rows"][0]["entityId"], channels=["ws"])

async def main():
    async with AsyncClient(api_key="pmw_...") as pmw:
        stream = FillStream(client=pmw, store=FileStateStore("stream.json"),
                            on_fill=lambda fill, meta: print(fill["side"], fill["price"], fill["tokenId"]))
        await stream.run()

asyncio.run(main())

Is there an official Polymarket Python library?

Yes, for trading: py-clob-client, Polymarket's client for the CLOB order book. Market data and wallet history come from the public Gamma and Data APIs, which plain HTTP requests can query.

How do I get a Polymarket wallet's trades in Python?

Call https://data-api.polymarket.com/trades with user set to the wallet's profile (proxy) address. For trades as they happen, subscribe to the trader with the pmwallets SDK and receive each fill over WebSocket.

Do I need an API key for Polymarket data?

Not for Gamma or the Data API, which are public. Placing orders needs CLOB credentials derived from your wallet. The PMWallets SDK needs a PMWallets API key.