# Polymarket US TypeScript SDK Official TypeScript client for Polymarket US - npm has shipped nothing since January. *https://predictionmarkets.tools/tools/polymarket-us-typescript · 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-typescript | | Pricing model | open-source | | Free tier | true | | Open source | true | | Licence | MIT | | Self-hosted | true | | Tested hands-on | false | | Last updated | 2026-09-20 | ### 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 | false | | 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-20; availability 2026-09-20; capabilities 2026-09-20.* ## 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](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, 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](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. 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](https://predictionmarkets.tools/tools/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](https://predictionmarkets.tools/tools/polymarket-us-python) 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](https://predictionmarkets.tools/tools/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](https://predictionmarkets.tools/tools/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](https://predictionmarkets.tools/tools/ccxt) and [pmxt](https://predictionmarkets.tools/tools/pmxt) both carry Polymarket US, at the usual cost of reading somebody else's translation of the exchange instead of the exchange. ## FAQ ### Is there one TypeScript package or several? One. Polymarket publishes a single package for its US exchange, polymarket-us on npm, built from the Polymarket/polymarket-us-typescript repository, which holds one library and not a workspace. There is no separate clob, gamma or data package on this side - those names belong to the international on-chain platform, where the scoped @polymarket packages live. ### Is the npm package current? No. Version 0.1.1 was published on 21 January 2026 and nothing has been published since, while the repository's main branch took a fix to the order-snapshot subscription types on 17 September 2026 without bumping the version. There are no GitHub releases and no tags. An npm install today gets the January code. ### Does it handle retries the way the Python SDK does? No, and this is the clearest difference between the twins. The Python package ships a retry module with exponential backoff and a correlation id on every request; the TypeScript client has neither - one fetch call, a 30-second AbortController timeout, and an APIError raised on failure. ### Can I use it in a browser? Partly. REST calls use the global fetch and will run anywhere it exists, but the WebSocket half refuses outright - it checks for window.document and throws, because the exchange authenticates streams with headers that a browser WebSocket cannot send. Streaming is Node-only by design, not by omission. ## 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 Python SDK](https://predictionmarkets.tools/tools/polymarket-us-python.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.