Polymarket

Polymarket Data API v2

The Polymarket Data API: wallet portfolios, trade and activity feeds, market state and ranked boards. Conventions every endpoint shares Envelope: every…

Finance & banking#finance

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The Polymarket Data API: wallet portfolios, trade and activity feeds, market state and ranked boards.

Conventions every endpoint shares

  • Envelope: every response wraps its payload in data (paged routes add pagination). A documented miss is data: null or an empty list, never an error.
  • Pagination is cursor-only: follow pagination.next_cursor until null; has_more is exact, and there is no offset query parameter (sending one is a 400). Cursors are signed, typed per endpoint, and opaque. The feeds (trades, activity, combo activity) are keyset walks, stable across concurrent writes; the boards, holders and most combo-position sorts are offset walks behind the opaque token, so a page taken across a data refresh can skip or repeat rows. Where a cursor binds its cohort (the boards, positions, combo positions), resuming bare is fine, restating the same values is fine, and contradicting them is a 400. The trades/activity feed cursors carry only the seek anchor and page size (plus the sort direction on activity): re-send identical filters on every page, because changing one mid-walk re-anchors silently.
  • Rate limiting: 429 with Retry-After is the busy signal for heavy queries. A heavy query may first be queued briefly for a capacity slot; the 429 arrives only if that short wait ends unserved. Each caller also has a per-client request allowance, and bursts past it get the same 429 with Retry-After sized to the remaining wait. Retry after the given delay. A request that could not get a database connection within its budget is NOT a 429: it is a 503 request_timeout with Retry-After, because the shortage is on the server side, not in the caller's rate.
  • Identifiers: condition (aliases condition_id, conditionId) is the unified query key for on-chain 0x condition ids; market_id fields carry Gamma's own market ids; event_id takes Gamma event ids; token_id is the CLOB asset id (the key on /v2/prices-history).
  • Params accept both snake_case and camelCase spellings.
  • Units: bare volume/size values are shares; _usdc suffixed fields are USD; taker_ prefixed volumes are one-side.
  • Sentinels: outcome_index: 999 means the outcome could not be labeled; a missing or null numeric field means unavailable, never zero.
  • Windows on /v2/trades?user= and /v2/activity: an omitted or 0 start floors to three years back (start=1 asks for full history); an omitted or 0 end is now plus one day. The other /v2/trades shapes ignore start/end: condition/event_id serve a fixed three-year window and the bare feed serves the rolling current-plus-previous month. Other windowed routes treat omitted/0 bounds as unbounded; each documents its own rule. /v2/prices-history is the strict one, where a 0 bound is a 400.
  • Errors: every unsuccessful response is JSON with a human-readable error, stable code, retryable flag, and opaque trace_id; validation failures may also name parameter. Codes map to statuses as follows: invalid_request = 400, not_found = 404, method_not_allowed = 405, rate_limited = 429, internal = 500, and both request_timeout (the request deadline, the datastore's statement timeout, or the connection pool's acquire budget) and dependency_unavailable = 503. A 429 or 503 that is worth retrying carries Retry-After in seconds. Every response, successful or not, echoes the same id in the x-trace-id header; supply it when reporting a failure so operators can correlate it with telemetry.
  • Auth: none. All data routes are public; no API key or token is required.

Endpoints 21

wallet

  • GETGet wallet approvals/v2/approvalsPolygon token/operator approval state for one wallet. ?user= must be an EVM address. The complete served catalog is returned in canonical order under { data…
  • GETList positions for a user or market/v2/positionsA keyset page of positions in the standard { data, pagination } envelope. One route serves a user's open book, their closed book (status=CLOSED), and a…
  • GETList combo positions/v2/positions/combosCombo positions for a user, in the standard { data, pagination } envelope. Sorts: FIRST_ENTRY (default) | ENTRY_COST (+ CURRENT_VALUE alias) | UPDATED, each…
  • GETGet a user's PnL series/v2/user-pnlComplete cumulative native-PnL atoms and compositions.
  • GETGet a user's profile stats/v2/user-statsThe profile card for one wallet in a single call. ?user= is required. Returns { data: { trades, biggest_win, views, join_date, all_time_pnl } }, or { data:…
  • GETGet a user's trading volume/v2/user-volumeOne wallet's trading volume over a window, in both units side by side. ?user= is required. ?start= / ?end= are epoch seconds, inclusive and optional: omitted…
  • GETGet portfolio value/v2/valueThe user's portfolio value: single-market holdings marked to market plus unresolved combo positions at cost basis. ?user= is required (400 otherwise).…

feeds

  • GETList account activity/v2/activityKeyset-paginated activity feed (trades, splits, merges, redeems, …) in the standard { data, pagination } envelope. Ordering is (block_timestamp, sequence_id),…
  • GETList combo activity/v2/activity/combosKeyset-paginated combo lifecycle + redemption feed for a user, in the standard { data, pagination } envelope. Pass ?cursor= from a prior response's…
  • GETList trades/v2/tradesKeyset-paginated trade feed in the standard { data, pagination } envelope. Pass ?cursor= from a prior response's next_cursor to fetch the next page; it…

markets

  • GETList a market's top holders/v2/holdersTop holders of a market, netted per user and grouped by outcome token. ?condition= (CSV of condition_id) is required (400 otherwise). ?limit= (default 100,…
  • GETGet live volume for an event/v2/live-volumeCumulative one-side (taker) volume per market. Pass ?event_id= as a comma-separated list of integer event ids (aliases id / eventId); every market under those…
  • GETGet open interest/v2/oiPriced gross open interest per market. Pass ?condition= as a comma-separated list of condition ids (aliases condition_id / conditionId, matching the feeds);…
  • GETGet a token's price history/v2/prices-historyThe price-history series for one outcome token, or a single point-in-time observation. Three window forms, exactly one per request: start (with optional end),…
  • GETGet resolution state/v2/resolutionsComplete resolution state by one selector family. Supply exactly one of question_id, condition, or event_id. Condition and event selectors accept…
  • GETLook up tokens/v2/tokensResolves token ids, or the tokens of conditions, to their condition, module, outcome, market, event and neg-risk question index in one call. Exactly one…

boards

  • GETList the biggest wins/v2/biggest-winnersThe biggest single winning positions. One row per winning POSITION, not per user: pnl is final_value - initial_value for that position, and the window…
  • GETGet the builders leaderboard/v2/builders/leaderboardThe ranked board of builders by volume. ?time_period= is day (default), week, month or all and selects the window; one row per builder in it. Deeper pages…
  • GETGet builder volume over time/v2/builders/volumeThe per-builder volume time series. ?interval= is the bucket width, not a window: day (default) returns every day on record bucketed daily, week and month…
  • GETGet the trader leaderboard/v2/leaderboardThe ranked board of realized PnL, combos included. ?time_period= is day (default), week, month or all; ?category= is overall (default) or a market category;…

service

  • GETGet data freshness/v2/statusHow fresh the data behind this API is. /readyz answers whether this pod can reach its datastore; this answers how far behind chain head what you are reading…

API details

Base URL
https://data-api.polymarket.com
https://data-api-rs.stage.pmd.use1.polymarket.sh
Authentication
None declared in the description
Operations
21 operations on 21 pathsGET 21
Main resources
wallet 7markets 6boards 4feeds 3service 1
Response formats
application/json
Description format
OpenAPI 3.1.0, API version 0.1.0

How to test the Polymarket Data API v2 in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Polymarket Data API v2 collection, without the publisher's secrets.
  3. Add your credentialsOpen the collection's variables or an environment and enter your API key or token, if the API needs one.
  4. Send a requestPick an endpoint, for example “Get wallet approvals” (GET /v2/approvals), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Polymarket Data API v2?

The Polymarket Data API: wallet portfolios, trade and activity feeds, market state and ranked boards. Conventions every endpoint shares Envelope: every… It is listed under Finance & banking and has 21 endpoints.

Who publishes the Polymarket Data API v2?

It is listed from Polymarket's public API description (an OpenAPI document), not published by Polymarket on Swastik Codes. Anyone who controls polymarket.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Polymarket Data API v2?

Its description lists 2 base URLs: https://data-api.polymarket.com, https://data-api-rs.stage.pmd.use1.polymarket.sh. The first is the usual one; the others are typically sandbox or regional servers.

How do I authenticate with the Polymarket Data API v2?

Its OpenAPI description does not declare an authentication scheme. Some endpoints may be open; check the provider's documentation before relying on that.

How many endpoints does the Polymarket Data API v2 have?

21 operations on 21 paths (21 GET). The largest groups are wallet, markets, boards, feeds.

Is forking the Polymarket Data API v2 free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.