Polymarket US TypeScript SDK

What it is

Polymarket's own TypeScript client for Polymarket US, the CFTC-designated exchange run by QCX LLC — a different venue and a different API from the on-chain Polymarket most readers arrive from. It installs as npm install polymarket-us, the repository is Polymarket/polymarket-us-typescript, and the exchange's own quickstart names that package beside the Python one, so there is no ambiguity about which install name is the vendor's.

It is one package, not three. The repository holds a single library — src/client.ts, eight resource modules, a WebSocket folder and a type folder — with no workspace, no packages/ directory and no second manifest. npm carries exactly one Polymarket US distribution, polymarket-us, published from a @polymarket.com account. The scoped @polymarket/* names on npm — client, clob-client, bindings, sdk-v2 — belong to the international on-chain platform and speak to a different API entirely.

The surface mirrors the Python twin almost method for method:

• Reads with no credential. events.list/retrieve/retrieveBySlug, markets.list, markets.retrieveBySlug, markets.book, markets.bbo, markets.settlement, series.list, sports.list, sports.teams and search.query.
• Orders. create, list, retrieve, modify, cancel, cancelAll, preview and closePosition, typed the way the exchange types them — an intent such as ORDER_INTENT_BUY_LONG, an order type, a price with an explicit currency, a quantity and a time in force.
• Account. portfolio.positions, portfolio.activities and account.balances.
• Streams. ws.markets() for books and trades, ws.private() for orders, positions and balance events, both as typed emitters with heartbeat, error and close.

Errors are classes rather than status codes: AuthenticationError, BadRequestError, NotFoundError and RateLimitError are exported and meant to be caught by instanceof.

Availability

The package imposes nothing. It installs from npm anywhere, needs Node 18 or newer, and the read endpoints answer with 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 requires identity verification before it will let anyone trade — see 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, with the LICENSE file present in the repository and the npm license field agreeing. Nothing to buy, nothing metered, no key tiers. What a fill costs is the exchange's fee schedule and belongs on 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.

The addressing is slug-first, as on the rest of this exchange: markets.book('btc-100k'), orders.create({ marketSlug: 'btc-100k-2025', ... }). There is no token id, no wallet, no allowance and no on-chain approval step, so the class of Polygon approval failures that catches new users of py-clob-client does not exist here.

Integrations

Two runtime dependencies — @noble/ed25519 for signing and ws for streams. The build ships both ESM and CommonJS entry points with separate type declarations, so it drops into either module system without a shim.

Authentication is the exchange's Ed25519 scheme, and it is worth knowing exactly what gets signed: the client concatenates the millisecond timestamp, the HTTP method and the request path, signs that, and sends X-PM-Access-Key, X-PM-Timestamp and X-PM-Signature. The request body is not part of the signed message. The Python SDK signs the same three components in the same order, so this is the exchange's design rather than a quirk of one client.

The two hosts are separate and both are overridable through gatewayBaseUrl and apiBaseUrl: public reads go to gateway.polymarket.us, everything authenticated to api.polymarket.us, and the streams to wss://api.polymarket.us. Request timeout defaults to 30 seconds and is a constructor option.

There is no CLI, no MCP server and no strategy layer. The Python twin ships an examples/ directory; this repository ships none, and the README is the whole of the worked code.

Limitations

The published package is eight months behind the repository. npm has five versions, every one of them uploaded on 20 or 21 January 2026, and latest is 0.1.1 from 21 January. Since then main has taken exactly one commit — a fix correcting the order-snapshot subscription types on 17 September 2026 — and package.json on main still reads 0.1.1, so that fix is not queued for a release either. There are no GitHub releases and no tags at all. Install from git if you need it.

No retries, no correlation id. The Python twin ships _retry.py with exponential backoff on connection errors, timeouts and 408/409/429/5xx, and attaches a generated correlation id to every exception. The TypeScript client has neither: one fetch, one abort timer, one throw. On an exchange that documents a five-second inbound-order stopgap returning a rate-limit message, that difference is yours to write.

The first three npm versions are empty. 0.0.1, 0.0.2 and 0.0.3 are 662-byte deployment tests published by the vendor within three minutes of each other. They are harmless, but a version string alone does not tell you whether a release contains a library.

WebSockets refuse to run in a browser, by an explicit check and a thrown error rather than by failing obscurely. The stated reason is that the exchange authenticates streams with headers a browser WebSocket cannot set.

It is 0.1.1 on a live exchange, with fifteen stars, one open pull request, no open issues, no changelog and three human contributors. Pin it.

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

Alternatives

The Polymarket US Python SDK is the same exchange, the same signing scheme and the same method inventory, with the retry layer this one lacks — and the same release lag.

If you would rather not take a 0.1.x dependency at all, the Polymarket US API is plain REST with three headers, and its public gateway answers unauthenticated.

For the on-chain Polymarket rather than the US exchange, the official client is polymarket-client in Python; there is no first-party TypeScript equivalent on this side of the catalogue that covers both. For several venues behind one interface, ccxt and pmxt both carry Polymarket US, at the usual cost of reading somebody else's translation of the exchange instead of the exchange.