Think of the Polymarket API as three separate doors, only one of which is locked. Market data and history are open to anyone who asks. Placing an actual order is the one door that needs a key — and understanding why that split exists will save you more debugging time than memorizing endpoint names.
Three APIs, One Underlying System
Gamma handles the descriptive layer — what a market is asking, which category it sits in, when it resolves. The Data API answers historical questions: what happened, who held what, how a market’s price moved over time. The CLOB API is where the actual order book lives — current bids and asks, and the machinery to place or pull an order. All three ultimately describe the same underlying markets; they’re just split by what kind of question you’re asking.
Everything reference-level — the exact schema, current rate limits, endpoint paths — lives at docs.polymarket.com. Treat that as the source of truth; anything here is the conceptual map, not a substitute for it.
Reading Requires Nothing Extra
Here’s the part a lot of newcomers overcomplicate: pulling a live price, a current spread, or an order book snapshot needs no credentials at all. We rely on exactly this for PolyScope’s own top-markets display — a plain GET request against public endpoints, refreshed every few minutes rather than hit on every page load. If your project is purely about showing or analyzing market data, you can plausibly ship the whole thing without ever generating an API key.
The Lock: Why Trading Needs Two Layers
Submitting or cancelling an order is different, because it moves real money, and the system wants two separate guarantees before it lets that happen.
The first guarantee is ownership: your wallet’s private key signs a structured message (EIP-712 format), proving cryptographically that whoever is asking actually controls the funds. Think of this as your passport — it proves identity, but you don’t want to hand it over for every single request.
The second layer is a set of API credentials — key, secret, and passphrase — generated once through that passport-level proof, then reused like a hotel key card for the rest of your session. Every order placement or cancellation needs the full set of these credentials attached as headers; lose one and the request fails, typically with an error that looks like a bad signature rather than a missing field, which is exactly why this step trips people up.
Don’t Write Your Own Signing Logic
Polymarket maintains official client libraries — a Python client, plus TypeScript and Rust versions — that already handle this signing correctly. Building your own EIP-712 signer from scratch is a solvable problem, but it’s rarely worth solving: a subtly wrong signature doesn’t throw a clean parsing error, it just gets rejected as unauthorized, and diagnosing that blind is a bad use of a first afternoon on this API.
A Sane First Build
- Pull market metadata from Gamma — question text, category, resolution date.
- Pull the live order book from the public CLOB endpoint for pricing and depth.
- Cache both server-side on a short timer instead of polling continuously.
- Only wire up L1/L2 authentication once you actually need to place or cancel an order — for the trading mechanics themselves, our step-by-step guide covers what those orders mean from a trader’s side.
What This Enables Beyond a Dashboard
Anything capable of hitting these endpoints and signing correctly is trading on the exact same order book the website uses — same liquidity, same prices, same settlement path. That’s also the entire mechanism behind Telegram-based trading tools: strip away the chat interface and a bot like Overdog is functionally a CLOB API client with a non-custodial wallet layer and its own Polygon node attached, built to keep execution latency down when it matters. One common build on top of this: a bot that watches a wallet’s on-chain activity and mirrors its trades automatically — see our guide to copy trading on Polymarket for how that works in practice.
FAQ: Polymarket API
Do I need credentials just to read prices? No — Gamma and the public CLOB read endpoints are open without any key.
What’s actually different between the two auth layers? One proves wallet ownership directly via a signed message; the other is a reusable credential set generated from that proof, used for ongoing trading requests.
Is hand-rolling my own signer a bad idea? Not impossible, just rarely worth it — the official Python client and its TypeScript/Rust siblings already solve this correctly.
Can this API power an actual trading bot? Yes — that’s precisely what a Telegram-based trading tool is under the hood. For how order books and settlement work conceptually, see our guide to how Polymarket works.
See our Disclaimer. Confirm current endpoint behavior against official docs before building anything that moves real funds.