pmwallets — Python SDK for PMWallets

Official Python client for PMWallets: the Polymarket smart-money leaderboard computed from the Polygon chain, and the real-time fills of the Polymarket wallets you follow — delivered in order, exactly once, with every gap replayed.

中文说明 · Node.js SDK: pmwallets-node · Ready-to-run copy-trading bot built on it: polymarket-copy-trading-bot-python

Install

pip install pmwallets     # Python ≥ 3.10

Create an API key on pmwallets.com/keys.

Usage

import asyncio
from pmwallets import AsyncClient, Client, FillStream, FileStateStore

# synchronous REST
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"])   # billed per entity per hour

# every fill of every entity you follow
async def main():
    async with AsyncClient(api_key="pmw_...") as pmw:
        stream = FillStream(
            client=pmw,
            store=FileStateStore("stream.json"),     # a restart resumes exactly where it stopped
            on_fill=lambda fill, meta: print(meta.source, fill["side"], fill["price"], fill["tokenId"]),
            on_event=lambda e: e["type"] == "fatal" and print(e["error"]),   # e.g. another bot already holds the stream
            # takeover=True,   # replace whichever API client holds this account's stream (it stops with "replaced")
        )
        await stream.run()

asyncio.run(main())

What is in it

One stream per account:

• An API-key connection takes priority over the pmwallets.com feed page (the page never takes the stream from it).
• Between two API connections the first one keeps the stream. A second one — another key of the same account, or the same bot started twice — is refused: blocked, then fatal, and the stream stops. Pass takeover=True to replace the holder instead; the holder gets replaced, then fatal, and stops (it does not fight back).
• A FillStream identifies itself with a random client_id, so its own reconnects after a network drop replace its own dead connection without needing takeover.
• When the server restarts it closes the socket with 1012; the stream reconnects at once (event restarting) and replays anything it missed.

HTTPS_PROXY is honoured.

PMWallets' servers are in the United Kingdom. A consumer that also trades on Polymarket should run from Ireland (AWS eu-west-1): Polymarket does not accept API orders from the UK, the US and several EU countries.

Trade-history exports

A purchase is access to files: one zstd-compressed CSV per wallet per UTC day, downloadable at once and again later.

order = client.create_export(["0x…"], "2026-09-01", "2026-09-30")
for f in client.export_files(order["id"])["files"]:
    data = client.download_export_file(f["wallet"], f["day"])  # .csv.zst
    # pandas: pd.read_csv(io.BytesIO(data), compression="zstd")

export_file_url(wallet, day) returns the short-lived link instead; the API key is never sent to the storage host.

Resources

• Polymarket smart-money leaderboard — profitable Polymarket traders scored from the Polygon chain, with win-rate confidence intervals
• Polymarket copy trading guide — which wallets are worth following and how to get their fills in time
• How to learn from Polymarket smart money — reading a trader's record: confidence intervals, maker vs taker, market specialism
• PMWallets API documentation — WebSocket and webhook fill push, fills replay, trade-history exports
• Measured fill-push latency — block-to-push p50 / p95, published live
• Ways to follow Polymarket wallets, compared — official leaderboard, free trackers, SQL dashboards
• FAQ · 中文站

License

MIT