Polymarket API Guide

Which Polymarket API should you use?

A common read path starts with Gamma discovery, then uses returned market and token identifiers to request current book data from the CLOB. Do not treat a Gamma display price as a guaranteed execution price.

Make a first public-data request

This request lists a small set of active, open markets without an API key:

curl "https://gamma-api.polymarket.com/markets?active=true&closed=false&limit=5"

Production code should:

1. validate response status and schema;
2. paginate rather than loading the whole catalogue at once;
3. store stable market and token identifiers rather than matching by title;
4. request a fresh CLOB book or quote immediately before an action; and
5. treat status, tick size, fee enablement, and resolution rules as dynamic metadata.

The odds guide explains why a displayed probability and an executable bid or ask can differ.

How Polymarket API authentication works

L1: EIP-712 wallet signature

L1 authentication proves control of the signing address and is used to create or recover API credentials. Generate the signature locally. A private key or seed phrase should never be sent to an API endpoint, embedded in a support message, or stored in source control.

L2: credentials and HMAC

L2 uses the generated API key, secret, and passphrase to create an HMAC-SHA256 signature for authenticated requests. Required POLY_* headers include the signer address, timestamp, API key, passphrase, and request signature.

Order payloads are also wallet-signed. L2 authenticates the request; the order signature authorizes the outcome-token order. Using an official client reduces the risk of constructing either signature incorrectly.

Email or social-login accounts can use a proxy or funder address that differs from the signer. Configure both roles according to the current SDK rather than assuming every address field is the same wallet.

Current unified SDK choices

Older CLOB clients and examples remain online. Do not mix method names, credential handling, or request formats from different client generations without checking compatibility.

Selected current rate limits

Polymarket uses Cloudflare sliding-window throttling. Current documentation says excess traffic is throttled or delayed rather than necessarily dropped at the instant a limit is crossed. Applications should still use bounded concurrency, caching, backoff, and WebSockets for high-frequency updates.

These are ceilings, not recommended targets. Endpoint-specific, burst, and sustained limits can apply together. A separate per-signer trading limiter was in warning-only rollout in late July 2026, with enforcement to be announced. Check the current trading-rate-limit page before deployment rather than treating warning-period behavior as permanent.

Implementation practices that prevent common failures

Use the CLOB book for executable prices

Polymarket normally displays the bid-ask midpoint and can show the last trade when the spread exceeds 0.10. A buyer executes against asks and a seller against bids. Fetch a current book before estimating fill price or slippage.

Read market-specific parameters

Tick size, status, token identifiers, and fee enablement can vary. Do not hard-code one precision or fee treatment for every market. The fees guide explains the market-specific formula.

Combine a snapshot with streams

Use REST for the initial state, then apply WebSocket updates. After a disconnect, fetch a fresh snapshot before applying new incremental messages; do not assume every missed update will replay.

Keep secrets out of browsers and logs

Public reads can run without credentials. Authenticated trading secrets belong in a controlled backend or signer environment. Never expose an API secret, passphrase, or wallet key in frontend JavaScript, logs, or a repository.

Enforce geographic restrictions

API trading is subject to the same location rules as the website. Use the public geoblock endpoint and handle server enforcement. An API is not a route around a restricted interface or physical-location rule.

Polymarket API troubleshooting

Public results are missing expected markets

Check the API family, filters, pagination, and market status. Gamma metadata, CLOB token data, and Data API records use related but distinct identifiers.

An authenticated request is rejected

Check system-clock accuracy, timestamp, exact method and path in the HMAC payload, credential pairing, and signer address. Do not invent headers from an older SDK example.

An order fails after authentication succeeds

Authentication and order validity are separate. Verify token, side, price, amount, tick size, balance or allowance, market status, fee parameters, and signer/funder configuration.

Requests become slow under load

Throttling can appear as delay rather than a clean error. Reduce concurrency, cache metadata, respect sustained limits, and use WebSockets for rapidly changing data.

A local WebSocket book drifts from REST

Reconnect, fetch a fresh snapshot, and resubscribe. Do not continue from a state that may have missed updates.

Keep International, US, and Perps APIs separate

This page describes Polymarket.com International prediction-market interfaces. Polymarket US publishes separate developer documentation. Polymarket Perps also uses separate leverage, margin, funding, and fee mechanics.

Do not reuse International endpoints, pUSD assumptions, credentials, or schemas for another product unless that product's current documentation explicitly supports them. An affiliate or website link also does not create API credentials; credentials are generated through the documented authentication flow.