> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/polymarket>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/polymarket.mdx>

---

# Polymarket API. Prediction markets as JSON.

Events, markets, order books, prices, price history, trades and trader profiles from Polymarket. Paginate with a cursor, branch on lookupStatus, and bill from meta.creditsCharged.

- Events and markets
- Books, prices and trades
- Perps and US exchange

Social Fetch exposes 42 Polymarket routes under `/v1/polymarket`. The event and market routes cover discovery: `GET /v1/polymarket/events` lists events with their markets' headline numbers, `GET /v1/polymarket/events/{eventIdOrSlug}` returns one event with full market records, `GET /v1/polymarket/markets` lists markets, `GET /v1/polymarket/markets/batch` looks up to 100 condition ids or token ids at once, and `GET /v1/polymarket/markets/{marketIdSlugOrConditionId}` returns one market with outcomes, prices, fees and resolution rules.

Trading data sits alongside it. `GET /v1/polymarket/books` returns order books for up to 150 outcome tokens, `GET /v1/polymarket/prices` returns best bid, best ask, midpoint, spread and last trade for the same batch size, `GET /v1/polymarket/tokens/{tokenId}/price-history` returns a bucketed series, and `GET /v1/polymarket/trades` and `GET /v1/polymarket/markets/{conditionId}/trades` page the public tape. `GET /v1/polymarket/markets/{conditionId}/holders` lists the largest holders per outcome, while `GET /v1/polymarket/markets/{conditionId}/stats` gives open interest and taker volume.

The catalog routes are `tags`, `series`, `sports` and `teams`. `GET /v1/polymarket/search` searches events, tags and profiles in one call, and `GET /v1/polymarket/movers` returns the markets that moved most. People routes take a wallet: profile and stats, open or closed positions, activity, a PnL breakdown over time, the leaderboard, and the biggest winning positions. A username works on `GET /v1/polymarket/users/{walletOrUsername}` and costs one extra lookup to resolve.

Perps and the US exchange are separate products with their own ids and rules, kept under `/perps/` and `/us/` so route names cannot be confused. Every response uses the `{ data, meta }` envelope. Lookups carry `data.lookupStatus`, lists carry `data.page`, and `meta.creditsCharged` is the billing source of truth. Nothing here places, signs or cancels an order.

## What you can get

- Events with every market they hold, and one event with full market records, outcomes and prices.
- Order books, midpoint prices and price history for outcome token ids.
- Trade tape by market or wallet, plus holders, open interest and taker volume.
- Tags, series, leagues, teams, search across events, tags and profiles, and the biggest movers.
- Wallet profiles, positions, activity, stats, PnL history, leaderboards and biggest wins.
- Separate Perps and Polymarket US route groups under `/perps/` and `/us/`.

## Polymarket endpoints

| Endpoint | Request | Credits | Docs |
| --- | --- | --- | --- |
| Events | GET /v1/polymarket/events | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/events/get) |
| Event | GET /v1/polymarket/events/{eventIdOrSlug} | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/events/eventidorslug/get) |
| Event insights | GET /v1/polymarket/events/{eventIdOrSlug}/insights | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/events/eventidorslug/insights/get) |
| Event annotations | GET /v1/polymarket/events/{eventIdOrSlug}/annotations | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/events/eventidorslug/annotations/get) |
| Event comments | GET /v1/polymarket/events/{eventId}/comments | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/events/eventid/comments/get) |
| Markets | GET /v1/polymarket/markets | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/markets/get) |
| Markets batch | GET /v1/polymarket/markets/batch | 1 credit per market id Up to 100 market ids per request Max 100 credits Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/markets/batch/get) |
| Market | GET /v1/polymarket/markets/{marketIdSlugOrConditionId} | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/markets/marketidslugorconditionid/get) |
| Market resolution | GET /v1/polymarket/markets/{conditionId}/resolution | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/markets/conditionid/resolution/get) |
| Market stats | GET /v1/polymarket/markets/{conditionId}/stats | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/markets/conditionid/stats/get) |
| Market holders | GET /v1/polymarket/markets/{conditionId}/holders | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/markets/conditionid/holders/get) |
| Market trades | GET /v1/polymarket/markets/{conditionId}/trades | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/markets/conditionid/trades/get) |
| Order books | GET /v1/polymarket/books | 1 credit per token id Up to 150 token ids per request Max 150 credits Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/books/get) |
| Prices | GET /v1/polymarket/prices | 1 credit per token id Up to 150 token ids per request Max 150 credits Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/prices/get) |
| Price history | GET /v1/polymarket/tokens/{tokenId}/price-history | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/tokens/tokenid/price-history/get) |
| Trades | GET /v1/polymarket/trades | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/trades/get) |
| Tags | GET /v1/polymarket/tags | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/tags/get) |
| Tag | GET /v1/polymarket/tags/{idOrSlug} | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/tags/idorslug/get) |
| Series | GET /v1/polymarket/series | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/series/get) |
| Series detail | GET /v1/polymarket/series/{idOrSlug} | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/series/idorslug/get) |
| Sports | GET /v1/polymarket/sports | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/sports/get) |
| Teams | GET /v1/polymarket/teams | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/teams/get) |
| Search | GET /v1/polymarket/search | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/search/get) |
| Movers | GET /v1/polymarket/movers | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/movers/get) |
| User | GET /v1/polymarket/users/{walletOrUsername} | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/users/walletorusername/get) |
| Users | GET /v1/polymarket/users | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/users/get) |
| User positions | GET /v1/polymarket/users/{wallet}/positions | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/users/wallet/positions/get) |
| User activity | GET /v1/polymarket/users/{wallet}/activity | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/users/wallet/activity/get) |
| User stats | GET /v1/polymarket/users/{wallet}/stats | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/users/wallet/stats/get) |
| User profit | GET /v1/polymarket/users/{wallet}/pnl | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/users/wallet/pnl/get) |
| Leaderboard | GET /v1/polymarket/leaderboard | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/leaderboard/get) |
| Biggest wins | GET /v1/polymarket/biggest-wins | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/biggest-wins/get) |
| Perps instruments | GET /v1/polymarket/perps/instruments | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/perps/instruments/get) |
| Perps tickers | GET /v1/polymarket/perps/tickers | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/perps/tickers/get) |
| Perps candles | GET /v1/polymarket/perps/instruments/{instrumentId}/klines | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/perps/instruments/instrumentid/klines/get) |
| Perps order book | GET /v1/polymarket/perps/instruments/{instrumentId}/book | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/perps/instruments/instrumentid/book/get) |
| Perps trades | GET /v1/polymarket/perps/instruments/{instrumentId}/trades | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/perps/instruments/instrumentid/trades/get) |
| Perps leaderboard | GET /v1/polymarket/perps/leaderboard | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/perps/leaderboard/get) |
| US events | GET /v1/polymarket/us/events | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/us/events/get) |
| US event | GET /v1/polymarket/us/events/{idOrSlug} | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/us/events/idorslug/get) |
| US market | GET /v1/polymarket/us/markets/{idOrSlug} | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/us/markets/idorslug/get) |
| US series | GET /v1/polymarket/us/series | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/us/series/get) |

## How to start

1. **Create an API key.** Sign up at Social Fetch and copy a key (`sfk_…`). New accounts get 100 free credits, enough to read events, markets, books and a wallet profile before choosing a plan.
2. **Start from an event or market.** Call `GET /v1/polymarket/events/30829` for the 2028 Democratic nominee event. Each entry in `data.event.markets` carries `conditionId` and `outcomes[].tokenId`; pass those to the market, books, prices, trades and holders routes. Send `x-api-key` on every request.
3. **Page and branch.** Check `data.lookupStatus` before storing a row (`found` or `not_found`), keep the same filters and pass `data.page.nextCursor` while `data.page.hasMore` is true, and bill from `meta.creditsCharged`.

## Pricing

Most Polymarket routes charge a flat credit amount per completed request, shown on every endpoint page. The batch routes (`books`, `prices`, `markets/batch`) charge one credit per requested token or market id. Each page of a list is its own request. Credits never expire on pay-as-you-go packs, and `meta.creditsCharged` on every response is the billing source of truth.

## Compared with the official API

Polymarket publishes market data through several developer surfaces, each with its own hosts, identifiers and response shapes: numeric ids and slugs for events and markets, condition ids and token ids for trading data, and separate Perps and US exchange products. Social Fetch gives one envelope across all of them: `data.lookupStatus`, opaque cursors, decimal money as a number or exact string, typed `not_found` answers, and route groups that keep the two exchanges apart.

## FAQ

### Is there a Polymarket API for events and markets?

Yes. Social Fetch has 42 Polymarket routes under /v1/polymarket: events, event lookup, insights, annotations, comments, markets, market lookup by id, slug or condition id, batch market lookup, order books, prices, price history, trades, holders, tags, series, sports, teams, search, movers, user profiles, positions, activity, stats, PnL, leaderboards, biggest wins, Perps and Polymarket US. Authenticate with your Social Fetch API key in x-api-key.

### How do I go from an event to an order book?

Call GET /v1/polymarket/events/{eventIdOrSlug}. On data.lookupStatus: found, each market in data.event.markets has a conditionId and an outcomes array. Each outcome has a tokenId. Pass up to 150 token ids to GET /v1/polymarket/books (query tokenIds, comma separated or repeated) or to GET /v1/polymarket/prices. The market endpoint returns the full record, including fees and resolution rules.

### What does lookupStatus mean?

found means the object or list was returned. not_found means no event, market, tag, series, token or wallet matched. HTTP 200 only means the request finished, so branch on data.lookupStatus before writing. Some lists describe an empty result as found with an empty array, such as a market with no trades yet.

### How do cursors work?

Every list response has data.page with hasMore and nextCursor. Pass data.page.nextCursor as the cursor query parameter and keep the other filters unchanged. The cursor is an opaque string tied to one operation; it is not a timestamp or an offset you can build yourself. When hasMore is false, stop.

### How are batch routes billed?

GET /v1/polymarket/books and GET /v1/polymarket/prices charge one credit per token id, with a maximum of 150 ids per request. GET /v1/polymarket/markets/batch charges one credit per condition id or token id, with a maximum of 100 ids. The batch response summary reports requested, found and notFound. Confirm the charge with meta.creditsCharged.

### How far back can price history go?

Use interval=1h, 6h, 1d, 1w, 1m, max or all for a preset range, or pass from and to as unix seconds with bucketSeconds between 60 and 86400. A custom from and to window spans at most 15 days. Points come oldest first, and each point carries at, price and bucketSeconds. Walk a longer history in several 15-day windows.

### Can I read a wallet's positions and profit?

Use GET /v1/polymarket/users/{wallet}/positions for open, closed, redeemable or mergeable positions, GET /v1/polymarket/users/{wallet}/activity for the action history, GET /v1/polymarket/users/{wallet}/stats for headline figures and a PnL breakdown, and GET /v1/polymarket/users/{wallet}/pnl for a series over time. The leaderboard and biggest wins routes rank wallets across the market. A wallet that never traded returns an empty list or not_found, not an error.

### Are Perps and Polymarket US the same market data?

No. Perpetual futures live under /v1/polymarket/perps (instruments, tickers, klines, book, trades, leaderboard), and the US exchange lives under /v1/polymarket/us (events, event, market, series). They have their own ids, fields and rules, so the route groups keep them separate. Polymarket US is a different exchange from the main Polymarket event market.

### Do comments, insights and annotations cover every event?

Comments are keyed by numeric event id and return an empty list when an event has none; an id that does not exist returns not_found. Insights are machine-written context and can be null for an event that has none. Annotations explain dated price moves and only exist for events with large moves, so an empty array is normal. All three are read-only and never trade.

### Does this place trades or connect a wallet?

No. Every Polymarket route on Social Fetch is read-only. There is no signing, order placement, cancellation, deposit or wallet connection. The routes return public market data, public trade and holder rows, and public wallet profiles and positions.

## Related

- [Polymarket Events API](https://www.socialfetch.dev/platforms/polymarket/events): List events with their markets and headline numbers (`GET /v1/polymarket/events`).
- [Polymarket Market API](https://www.socialfetch.dev/platforms/polymarket/markets-marketidslugorconditionid): One market by id, slug or condition id, with outcomes, fees and rules (`GET /v1/polymarket/markets/{marketIdSlugOrConditionId}`).
- [Polymarket Order Book API](https://www.socialfetch.dev/platforms/polymarket/books): Bids and asks for up to 150 outcome tokens in one request (`GET /v1/polymarket/books`).
- [Polymarket Price History API](https://www.socialfetch.dev/platforms/polymarket/tokens-tokenid-price-history): Bucketed price points with interval or from/to controls (`GET /v1/polymarket/tokens/{tokenId}/price-history`).
- [Polymarket Positions API](https://www.socialfetch.dev/platforms/polymarket/users-wallet-positions): A wallet's open, closed and redeemable positions with cost and PnL (`GET /v1/polymarket/users/{wallet}/positions`).
- [Ask in plain English](https://www.socialfetch.dev/ask): Route a natural-language prediction market question to the matching Polymarket operation.