Polymarket Data API: Public Endpoints and Response Fields
PolyLab serves basic market data publicly; custom screening and holder analysis require authenticated analysis access. The MIT-licensed Python SDK is a separate client of the hosted service.
These are the endpoints the public PolyLab app itself calls, documented so they can be used directly. Base URL is https://api.polylab.app. They return the snapshot described in Freshness and Limitations, not a live order book feed, and this page reflects the current implementation rather than a versioned stability promise.
Access and open-source client
The Python SDK is MIT-licensed client code for this hosted service, not a self-hostable backend. A source-code license does not grant access to protected endpoints.
Market listing/search with every non-smart-money filter and sort, tags and status are public. Holder lists (/api/markets/{market_id}/holders, accepting numeric market or condition IDs) and market history (/api/market-history) are public for server-selected free picks, including pinned published social picks. Smart-money filters and sorts, and holder lists and history on other markets require Pro (or the early-access cohort); unauthenticated protected requests return HTTP 401 and signed-in accounts without Pro receive HTTP 403. For guests and free accounts the server strips smart-money fields from market rows, except for the one active showcase strategy (plan.showcase_strategy — usually Coinflip Club, with Newsmaker then Longshot as fallbacks when it has fewer than 3 qualifying markets in the current snapshot), which the server resolves from its own configuration via strategy=<id>. Pro-gated 401/403 responses carry {detail, upgrade: true, feature} where feature is smart_money, holders, market_history or agent. Non-Pro market rows are flagged analysis_locked; /api/discovery accepts every strategy, and showcase rows requested with strategy=<showcase id> on /api/markets or /api/market-outcome are tagged showcase_strategy. GET /api/access reports the caller's plan (id: guest, free, pro or early_access; watch_limit 0, 3 or null for unlimited; showcase_strategy; grace, grace_until; price_usd 29, anchor_price_usd 49, trial_days 7) and capabilities (smart_money, holders, market_history, smart_money_alerts, agent; advanced_filters and full_screener are true for everyone). GET /api/billing/status includes grace_until. App Pro is USD 29/month (early-access price, normally USD 49) after a 7-day card-required trial; existing early-access accounts keep Pro free. See Access Model. A separately sold API plan is proposed, not currently available.
SDK compatibility note (2026-09-29): published client 0.1.0 does not support authentication. Its README examples using custom filters or holder analysis therefore return 401 against the current service. Basic public calls still work. SDK examples and authentication support need a coordinated update; do not assume all documented SDK calls work without an account.
GET /api/homepage-bootstrap
Returns the precomputed homepage payload used for the marketing homepage first paint.
Important response fields include:
| Field | Meaning |
|---|---|
generated_at | Snapshot generation timestamp |
market_last_updated | Latest snapshot_at used when building the snapshot |
smart_money_last_updated | Latest smart-money refresh timestamp available to the snapshot |
cache_max_age_ms | Suggested client-side cache TTL for local bootstrap hydration |
spotlight_markets | Ready-to-render smart-money spotlight cards |
playbook_previews | Per-playbook preview rows keyed by preset id |
GET /api/app-bootstrap
Returns the precomputed first-paint payload for /app.
Query params:
| Param | Meaning |
|---|---|
view | scanner or smart |
preset | Optional preset id such as smart_money_edge |
Important response fields include:
| Field | Meaning |
|---|---|
generated_at | Snapshot generation timestamp |
market_last_updated | Latest snapshot_at used when building the snapshot |
smart_money_last_updated | Latest smart-money refresh timestamp available to the snapshot |
view | Resolved app view after preset application |
active_preset_id | Resolved preset id, or null for default bootstraps |
filters | Resolved initial filter state for the first paint |
markets | Initial market rows rendered before live revalidation |
tags | Initial tag stats used by include/exclude autocomplete |
cache_key | Storage key used by the frontend for bootstrap caching |
GET /api/tags
Returns tag statistics used by the include/exclude tag UI.
| Field | Meaning |
|---|---|
tag_label | Tag label |
count | Number of occurrences in the current snapshot |
GET /api/status
Returns the last known refresh timestamps used by the UI header.
| Field | Meaning |
|---|---|
last_updated | Latest snapshot_at in active_market_outcomes |
smart_money_last_updated | Latest last_updated_at in market_smart_money_stats |
GET /api/markets
Returns the main scanner rows and accepts the query parameters documented in Scanner Query and Filter Contract.
Important response fields include:
| Field | Meaning |
|---|---|
market_id | Market identifier |
condition_id | Condition identifier used for holders lookup |
question | Market question |
outcome_name | Row outcome |
price | Stored outcome price |
apr | Computed APR |
spread | Stored spread |
volume_usd | Stored volume |
liquidity_usd | Stored liquidity |
start_date | Start date |
end_date | End date |
category | Primary category from tags |
icon_url | Event image/icon |
yes_profitable_count | Sampled profitable YES wallets |
yes_losing_count | Sampled losing YES wallets |
yes_total | Total sampled YES holder rows |
no_profitable_count | Sampled profitable NO wallets |
no_losing_count | Sampled losing NO wallets |
no_total | Total sampled NO holder rows |
GET /api/markets/{market_id}/holders
Returns holder rows for the condition represented by the selected market detail view.
| Field | Meaning |
|---|---|
wallet_address | Normalized holder wallet |
position_size | Current sampled position size |
outcome_index | YES / NO side index |
total_pnl | Joined wallet PnL if available |
alias | Optional wallet alias |
wallet_tag | Optional operational tag such as SYSTEM |
Contract stability
The homepage and initial /app load are intentionally snapshot-backed for speed. Live /api/markets remains the source for interactive filtering, pagination, and silent revalidation after first paint.
This reference documents what the current public app uses today. It should be read as a current implementation contract, not a long-term versioned API promise.
Exact shared market links
GET /api/market-outcome?market_id=3762773&outcome_index=0 resolves one outcome directly, including expired rows still in the dataset. Provide exactly one of market_id or condition_id, and an explicit outcome_index. The existing condition-ID form is unchanged. Missing/ambiguous identity returns 422; missing data returns 404, without a text-search fallback. Guest responses retain the basic-field projection; protected metrics and holders still require server-verified analysis access.
Shared web links use /app?mode=market&market_id=…&outcome_index=…, with no search query. The app opens a single-market view and skips category/status/list initialization. Legacy app links containing a market/condition ID use the same direct path. This is a web route and an additive API lookup option; existing SDK calls and response schemas are unchanged. Paid API authentication/documentation coordination remains pending before that product launches.
Related market discovery
GET /api/related-markets?condition_id=<id>&offset=0&limit=20 returns {markets, has_more, next_offset}. Limits are 1–40 and offsets 0–1000. For dated sports fixtures, the root event and its subevents (such as exact score and halftime result) share relationship: "same_event". Other fixtures involving either team are excluded. For other markets, rows with the same upstream event slug come first. Separately ranked text matches use relationship: "similar" and require a matching numbered UFC event or at least two meaningful shared words. The selected market is excluded. Unknown condition IDs return 404. Each market has the same guest/free/Pro field projection as /api/market-outcome; relationship is the only additional field. The response is private and not stored. This additive endpoint has no SDK method in the published Python client yet; existing SDK methods and permissions are unchanged.