Skip to content
scrapeatlas.Dashboard

Prediction markets

Polymarket API

Search Polymarket and read events, markets, order books, price history, trades, comments, trader profiles, positions, activity, holders and the leaderboard.

13 endpointsx-api-key

Thirteen authenticated endpoints read Polymarket’s public market, trading and profile data: events and markets with outcome prices, live order books, price history, trades, comment threads, trader profiles, positions and activity, top holders and leaderboards.

API availability: Available

Base URL · local workerhttp://localhost:3052Public API: https://api.scrapeatlas.com.
Authenticationx-api-keyCustomer key from your account. See Authentication.

Endpoints

GET/v1/polymarket/search

Search Polymarket

Search Polymarket events by keyword, with matching tags and trader profiles when you ask for them. Each event carries its markets with outcomes and prices. Page through results with page.

Reference
GET/v1/polymarket/events

List Polymarket events

List Polymarket events with market summaries. Filter by tag, open or closed status, featured, volume, liquidity and start or end date; sort by volume, liquidity, open interest, competitiveness or date; and page with the returned cursor.

Reference
GET/v1/polymarket/event

Get a Polymarket event

Retrieve a Polymarket event by slug, ID or URL with its rules, totals, tags, series and every market with outcomes, prices, token IDs, volume and liquidity.

Reference
GET/v1/polymarket/market

Get a Polymarket market

Retrieve one Polymarket market by slug, ID, condition ID or URL: question, rules, outcomes with prices and token IDs, quotes, volume, liquidity, price changes and its event.

Reference
GET/v1/polymarket/orderbook

Get a Polymarket order book

Retrieve the live order book for one outcome token: every bid and ask level as the CLOB serves it, the best bid and ask, tick size, minimum order size and last trade price.

Reference
GET/v1/polymarket/price-history

Get Polymarket price history

Retrieve the price history of one outcome token as timestamped points. Choose a relative interval or a start and end time, set the bucket width, and page with the returned cursor.

Reference
GET/v1/polymarket/trades

List Polymarket trades

List recent trades for a market, an event or a trader, newest first: side, size, price, outcome, market and the trader’s public profile. Filter by side and minimum size, include maker fills, set a time window for a trader, and page with the returned cursor.

Reference
GET/v1/polymarket/comments

List Polymarket comments

List the comment thread of a Polymarket event or series, newest or oldest first, with replies and commenter profiles. An event in a recurring series, or in any series when the event has no comments of its own, returns the series discussion, as the event page shows it; other events return their own thread. Optionally keep only comments from position holders.

Reference
GET/v1/polymarket/profile

Get a Polymarket trader profile

Retrieve a Polymarket trader by @handle, wallet or profile URL: public profile, trade count, biggest win, views, join date, all-time PnL breakdown, current portfolio value and all-time leaderboard ranks.

Reference
GET/v1/polymarket/user-positions

List a Polymarket trader’s positions

List a trader’s positions with size, average and current price, value, cost and realized and unrealized PnL. Choose open, closed, redeemable, redeemable_lost or mergeable positions, sort them, and page with the returned cursor.

Reference
GET/v1/polymarket/user-activity

List a Polymarket trader’s activity

List a trader’s on-chain activity, newest first: trades, splits, merges, redemptions, rewards, conversions and tips. Filter by type, side and time window, and page with the returned cursor.

Reference
GET/v1/polymarket/holders

List Polymarket market holders

List the largest holders of each outcome of a market with their share balances and public profiles. Set a minimum balance and page with the returned cursor.

Reference
GET/v1/polymarket/leaderboard

Get the Polymarket leaderboard

Read the Polymarket trader leaderboard by profit or volume for a day, week, month or all time, overall or in one category, and page with the returned cursor.

Reference

Quick start

Create an API key on your account page, then call the public API. Values below are placeholders.

Terminal
curl "https://api.scrapeatlas.com/v1/polymarket/search?query=bitcoin&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

Coverage & limits

  • Independent, stateless worker: four concurrent operations with a queue of 16 waiting up to 8 seconds; 25-second total deadline including the queue; at most nine upstream HTTP requests per operation, including one shared retry after a network failure or 5xx. No automatic retry for HTTP 429 or challenges.
  • Fixed public HTTPS origins only: gamma-api.polymarket.com, data-api.polymarket.com, clob.polymarket.com, and polymarket.com for @handle profile pages. Caller input becomes a validated path segment or query value, never a destination. No login, cookies, browser, outbound link visits, media downloads or result storage. The service API key is never forwarded.
  • Byte limits per source response: 16 MiB from Gamma, 4 MiB from the Data API and the CLOB, 2 MiB for a profile page; 24 MiB per operation. JSON depth 64 and 2,500,000 parsed nodes.
  • Page sizes: search 1–50 results per type and pages 1–100; events 1–50; comments 1–100 top-level comments with their replies, at most 2,000 rows; trades, positions and activity 1–500; holders 1–100 per outcome; leaderboard 1–500; price history 1–5,000 points. Order books return at most 1,000 levels per side and events at most 1,000 markets.
  • Event listings return market summaries; the event and market endpoints return the full market projection. Event metadata, team and sport objects, reward and fee schedules, and per-comment reaction lists are not returned; comments keep the source reaction count.
  • Cursors come from the source and bind the parameters they were issued with: send the same parameters with nextCursor. Rows the source repeats within a page are returned once.
  • A market, event or token given by ID that returns an empty page is checked against the source and answers not_found when it does not exist. For a wallet, an empty page or a cursor the source rejects is checked the same way on every page, and an owner wallet is replaced by its trading wallet, so the owner wallet can be sent with each nextCursor.
  • A bounded in-process map of handle to trading wallet (5,000 entries, 6-hour lifetime) saves the profile page read on repeat lookups; a miss reads the page again.
Error codes
11
HTTPfailure.codeMeaning
200partialUsable data with level_limit, point_limit, market_limit, comment_row_limit or *_unavailable warnings.
400invalid_requestMissing, duplicate, conflicting, unsafe or unsupported parameters, a URL outside polymarket.com, or a cursor the source rejects.
401unauthorizedMissing or invalid worker API key.
404not_foundUnknown event, market, outcome, token, series, handle or wallet.
429upstream_rate_limitedPolymarket throttled the request; no automatic retry.
502upstream_challengedPolymarket rejected the request or answered with a challenge page.
502unsupported_pageMalformed, mismatched or non-JSON source data, or a profile page without its wallet address.
502response_too_large payload_too_complexResponse exceeded byte or parsing limits.
502unsafe_redirect request_limit upstream_errorBounded source retrieval could not complete.
503busyAll worker slots and queue places are occupied.
504timeoutTotal request deadline expired.