Start a Polymarket US market-data project with the US retail public gateway. It exposes market and event information without an API key. Account operations and trading use a separate authenticated API. International Polymarket wallet analytics use another product and documentation family.
This guide follows the public retail reference, checked October 22, 2026. Our single bounded request returned HTTP 200 and one market row without credentials. We did not connect an account, install an SDK, retrieve a private portfolio or submit an order.
Choose the documentation family first
The Polymarket US introduction identifies gateway.polymarket.us for public market data and api.polymarket.us for authenticated account operations. Keep the host and product beside every saved request.
Polymarket US also has documentation for exchange and institutional integrations. The API overview distinguishes retail app users from participant, broker and clearing workflows. Authentication, account identifiers and streaming protocols depend on that family. An institutional access-token example is not a replacement for the retail public request below.
If you are comparing trading platforms rather than building a reader, start with Kalshi, Polymarket US and international Polymarket. A successful public data request does not establish account or trading eligibility.
Make one small public request
The Get Markets reference documents GET /v1/markets and filters including limit, active and closed. This request selects one page of up to one market marked active and not closed:
curl --fail --show-error --max-time 25 \
'https://gateway.polymarket.us/v1/markets?limit=1&active=true&closed=false' \
--output polymarket-us-markets.json
The example uses shell line continuation for macOS/Linux. In Windows PowerShell, use curl.exe with the quoted URL and options on one line. It needs no authorization header or wallet connection. Save the exact URL and your UTC observation time beside the JSON so you can explain what you requested later.
On October 22 at 01:39 UTC, our bounded HTTP read of that exact URL returned one row in a markets array, in a 4,273-byte response. That observation verifies this read at that time. It does not establish every market's availability, a continuously working feed or the accuracy of every documented field. An empty array on a later successful request is also possible; keep it distinct from a request failure.
Inspect the REST shape before mapping fields
The public response is an object containing markets. In the row we observed, id was a string; active and closed were booleans; marketSides was an array; and bestBidQuote and bestAskQuote were objects. assetPriceTerms was null. Preserve identifiers as opaque values and unavailable fields as unavailable.
The TypeScript markets reference presents an SDK-facing field summary. Read that together with the raw REST reference and your actual response. A display model may need an adapter; copying a bestBid number from an SDK table into a parser expecting a raw bestBidQuote object can hide a mismatch.
This small Python inspection reads only the file you already downloaded. It makes no network call and performs no trading calculation:
import json
from decimal import Decimal
from pathlib import Path
payload = json.loads(
Path("polymarket-us-markets.json").read_text(encoding="utf-8"),
parse_float=Decimal,
)
markets = payload.get("markets")
if not isinstance(markets, list) or len(markets) > 1:
raise ValueError("Expected the bounded one-market response")
for market in markets:
if not isinstance(market, dict):
raise ValueError("Expected a market object")
fields = ("id", "slug", "question", "active", "closed", "status")
print({field: market.get(field) for field in fields})
Keep the original JSON as the source record. Parsing decimal numbers explicitly avoids introducing binary floating-point rounding in later analysis, but it does not supply a missing unit or validate a price's economic meaning. Keep a quote's currency and source time when you map it, and do not turn a missing bid into a zero-price opportunity.
Treat a market list as a catalog snapshot
A market row can help a reader discover the question, status and identifiers. An active flag or a displayed quote does not guarantee that a particular account can execute a particular size at that price. Read the contract rules and use the documented order-book/BBO routes when the research question concerns available prices and size.
This guide tested the list request, not those other routes or streaming connections. Use the order-book walkthrough and depth simulator to understand why a headline price and an average fill are different observations. Neither tool is a live Polymarket US order preview.
The US retail list reference documents limit and offset. Preserve its own filter and pagination contract when expanding a reader. The international Data API v2 wallet guide has a different cursor contract. Label each dataset with its product instead of combining two hosts' pages into one purported complete export.
Stop cleanly when a request fails
Inspect an HTTP failure before changing the request. A malformed filter, an access denial, a rate limit and a temporary service failure have different causes. Preserve the status and observation time, and mark the sample unavailable. Do not substitute yesterday's data without showing its age, fill an error with zeros or automatically add account keys to a public-reader problem.
The example is one on-demand read with a timeout, not a polling service or a complete-market crawler. A production collector needs current rate-limit guidance, bounded pages, cancellation, backoff appropriate to the published rules, coverage markers and refresh monitoring. Those are separate from proving that one request returned a JSON object.
Keep account keys out of the display project
Polymarket US's authentication guide explains the app-account, identity-verification and developer-key workflow for authenticated access. Portfolio reads, trading and the documented authenticated WebSocket connections belong to that workflow. They are unnecessary for the single public request here.
When a project later needs account data, define the specific permissions and trusted execution environment before adding a secret. A public client bundle or article comment is not a place for signing material. This guide does not activate or verify that account-access path.
For a parallel public-data exercise on another venue, use the Kalshi market-reader tutorial. For international wallet PnL, use the wallet review workflow. The tools directory separates these jobs by platform, task and experience.