Polymarket US Developer Portal: API Access and SDK Guide
The Polymarket US developer portal is the credential and documentation entry point for applications built against the regulated US product. Generate keys at the official polymarket.us/developer page, use the official Python or TypeScript SDK, keep secrets on the server, and treat the US API as a separate product from the international Polymarket APIs.
That last distinction prevents the most expensive integration mistake. Code written for gamma-api.polymarket.com, data-api.polymarket.com or the international CLOB is not automatically compatible with Polymarket US. The objects, authentication, legal access and order workflow can differ even when both products use prediction-market language.
Identify the product before writing code
There are two documentation families developers may encounter.
| Product | Typical use | Starting point |
|---|---|---|
| Polymarket US | US events, portfolios and regulated trading API | polymarket.us/developer and official US SDKs |
| International Polymarket | Gamma discovery, Data API analytics and CLOB trading | docs.polymarket.com |
Do not choose an endpoint because a search result looks familiar. Confirm the hostname, SDK repository owner and product name. The official Polymarket US Python repository describes API keys generated at the US developer portal. The official TypeScript repositories expose the same product family in JavaScript-friendly packages.
Build separate configuration namespaces such as POLYMARKET_US_* and POLYMARKET_GLOBAL_*. This reduces the risk that a production service sends a key to the wrong host.
What you can build
The US SDK documentation groups functionality around public discovery and authenticated account operations. Depending on the current API version and account permissions, an application can work with:
- events and markets;
- categories and series;
- market search and filtering;
- order books and recent trades;
- portfolio positions and account trades;
- order placement, modification and cancellation;
- market and private WebSocket streams.
A read-only event browser is a very different security project from an execution bot. Start with public endpoints, then add account reads, and add trading only after monitoring and controls are complete.
Create and protect API credentials
Generate credentials only while signed in on the official Polymarket US domain. Record the key identifier and secret in a secrets manager. If the portal shows a secret only once, do not place it in screenshots, chat messages or tickets.
Production rules:
- Keep secrets out of browser JavaScript and mobile bundles.
- Never commit
.envfiles or copied request headers. - Use separate keys for local development, staging and production if supported.
- Give a service only the permissions it needs.
- Rotate a key after suspected exposure and test revocation.
- Log the key identifier, not the secret.
- Prevent request logs and error trackers from capturing authorization headers.
A public repository containing a deleted secret is still compromised. Git history, forks, package caches and automated scanners may retain it. Revoke first; clean history second.
Install an official SDK
The official Python SDK repository is Polymarket/polymarket-us-python. The official TypeScript SDK repositories are under the same Polymarket GitHub organization. Check the repository README and package registry before installing because package names and versions can change.
For Python, use a dedicated virtual environment and pin an exact version in the deployment lockfile. For TypeScript, keep the runtime and SDK package versions in package-lock.json, pnpm-lock.yaml or the equivalent.
Before upgrading:
- read release notes and migration instructions;
- run contract tests against a non-production account;
- compare response schemas;
- confirm numeric precision and timestamp parsing;
- retest authentication and WebSocket reconnects.
Do not copy an installation command from an unofficial blog without checking it against the current official README.
Model money and probability precisely
Prediction-market prices and quantities should not use binary floating point for validation or accounting. A value displayed as 0.10 can become a nearby internal float, causing tick-size or total mismatches.
Use decimal arithmetic:
from decimal import Decimal
price = Decimal("0.63")
quantity = Decimal("125")
notional = price * quantity
Preserve the SDK’s documented units. A field may represent cents, dollars, contracts or a decimal probability. Do not infer the unit from a convenient-looking number.
Validate:
- minimum and maximum price;
- permitted tick increment;
- quantity step;
- side and outcome identifiers;
- maximum acceptable notional;
- market status and close time.
The order preview in your own interface should show the same economic commitment a user will submit.
Read market data before opening private access
Begin with an event browser that retrieves events, individual markets and order-book data. Store both the exchange identifier and a human-readable slug or title; titles are not reliable primary keys.
A robust market-data cache records:
{
"source": "polymarket-us",
"event_id": "exchange-assigned identifier",
"market_id": "exchange-assigned identifier",
"retrieved_at": "UTC timestamp",
"sequence_or_version": "if provided",
"payload": "unmodified response"
}
This makes it possible to diagnose whether a stale screen came from the upstream API, your cache or the client.
Market pages should display the full contract question and resolution terms. A short label is not enough for execution. Two similarly named contracts can have different deadlines, sources or thresholds.
Use WebSockets as streams, not truth by themselves
Official SDKs expose market and account streaming helpers. WebSockets reduce latency, but connections can drop, events can be delayed, and a process can restart between messages.
Use a snapshot-plus-stream pattern:
- Request a REST snapshot.
- Record its sequence or time marker if available.
- Subscribe to the relevant WebSocket channel.
- Apply updates in order.
- Detect gaps, malformed messages and stale heartbeats.
- Re-fetch a snapshot after an uncertain reconnect.
Do not assume silence means “no change.” It may mean the subscription failed. Alert when the last-message age exceeds the expected interval.
Private streams can contain order or account information. Keep them behind authenticated backend services and apply access control to any internal dashboard that displays them.
Design an order lifecycle that can fail safely
An execution request has more states than “sent” and “filled.” A useful internal state machine includes:
- locally validated;
- submission pending;
- accepted or rejected;
- open;
- partially filled;
- filled;
- cancel requested;
- cancelled;
- expired or closed by market state;
- reconciliation required.
The official Python SDK README warns that cancellation and modification response arrays can echo submitted IDs and should not be treated as proof that every requested order changed. An unknown order ID may be ignored. Therefore, reconcile the live order state after a cancel or modify call.
Network timeouts are ambiguous. The exchange may have accepted an order even though your client did not receive the response. Use an idempotency mechanism when the API supports one, and otherwise query orders before retrying. Blind retry loops can create duplicate exposure.
Put risk controls outside the strategy
A strategy process should not be able to disable its own limits. Enforce controls in a separate execution layer.
Recommended controls include:
- maximum order quantity and notional;
- maximum exposure per market and correlated event;
- price collars relative to a recent verified book;
- daily loss and error thresholds;
- market-status and close-time checks;
- duplicate-order detection;
- a global cancel and disable switch;
- reconciliation between orders, fills and positions.
Test the kill switch before it is needed. A button that has never been exercised is documentation, not a control.
Handle rate limits and errors deliberately
Respect the current API documentation rather than guessing a request rate. On a retryable response, use capped exponential backoff with jitter. Do not retry authentication failures, validation errors or insufficient-balance responses as if they were transient.
Classify errors:
| Class | Example response | Safe action |
|---|---|---|
| Validation | Invalid price or quantity | Fix input; do not retry unchanged |
| Authentication | Expired or invalid credential | Stop and rotate or reauthenticate |
| Rate limiting | Too many requests | Back off and reduce concurrency |
| Server/transient | Temporary upstream failure | Retry with a cap and idempotency protection |
| Ambiguous timeout | No response after submit | Reconcile before retrying |
Log the request ID returned by the service when available. Redact credentials and sensitive account data.
A safe development sequence
Phase 1: Public explorer
List events, open a market, show rules and render the order book. No account credentials.
Phase 2: Read-only account view
Display positions, trades and orders for the authenticated account. Confirm that access is denied for other accounts.
Phase 3: Paper execution
Simulate fills against recorded books. Include spread, partial fills, delays and rejected orders.
Phase 4: Minimum-size live test
Submit one small limit order in a market you understand. Reconcile it through open, partial, cancel and final position states.
Phase 5: Controlled automation
Enable a small allowlist of markets and conservative limits. Add alerts before increasing scope.
This sequence makes operational failures visible while their cost is still small.
Testing that matters
Unit tests alone do not prove an exchange integration works. Add fixtures and integration tests for:
- decimal rounding at tick boundaries;
- a market closing between validation and submission;
- partial fills followed by cancellation;
- duplicate and out-of-order stream messages;
- a WebSocket disconnect during a fill;
- a timeout after an order may have been accepted;
- key revocation;
- stale order-book data;
- daylight-saving and UTC conversion errors;
- schema fields added without warning.
Replay real sanitized messages through the parser. Property-based tests are useful for price, quantity and serialization boundaries.
Compliance and product boundaries
API access does not override geographic, account, identity or product rules. Do not use automation to evade restrictions, operate another person’s account or conceal beneficial ownership.
If you build for others, address:
- clear order confirmation and error messages;
- audit records and retention;
- permission revocation;
- data minimization;
- suitability of alerts and risk statements;
- applicable licensing and legal obligations.
The US product can change independently of the international product. Recheck the official portal, terms and SDK release notes before launch.
Frequently asked questions
Is the Polymarket US API the same as the international Polymarket API?
No. Treat them as separate products with different hosts, SDKs, authentication and availability. Do not send credentials from one product to the other.
Where do I create a Polymarket US API key?
The official SDK documentation directs users to polymarket.us/developer. Navigate there from the official US site rather than a third-party link.
Can I put the API secret in a browser app?
No. Browser code and mobile bundles can be inspected. Keep secrets in a controlled backend or secrets manager.
Does a successful cancel request prove the order is cancelled?
Not necessarily. The official SDK notes that returned cancellation identifiers may echo the request. Query live order state and reconcile positions.
Should an automated client retry a timed-out order submission?
Only after checking whether the first request was accepted. An immediate blind retry can duplicate the order.
Official sources
- Polymarket US Developer Portal
- Official Polymarket US Python SDK
- Official Polymarket US TypeScript SDKs
- Polymarket International Documentation
Risk notice: Trading APIs can create, modify and cancel financial positions. Use least-privilege credentials, tested limits and independent reconciliation. Examples are educational and not trading or legal advice.
Related guides
Update log
- November 17, 2026: Verified portal location and implementation notes against the official Polymarket US Python and TypeScript SDK repositories.