Polymarket US API

What it is

The developer surface of Polymarket's US exchange, split across two hosts that behave nothing alike.

gateway.polymarket.us is the public half and takes no credentials at all. It serves markets, events, series, tags, sports leagues and teams, full-text search, price history, best bid and offer, the order book and the settlement price — everything a reader, a screen or a chart needs. Its generated OpenAPI description carries an explicit empty security list, and on 19 September 2026 every one of those paths answered this machine with 200 and no headers.

api.polymarket.us is the authenticated half: orders, portfolio, balances, and two WebSockets — a private stream for order, position and balance updates, and a markets stream for books and trades. An unauthenticated request to its root answers 401 Missing required API key headers. Your own record is GET /v1/portfolio/activities there — trades, resolutions, deposits, withdrawals and rebates, paged by cursor; export your Polymarket trade history covers it beside the international export.

Two things here go beyond a plain order book. Combos are multi-leg instruments you create through the API — up to 1,000 new combo instruments per exchange participant per week, resetting Monday at 00:00 UTC, with returning an existing canonical combo not counting against the quota. And an RFQ layer sits beside the book for those combos: create a request, read quotes, accept one side, confirm during last look. The international platform now has its own combos and RFQ flow on a separate host, which shares nothing with this one but the idea. There is also a separate institutional track — a Trader Guide with private-key JWT registration, preprod and production environments, and drop-copy reporting — documented alongside the retail one.

Availability

This is the CFTC-designated US exchange, so the account side is as narrow as the venue's: an account is opened in the iOS app, identity verification comes before trading and before API access, and an invite code may be required. The key is then created at the developer portal by signing in with the same method used in the app — the documentation warns that switching between Apple, Google and email sign-in can break key access.

The data side carries none of that. The public gateway is a single global host with no region selection, and it answered without credentials. As everywhere in this category, being able to read the book is not permission to trade against it.

Pricing

Nothing is charged for the API itself, on either host. What costs money is the fill, and the fee schedule is the venue's: on this card it is recorded as the effective rate at a price of 50 cents, where the taker pays 1.74% of the dollar of payout and a resting order is neither charged nor paid. Under the schedule effective 19 October 2026 the maker rebate starts at $10,000,000 of maker volume in the previous calendar month, so a new account earns none, and combo fills carry none at any tier — read the fee page and the Polymarket US card for the full curve and the tiers before planning around the midpoint number.

There are no data plans, no tiers and no metering. The ceiling is the rate limit, which changed after this card was first written: as the rate-limit page read on 4 October 2026, the retail API allows 25 requests a second shared across endpoints, enforced per source IP and Cloudflare location — so several API keys on one machine share one counter — with POST /v1/combos, POST /v1/rfqs and the RFQ listing routes at 1 a second, and quote creation and deletion at 100. Exceeding a limit answers 429.

Markets & resolution

Sports, overwhelmingly. Paging the public markets endpoint 500 rows at a time with active=true&closed=false reached 60,000 rows on 19 September 2026 without running out, and 52,800 of those carried category: sports against 6,351 politics, 472 culture, 151 macro, 79 technology, 77 finance, 54 crypto, 9 geopolitics and 7 science. Most of the sports volume is derivative lines rather than distinct questions — quarter totals, spreads and alternate handicaps on the same fixture, each its own row with its own slug.

Resolution is the exchange's own. There is no oracle, no bond and no dispute window to model: the outcome arrives as a settlement price on the market's slug, and a Contract Outcome Review under the rulebook is final. For code, that means the interesting endpoint is /v1/markets/{slug}/settlement rather than anything resembling a proposal feed.

Identifiers are slug-first. Price history, best bid and offer, the book and the settlement price are all addressed by market slug rather than by numeric id, and the slugs encode the fixture — aec-nfl-lac-ten-2025-11-02. Partner external ids (an OpticOdds fixture, for instance) resolve to an internal event through a dedicated endpoint, which is the supported way to join against an outside sports feed.

Integrations

REST on both hosts, plus the two WebSockets. Raw authenticated requests carry three headers — X-PM-Access-Key, X-PM-Timestamp and X-PM-Signature — with the signature built from the timestamp and the request using the secret key.

First-party SDKs exist in TypeScript and Python and handle the signing. Both are published by the vendor's own organisation and are MIT-licensed: polymarket-us on npm at 0.1.1, last published 21 January 2026 from Polymarket/polymarket-us-typescript, and polymarket-us on PyPI at 0.1.2, uploaded 22 January 2026 from Polymarket/polymarket-us-python, whose default branch was last pushed to on 17 September 2026. Those are 0.x version numbers on a live exchange; pin them.

Batch routes take up to 20 orders for create, cancel and modify. The documentation is unusually blunt about what a 200 on those means: a per-entry exchange outcome is delivered on the order stream, not in the response, and canceledOrderIds is an echo of the request rather than a confirmation.

Limitations

• Unknown query parameters are silently ignored. /v1/markets?category=politics returned a response byte-identical to /v1/markets on 19 September 2026 — same MD5 — because category is not a parameter of that endpoint. A mistyped filter does not 400; it returns an unfiltered page that looks filtered.
• No total count anywhere. The markets response is a bare markets array with no pagination envelope, so there is no way to know how many rows a filter matched without walking to the end.
• limit is capped at 500 and silently clamped: a request for 1,000 returns 500 without saying so.
• The developer path runs through an iOS app and an identity check. No app, no key — and that is the gate on the WebSockets and on every write, not just on trading.
• A latency reject looks exactly like a rate limit. The five-second order stopgap returns Global Rate Limit Exceeded, and backing off in response is the wrong reaction.
• Nothing ports from the international platform. Different hosts, different identifiers, different signing scheme, no wallet, no UMA.

Alternatives

For the international Polymarket, the Gamma API is the catalogue and the CLOB API is the book and the order router, both keyless to read and neither usable from the US. For the other US-regulated exchange, the Kalshi API has published token-bucket limits and a demo environment, which this one does not. If the requirement is the same data alongside other venues in one schema, FinFeedAPI and Adjacent sell that, and neither is free.