---
url: "https://predictiontoolkit.com/guides/polymarket-api-endpoints/"
publisher: "PredictionToolkit"
dateModified: "2026-11-02"
---

[← Polymarket guides](<https://predictiontoolkit.com/guides/>) 

# 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.

## Continue researching

-   [Polymarket Gamma API: Event and Market Discovery API](<https://predictiontoolkit.com/tools/polymarket-gamma-api/>)  · context: Review discovery data.
-   [Polymarket CLOB API: read books and implement order handling](<https://predictiontoolkit.com/tools/polymarket-clob-api/>)  · context: Review outcome books and private orders.
-   [Polymarket Data API: turn public activity into wallet analytics](<https://predictiontoolkit.com/tools/polymarket-data-api/>)  · context: Review positions and rankings.
-   [Polymarket API key and authentication](<https://predictiontoolkit.com/guides/polymarket-api-key/>)  · context: Understand authentication layers.
-   [Polymarket APIs and Data Providers](<https://predictiontoolkit.com/polymarket-api/>)  · context: Compare API choices.