Polymarket API endpoints: choose the host and identifier

By PredictionToolkit

Gamma, CLOB and Data API answer different questions. This guide separates documented requests from the source-recorded public checks; these services are operated by their providers, not this directory.

Start with the task

• Discovery: https://gamma-api.polymarket.com GET /markets/keyset?closed=false&limit=1.
• Outcome book: https://clob.polymarket.com GET /book?token_id={outcome token ID}.
• Trader ranking: https://data-api.polymarket.com GET /v2/leaderboard?time_period=day&limit=1. These three public requests need no account credentials.

Preserve separate identifiers

An event groups markets. Gamma id identifies metadata; conditionId identifies the on-chain condition. In the sampled CTF market, outcomes and clobTokenIds were JSON-encoded arrays paired by index. Parse both and check equal lengths before selecting a token. Stop if the fields are missing, misaligned or unsuitable for the protocol. Do not substitute the numeric Gamma id for a condition or token.

Check the public book handoff

The recorded check fetched one open Gamma market and its selected outcome book without authentication; both returned HTTP 200. Gamma supplied markets and next_cursor. CLOB supplied market, asset_id, bids, asks and timestamp: market matched conditionId and asset_id matched the token. A repeat can return another market, empty results or a missing book/error. Do not preserve the sampled price as a current quote.

Select a wallet-data read

Documented Data routes include GET /v2/positions?user={proxy wallet}&limit=1 and GET /v2/activity?user={proxy wallet}. Use a public proxy address you are entitled to examine; no wallet was queried in the recorded check. Positions default to OPEN. Use condition for a condition filter, not Gamma id. Paged reads expect data and pagination, with position condition_id and token_id. Follow opaque next_cursor until null; pagination.offset is display metadata, not a request parameter. Check defaults, filters, limits and empty results for each route.

Separate traders from builders

The trader request returned HTTP 200 and one user_id row, with data/pagination, has_more and next_cursor; only its first page was checked. GET /v2/builders/leaderboard?time_period=day&limit=1 instead describes builder_code integrations, attributed volume and active users; it remained documentation-only. Label PNL versus VOLUME, period and units. Daily marked P&L differs from all-time realized P&L; volume is shares, not USD or guaranteed profit. Rankings do not identify people or prove integrations.

Check the result

• Record host, path and public/private access boundary.
• Keep Gamma id, conditionId and the labeled token separate; compare book.market and asset_id.
• For Data, preserve data/pagination and cursor continuation rather than page numbers.
• State trader user_id or builder_code, metric, window and units.

Limits and private operations

Private CLOB GET /data/orders needs L2 HMAC authentication; placing an order additionally needs a wallet signature. Public wallet activity is not private order state or a human identity. The recorded checks covered one Gamma page, one CTF book and one trader page, not wallet accounting, all pages, private requests, signatures, orders or latency. They do not guarantee history or future availability. Do not send addresses, keys, secrets or signatures to the directory.