polymarket-client

What it is

Polymarket's own Python SDK, and the one package Polymarket's documentation names: polymarket-client on PyPI, built in the Polymarket/py-sdk repository, published by Polymarket Engineering, MIT by the LICENSE file in the repository and by the PyPI classifier alike. It needs Python 3.11 or newer. Version 0.10.0 was published on 2026-09-10, the thirty-fourth release since 2026-05-21; the first twenty-one of those were betas of 0.1.0, and 0.1.0 itself - the first release carrying no beta tag - landed on 2026-07-22.

It ships four clients. PublicClient and AsyncPublicClient read public data and need no credentials at all; SecureClient and AsyncSecureClient take a local private key and can trade. The split is the useful one: a notebook pulling prices never handles key material, and the sync forms exist precisely so a script does not have to run an event loop.

What it covers, from the method inventory in src/polymarket/clients/:

• Discovery. list_events, list_markets, list_series, list_tags, search and the sports metadata calls, against the Gamma API. This is the half the predecessor did not have.
• CLOB reads. get_midpoint, get_price, get_spread, get_order_book and their bulk forms, get_last_trade_price, list_price_history and estimate_market_price.
• Order signing and trading. EIP-712 typed-data signing, create_limit_order and create_market_order, place_limit_order and place_market_order, post_order, post_orders, cancel_order, cancel_orders, cancel_all and cancel_market_orders.
• Credential derivation, done for you. SecureClient.create() derives the Level 2 API credentials during client creation unless you pass your own, and derives the wallet address from the signer key. It classifies the account as one of four wallet types - a plain EOA, a Polymarket proxy, a Gnosis Safe or a Deposit Wallet - and picks the signature type from that.
• On-chain plumbing. approve_erc20, approve_erc1155_for_all, get_trading_approvals_state, a gasless relayer path, split_position, merge_positions, redeem_positions and scoped, revocable session keys. The allowance step that used to be a linked gist is inside the library.
• Account and portfolio. list_positions, list_trades, list_activity, get_portfolio_value, get_user_pnl, get_user_volume, get_resolutions and the rewards and builder-attribution calls.
• Streaming. subscribe() over the CLOB market and user channels, the live-data and sports feeds, with reconnection and heartbeats. Async clients only.

Check the install name before you type it. The package is polymarket-client and the import is polymarket. The bare polymarket distribution on PyPI is a three-kilobyte 2024 package by an unrelated author for exporting historical odds, and polymarket-sdk is a single 2026 release by a different unrelated author. Both install cleanly, neither is Polymarket's, and the name a reader guesses is one of those two rather than the right one.

Availability

The library has no geography. It installs from PyPI anywhere pip works, needs Python 3.11 or newer, and the public clients require no account, no key and no KYC. The us_persons and kyc_required flags on this card describe the package, not the exchange behind it - who may hold a funded position is a question about the venue, answered on polymarket.

What the package does decide is which Polymarket. Its only exported environment is PRODUCTION: Polygon chain 137, with clob.polymarket.com, gamma-api.polymarket.com, data-api.polymarket.com and the matching WebSocket hosts hard-coded into it. Polymarket US - the CFTC-regulated exchange on the .us domain - is not reachable through this SDK at any setting. It has its own Python package, polymarket-us, its own documentation site, its own key-by-key authentication and a different API surface, and it needs an account verified in the US app before keys can be generated at all. One vendor, two platforms, two SDKs, and nothing shared between them.

Pricing

Free and MIT-licensed. Nothing to buy, nothing metered, no paid tier of the library.

What a fill costs is the venue's business, not the package's. The SDK reads fee information back rather than setting it - get_builder_fee_rates returns the rates for a builder code - and the numbers belong on the venue's card.

Markets & resolution

A client resolves nothing. Orders placed through it reach Polymarket's CLOB and settle in USDC on Polygon like any other order on that book, and who decides an outcome is entirely the venue's question. The resolution-source row on this card is blank on purpose: the questions reachable through the SDK are whatever Polymarket lists, the library narrows nothing, and we have not surveyed that list here.

Two details of the data model still matter. A price is a probability - dollars from 0.00 to 1.00 per share, carried as Decimal rather than as a float. And the tradeable unit is a token ID, one per outcome; unlike its predecessor, this SDK will find them for you, because the Gamma discovery calls and the CLOB calls sit on the same client. The underlying HTTP services have cards of their own: polymarket-clob-api for the order book and orders, polymarket-gamma-api for events and markets.

It also reaches past event contracts. A perps module talks to Polymarket's perpetual-futures host, and the README marks every Perps API experimental and subject to change in any release.

Integrations

Seven runtime dependencies - eth-abi, eth-account, eth-utils, httpx[http2], msgpack, pydantic and websockets. That is a signing stack plus a typed HTTP and WebSocket client, which is the right way to read it: the package holds your private key in process to sign orders locally and posts signed payloads rather than credentials.

Optional extras carry the analysis side. pandas, polars and arrow each add one DataFrame backend and quant installs all three, after which a page or a paginator converts directly with to_pandas, to_polars or to_arrow. Models render as compact cards in Jupyter. The package ships py.typed and returns Pydantic models, so a type checker sees the API surface.

No CLI and no MCP server - it is a library, and anything built on it is your own code.

Limitations

It is 0.x, and it means it. The PyPI classifier says Beta, the README says minor releases on the 0.x line may include breaking changes, and 0.10.0 on 2026-09-10 shipped one: data reads were migrated to the Data API v2 contract. Pin the version.

Production only. One environment is exported. There is no testnet or paper target for a reader to rehearse against; the repository's own integration tests reach a staging chain by forking the environment through a private internal module, which is not a supported user path. Anything you run against this SDK runs against real money.

Streaming is async-only. PublicClient and SecureClient do not implement subscribe(). A sync script that wants live book updates has to poll or move to the async client.

Python 3.11 or newer. The archived predecessor ran on 3.9.10, so a stack pinned to an older interpreter cannot take the migration without moving first.

The perps surface is experimental by the vendor's own statement, including client methods, sessions, stream subscriptions and models.

It is four months old. First release 2026-05-21, twelve open issues and eleven open pull requests as of 2026-09-19, last commit on main 2026-09-18. That is an actively developed project rather than a settled one, and the API you write against this month may change under you the next - which is the trade for the predecessor being dead.

Alternatives

There is no second official Python SDK for this platform, so the alternatives are the predecessors and the generalists.

py-clob-client is the archived original, and Polymarket says it no longer functions - it is a reference for reading old code, not a choice. Between the two sat py-clob-client-v2, also Polymarket's own, last released at 1.1.0 on 2026-07-17 and carrying a note recommending the unified SDK for new projects; it has no card here. Worth knowing when you open the vendor's migration guide: its Python examples map py-clob-client-v2, the relayer client and the builder-signing SDK onto the new client, so a reader migrating from the original py-clob-client is reading a guide written one generation later than their code.

If the goal is several venues rather than this one, ccxt reaches Polymarket's CLOB through its prediction namespace alongside six other venues. If the goal is only to read prices and you would rather not carry a signing stack, polymarket-clob-api and polymarket-gamma-api are plain HTTP and need no client library at all.