# Polymarket US Python SDK

Official SDK for Polymarket US - installs as polymarket-us, unreleased since January.

*https://predictionmarkets.tools/tools/polymarket-us-python · Trading Clients, SDKs & Bots*

## Facts

### At a glance

| Field | Value |
| --- | --- |
| Vendor | Polymarket |
| Category | Trading Clients, SDKs & Bots |
| Job | sdk |
| Website | https://github.com/Polymarket/polymarket-us-python |
| Pricing model | open-source |
| Free tier | true |
| Open source | true |
| Licence | MIT |
| Self-hosted | true |
| Tested hands-on | false |
| Last updated | 2026-09-19 |

### Availability

| Field | Value |
| --- | --- |
| Jurisdictions | global |
| Open to US persons | true |
| KYC required | false |

### Markets

| Field | Value |
| --- | --- |
| Settlement | cash |
| Resolved by | none |

### Economics

| Field | Value |
| --- | --- |
| Taker fee | none |
| Maker fee | none |
| Liquidity model | clob |
| Platforms | library |
| AI features | none |

### Interfaces

| Field | Value |
| --- | --- |
| API | true |
| WebSocket | true |
| Scripting | none |
| Python | true |
| MCP server | false |
| Export | json |

### Capabilities

Yes: order_book, automation, live_trading, portfolio_tracking

No: charting, screening, backtesting, paper_trading, calibration_scoring, cross_venue, alerts, news, tax_reporting

*Verified: pricing 2026-09-19; availability 2026-09-19; capabilities 2026-09-19.*

## What it is

Polymarket's own Python SDK for Polymarket US, the CFTC-designated exchange run by QCX LLC, which
is a different venue and a different API from the on-chain Polymarket most readers arrive from.
Installing it is `pip install polymarket-us`; the repository is `Polymarket/polymarket-us-python`
and the README calls it the official SDK.

The client is thin and modern: `httpx` for transport, `pynacl` for Ed25519 signing, `websockets`
for streams, Python 3.10 or newer, MIT-licensed with the LICENSE file in the repository and the
classifier on PyPI agreeing. Both a synchronous `PolymarketUS` and an asynchronous
`AsyncPolymarketUS` are exported from the same package.

What it reaches:

- **Reads with no credential.** Events (list, by id, by slug), markets (list, by id, by slug,
  order book, best bid and offer, settlement price), series, sports and teams, and a search
  endpoint that returns events with their markets nested.
- **Orders.** `create`, `list`, `retrieve`, `modify`, `cancel`, `cancel_all`, `preview` and
  `close_position`. Orders are typed the way the exchange types them - an intent
  (`ORDER_INTENT_BUY_LONG`), an order type, a price with an explicit currency, a quantity and a
  time in force.
- **Account.** Positions and activity history through `portfolio`, and balances through `account`.
- **Streams.** `ws.markets()` for order book and trade updates, `ws.private()` for order, position
  and balance events. Both are async only.

Two details are better than most SDKs manage. Idempotent requests are retried with exponential
backoff and jitter on connection errors, timeouts and 408/409/429/5xx, while order placement is
never retried automatically - so a network blip cannot submit the same order twice. And every
request carries a generated correlation id that is attached to the exception when one is raised,
which is what you quote to support.

## Availability

The package imposes nothing. It installs from PyPI anywhere pip works and the read endpoints need
no credential at all.

The credential does impose something. API keys are issued from the developer page of a Polymarket
US account, and Polymarket US is a US exchange that requires identity verification before it will
let anyone trade - see [polymarket-us](https://predictionmarkets.tools/tools/polymarket-us) for who may open one. This card's
`us_persons` and `kyc_required` flags describe the library, which grants no access and blocks
none.

## Pricing

Free and MIT-licensed. Nothing to buy, nothing metered, no key tiers. What a fill costs is the
exchange's fee schedule and belongs on [polymarket-us](https://predictionmarkets.tools/tools/polymarket-us).

## Markets & resolution

An SDK resolves nothing. Orders placed through it rest on the Polymarket US order book and settle
in dollars against the exchange's own determination; who decides an outcome is a question about
the venue and is answered on its card.

One structural difference from Polymarket's on-chain stack is worth knowing before you write
against either. Here the tradeable unit is a market **slug** - `markets.book("btc-100k")`,
`orders.create({"marketSlug": ...})` - not a token id, and there is no wallet, no allowance and
no on-chain approval step in the way. The signing key is an exchange API credential, so the whole
class of Polygon approval failures that catches new users of
[py-clob-client](https://predictionmarkets.tools/tools/py-clob-client) does not exist on this side.

## Integrations

Three runtime dependencies - `httpx`, `pynacl`, `websockets`. That is the whole surface: a signing
client, not a framework. There is no CLI, no MCP server and no strategy layer.

Polymarket publishes a TypeScript twin, `polymarket-us-typescript`, in the same GitHub
organisation and under the same licence, last touched on the same day as this one. If you want the
same exchange from several languages, that is the other half; nothing else here is generated from
a shared specification the public can see.

## Limitations

**The released package is eight months behind the repository.** PyPI has exactly two releases,
0.1.1 and 0.1.2, both uploaded on 2026-01-22, and there are no GitHub releases or tags at all. Since
then `main` has taken a retry, user-agent and correlation-id change (2026-06-02) and a fix
correcting the order-snapshot subscription types (2026-09-17). Everything described above as
"better than most SDKs manage" is in the repository; only some of it is in the wheel you install.
Install from git if you need the fixes.

**It is version 0.1.2 and labelled Beta**, by its own classifier. Two people from Polymarket have
committed to it, issue traffic is negligible, and there is no changelog.

**No paper trading, no sandbox in the SDK.** `orders.preview` prices an order without submitting
it, which is not the same thing.

**WebSockets are async only**, including from the synchronous client, so a purely synchronous
program has to reach for `asyncio.run` to receive anything.

**It is single-venue by construction.** Polymarket US markets, Polymarket US credentials, and
nothing about the on-chain exchange that shares the name.

## Alternatives

For the on-chain Polymarket rather than the US exchange, the current official client is
[polymarket-client](https://predictionmarkets.tools/tools/polymarket-client); [py-clob-client](https://predictionmarkets.tools/tools/py-clob-client) is the
archived predecessor and should not be started from.

For several venues behind one interface, [ccxt](https://predictionmarkets.tools/tools/ccxt) and [pmxt](https://predictionmarkets.tools/tools/pmxt) both carry
Polymarket US among others, at the usual cost of reading somebody else's translation of the
exchange instead of the exchange.

If you only want prices, the exchange's REST endpoints answer unauthenticated and need no library
at all.

## FAQ

### What is the package called on PyPI?

polymarket-us. The import is polymarket_us and the repository is Polymarket/polymarket-us-python. It is a different product from polymarket-client, which is Polymarket's SDK for the global on-chain exchange and speaks to a different API entirely.

### Is the PyPI package current?

No. Version 0.1.2 was uploaded on 2026-01-22 and nothing has been published since, while the repository's main branch carries two later commits - an HTTP retry, user-agent and correlation-id change on 2026-06-02 and a fix to the order-snapshot subscription types on 2026-09-17. A pip install today gets the January code.

### Does it hold my private key?

It holds a Polymarket US API credential - a key id and a base64-encoded Ed25519 secret key, issued from the developer page of a Polymarket US account. Requests are signed in process. There is no wallet key and no on-chain signing, because the US exchange settles in dollars rather than on Polygon.

### Does it stream, or do I have to poll?

It streams. The SDK ships two WebSocket connections - a markets channel for order book updates and trades, and a private channel for orders, positions and balances. Both are async only, even when the rest of your code uses the synchronous client.

## Also from Polymarket

- [Polymarket CLI](https://predictionmarkets.tools/tools/polymarket-cli.md)
- [polymarket-client](https://predictionmarkets.tools/tools/polymarket-client.md)
- [Polymarket CLOB API](https://predictionmarkets.tools/tools/polymarket-clob-api.md)
- [Polymarket Gamma API](https://predictionmarkets.tools/tools/polymarket-gamma-api.md)
- [Polymarket US API](https://predictionmarkets.tools/tools/polymarket-us-api.md)
- [Polymarket US TypeScript SDK](https://predictionmarkets.tools/tools/polymarket-us-typescript.md)
- [Polymarket US](https://predictionmarkets.tools/tools/polymarket-us.md)
- [Polymarket](https://predictionmarkets.tools/tools/polymarket.md)
- [py-clob-client](https://predictionmarkets.tools/tools/py-clob-client.md)

## Background

- [What running a bot does not solve](https://predictionmarkets.tools/guides/what-a-bot-cannot-fix.md) — A bot fixes speed and consistency. Rate limits, a missing rehearsal, a field that stops arriving, a partial fill and a paused market are not coding problems.

- [Where your key lives when software trades for you](https://predictionmarkets.tools/guides/where-your-key-lives.md) — Four different credentials are all called a key, and they differ in what a copy permits. What the clients in this catalogue ask for, and what to ask them back.

## Also worth comparing

- [Kalshi Python SDK (sync and async)](https://predictionmarkets.tools/tools/kalshi-python-sync.md) — Kalshi's current official Python client - weekly releases, Python 3.13 only, no source.
- [kalshi-python](https://predictionmarkets.tools/tools/kalshi-python.md) — Kalshi's own generated Python client - closed-source, and unreleased since September 2025.
- [pykalshi](https://predictionmarkets.tools/tools/pykalshi.md) — Unofficial Kalshi client with what the generated SDK leaves out - streams and retries.
- [CCXT](https://predictionmarkets.tools/tools/ccxt.md) — One client for seven prediction venues, inside a 104-exchange crypto library.
- [limitless-sdk](https://predictionmarkets.tools/tools/limitless-sdk.md) — Limitless Exchange's own async Python SDK - CLOB and NegRisk orders, WebSocket, MIT.
- [PMXT](https://predictionmarkets.tools/tools/pmxt.md) — CCXT-shaped client for prediction markets, with a hosted API and a self-hosted mode.