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.

Two things here have no counterpart on the international platform. 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. 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 the resting side is paid 0.31% rather than charged. That maker figure is a rebate, which is why it is negative here — read the fee page and the Polymarket US card for the full curve before planning around the midpoint number.

There are no data plans, no tiers and no metering. The ceiling is the rate limit: 20 requests a second per API key across all authenticated endpoints, and 20 a second per IP on the public ones, both answering 429 when exceeded.

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.