The Polymarket Data API is a useful starting point when you want repeatable public wallet research instead of manually reading a dashboard. The current v2 overview documents positions, PnL series, account activity, trades, market state and leaderboards under a shared response contract.
The documented public read endpoints do not require an API key. They do not authorize trading. This guide concerns data for Polymarket's international product; it does not establish access to a trading venue or a U.S. account.
On October 21, 2026, we checked bounded requests to /v2/status, /v2/leaderboard and /v2/positions. All returned HTTP 200. That verifies those reads at the observation time, not the completeness or accounting accuracy of every endpoint.
Use the current base URL and response envelope
The base is https://data-api.polymarket.com/v2. The API overview describes a data payload, with a pagination object on paginated routes. A client written for an older bare-array response should not assume that the v2 body itself is the list.
Start with a small request whose shape you can inspect. This Python example uses only the standard library and retrieves a two-row weekly leaderboard page:
import json
from urllib.request import urlopen
url = "https://data-api.polymarket.com/v2/leaderboard?time_period=week&limit=2"
with urlopen(url, timeout=20) as response:
page = json.load(response)
for trader in page["data"]:
print(trader["user_id"], trader.get("pnl"))
print("More pages:", page.get("pagination", {}).get("has_more"))
The endpoint and response shape were checked; running this example later can produce different wallets and figures. A leaderboard row is a research lead, not an instruction to follow its address.
Inspect one wallet's positions
For a public wallet, the documented starting route is /v2/positions?user=ADDRESS&limit=2. Replace ADDRESS with the exact trading/profile address you are investigating. Keep wallet identity consistent across data sources.
The sampled position rows included current_size, current_value, realized_pnl, unrealized_pnl, total_pnl, status, outcome identifiers and event metadata. Inspect those field names in the current schema before wiring a display or calculation.
Position states matter. Open, redeemable and closed data do not all represent the same stage in a trade's lifecycle. Do not add a current-value field to a realized-profit field without defining the accounting quantity you intend to show.
The PnL research guide explains the questions to ask before comparing accounts.
Walk cursors without changing the question
The v2 documentation specifies cursor pagination. Read pagination.next_cursor, preserve it as an opaque string and continue according to the route's contract. The documentation says offset in response metadata is not an offset request parameter.
Preserve the anchor and filters on subsequent requests. A wallet-position walk still needs its wallet and relevant filters; feed routes also need the same filters. Changing them midway can broaden or alter the result set.
Stop at the documented end rather than assuming a short page is the whole history. For a bounded exploratory script, record that you intentionally read only the first page. The first two positions are not an account audit.
Preserve units, nulls and observation times
Read the field's documented unit. Share counts, dollar amounts, token identifiers and percentages need different handling. Large token IDs should remain identifiers rather than being converted through a lossy floating-point number.
An unavailable numeric field is not zero. Likewise, a documented empty list does not prove the wallet never traded; it describes the selected query and available data. Record the request, filters, observation time and whether additional pages remain.
Use the status endpoint as one source of data-freshness context. A local cache can make a once-fresh response old even if the underlying service is healthy.
Handle errors as part of the workflow
The overview documents 400 responses for invalid requests and 429 with a Retry-After header under load. Keep error responses out of the numeric dataset, honor the retry guidance and use bounded requests instead of an unlimited loop.
If you need inspectable SQL across venues, use the Dune guide. If you only need an interface for a few wallets, Polymarket Analytics is a simpler research path. For market discovery before wallet work, see the public market-data guide.