Polymarket API Beginner Guide: Markets, Prices, Trades and IDs
Start with Polymarket’s public, read-only APIs: discover an event, choose one market, map its YES and NO outcome IDs, then request the current book or price history. Do not begin by generating private keys or placing an order. Public market data requires less trust and lets you verify your data model before money is at risk.
Polymarket exposes several services rather than one universal endpoint. The most common beginner error is sending the right parameter to the wrong service.
The API map
| Need | Official service | Typical host |
|---|---|---|
| Discover events and markets | Gamma API | gamma-api.polymarket.com |
| Prices, history, trades and analytics | Data API / CLOB data | data-api.polymarket.com, clob.polymarket.com |
| Live market updates | Market WebSocket | ws-subscriptions-clob.polymarket.com |
| Place and manage orders | Authenticated CLOB / unified SDK | Official secure client and CLOB host |
| Wallet operations | Relayer and secure client | Documented account-specific services |
Use the official documentation index to confirm hosts and schemas. A third-party endpoint can be useful, but it should not be presented as the official API.
Understand event, market and outcome
Polymarket’s data model has three layers:
- Event: groups one or more related markets.
- Market: one tradable question with resolution rules.
- Outcome: YES or NO, each with its own trading identifier.
For example, an election event may include one binary market per candidate. An event ID is not an outcome ID. The order-book endpoint needs the selected outcome’s asset identifier.
The protocol version determines that identifier:
- CTF markets expose
clobTokenIds; - Protocol V2 markets expose
positionIds; - the unified SDK normalizes the selected value as
assetIdorasset_id.
Never assume index zero means YES until you verify the outcome array and documentation.
Step 1: list active events
The official quickstart uses keyset pagination:
curl -G "https://gamma-api.polymarket.com/events/keyset" \
--data-urlencode "closed=false" \
--data-urlencode "limit=5"
The response contains event records and pagination information. Use a specific event slug or URL when you already know the target; use the list endpoint for a feed.
Do not download every market repeatedly. Cache stable metadata such as title and slug, while refreshing status, rules, outcomes and trading constraints as needed.
Step 2: fetch a specific event
A known event can be fetched by ID or slug:
curl "https://gamma-api.polymarket.com/events/slug/<event-slug>"
Inspect each nested market. Save:
- market ID;
- condition ID;
- protocol version;
- question and slug;
- close status;
- YES/NO identifiers;
- resolution source and rule text where supplied.
Use the market question rather than the event title in a trading display. One event can contain contracts with different dates or conditions.
Step 3: select the correct outcome ID
For a legacy CTF market, Gamma can return clobTokenIds as a JSON-encoded string. Parse it as JSON; do not split it manually on commas. For V2, use the corresponding item in positionIds.
Python example:
import json
def outcome_ids(market):
if market.get("version") == "v2":
ids = market["positionIds"]
else:
ids = json.loads(market["clobTokenIds"])
outcomes = market.get("outcomes")
if isinstance(outcomes, str):
outcomes = json.loads(outcomes)
return dict(zip(outcomes, ids))
Validate that both arrays have equal length. If fields are missing, fail explicitly rather than silently choosing an identifier.
Step 4: request the order book
With a YES outcome ID:
curl "https://clob.polymarket.com/book?token_id=<yes_asset_id>"
The response includes bids, asks, minimum order size, tick size, last traded price, a timestamp and a book-state hash.
The current documentation notes that bids are ordered ascending and asks descending, so the best price is the last entry in each array. Do not take element zero without checking the documented order.
def best_prices(book):
best_bid = float(book["bids"][-1]["price"]) if book["bids"] else None
best_ask = float(book["asks"][-1]["price"]) if book["asks"] else None
return best_bid, best_ask
Use decimal arithmetic for production financial calculations. Binary floating point is shown only to keep the example readable.
Step 5: read trades and price history
Recent matched trades for a market can be requested with its condition ID:
curl "https://data-api.polymarket.com/v2/trades?condition=<condition_id>&limit=20"
The official schema includes wallet, side, outcome identifier, condition, size, price, timestamp and transaction hash. Trades are returned newest first.
Historical outcome observations use an outcome ID:
curl "https://data-api.polymarket.com/v2/prices-history?token_id=<asset_id>&interval=1d&bucket_seconds=3600"
Price-history points are returned oldest first. Read resolution_seconds; do not assume every row has identical spacing.
Pagination is part of correctness
List and analytics endpoints may return a cursor with has_more. A script that reads only the first page can produce a biased sample.
Generic loop:
import requests
def fetch_pages(url, params):
cursor = None
while True:
query = dict(params)
if cursor:
query["cursor"] = cursor
data = requests.get(url, params=query, timeout=20).json()
yield from data.get("data", data.get("items", []))
page = data.get("pagination", {})
if not page.get("has_more"):
break
cursor = page["next_cursor"]
The exact response container varies by endpoint. Check the live schema instead of forcing every service into one parser.
Use strings or decimals for prices
The official SDK types prices and sizes as decimal strings or decimal objects. Preserve that behavior.
from decimal import Decimal
price = Decimal("0.37")
shares = Decimal("250")
cost = price * shares
Avoid float for order validation, fee calculations and totals. A small rounding error can violate tick size or change a signature.
Normalize timestamps to UTC and store the original value. Some raw endpoints use epoch seconds, others milliseconds, while SDKs may return timezone-aware datetime objects.
Public data versus authenticated trading
Market discovery, public books and public analytics can be read without exposing a wallet secret. Trading is different.
Polymarket’s current authentication documentation distinguishes:
- the signer address;
- the account wallet;
- wallet type;
- L1 signatures proving control;
- L2 CLOB credentials;
- Relayer or Builder API credentials for specific operations.
Do not copy a private key into a notebook, front-end bundle or chat message. Store secrets in a server-side secret manager or protected environment variables. Never log the CLOB secret or passphrase.
For a first project, stop at public data. Add trading only after the read path, identifiers, rounding, risk limits and failure handling are tested.
Error handling that beginners usually skip
Production code should:
- set connection and read timeouts;
- retry only transient failures with backoff and jitter;
- stop after a capped number of retries;
- handle
429without sending a request storm; - distinguish an empty book from an endpoint failure;
- validate schema before using fields;
- log request ID, endpoint and timestamp without secrets;
- reject stale data;
- use idempotent logic for order submission.
The official error-code documentation separates validation, authentication, balance and matching-engine problems. Do not retry a permanently invalid order as if it were a network timeout.
A safe first project
Build a read-only market monitor:
- Accept a Polymarket event URL.
- Fetch the event by slug.
- Display each market and its rule summary.
- Map YES and NO asset IDs.
- Fetch both books every 30 seconds.
- Calculate best bid, best ask and spread.
- Mark data stale after a defined threshold.
- Save timestamped JSON for later analysis.
This project teaches the full identifier chain without creating custody or order risk.
Common API mistakes
- Sending a condition ID where an outcome ID is required.
- Parsing JSON-encoded arrays as ordinary strings.
- Assuming the first book level is the best.
- Treating last trade, midpoint and executable ask as the same price.
- Ignoring cursor pagination.
- Mixing seconds and milliseconds.
- Using current market metadata to reconstruct a historical universe.
- Exposing secrets in browser JavaScript or Git history.
- Retrying rejected orders indefinitely.
Frequently asked questions
Is the Polymarket API free to read?
Public market-data endpoints do not require trading credentials. Usage remains subject to current documentation, terms and service controls.
Which API should I use to find markets?
Use the Gamma API or official public SDK market-listing methods. Then use the outcome IDs with the Data API or CLOB endpoints.
Do I need a wallet to read live odds?
No. Public event, market, book and price data can be read without signing a wallet transaction.
What is the difference between condition ID and token ID?
The condition identifies the binary market. The token or position ID identifies one tradable outcome. Book and price-history requests generally need the outcome identifier.
Can I place orders with the same public endpoint?
No. Order placement requires authenticated credentials, signatures and a correctly configured account. Follow the secure-client documentation.
Is there an official Python SDK?
Yes. The current documentation provides Python and TypeScript examples through unified official clients, alongside direct API calls.
Official sources
- Polymarket Documentation — Overview
- Polymarket Documentation — Discover Markets
- Polymarket Documentation — Prices and Order Books
- Polymarket Documentation — Analytics
- Polymarket Documentation — Wallets and Authentication
- Polymarket Documentation — Error Codes
Developer notice: Code examples are educational and omit production controls. Market schemas, hosts and authentication flows can change. Verify the current official documentation before deploying.
Related guides
- How to Pull Live Polymarket Odds With the API
- How to Backtest Historical Data
- How to Check the Polymarket Leaderboard
Update log
- November 17, 2026: Verified current Gamma, Data API, CLOB and unified authentication documentation.