Polytoolhub logoPolytoolhubSearch tools
← Polymarket Tool Guides

Polymarket API Endpoints: Gamma, CLOB and Data

By Polytoolhub

Three hosts answer different questions. Gamma at https://gamma-api.polymarket.com discovers events and markets; CLOB at https://clob.polymarket.com serves public outcome-token books and separately authenticated order actions; Data API v2 at https://data-api.polymarket.com/v2 serves public positions, activity and rankings. These are provider-documented paths, not endpoints operated by Polytoolhub.

Choose by task and access boundary

For market metadata use public Gamma GET /markets?closed=false&limit=1 or GET /markets/{Gamma market ID}. For an outcome book use public CLOB GET /book?token_id={outcome token ID}; CLOB GET /data/orders reads the operator's own orders and requires L2 API-credential request signing. For a public proxy wallet's holdings use Data GET /v2/positions?user={proxy wallet}&limit=1; for activity use GET /v2/activity?user={proxy wallet}. Data API v2 reads require no API key, but an address does not prove a person's identity. This guide requests no address, credential or signature.

Keep identifiers in their own columns

An event id groups markets. Gamma market id looks up a market; its 0x conditionId is the on-chain condition and the Data API condition filter (condition_id in rows). Gamma outcomes and clobTokenIds are JSON-encoded arrays aligned by index: match a label to its token ID before choosing a CLOB book. The book returns market for the condition and asset_id for the selected outcome token, not the Gamma numeric market id. Data v2 position rows expose condition_id and token_id; the Data vocabulary also defines market_id for Gamma market IDs on applicable rows. Compare corresponding fields, not IDs of different kinds; no cross-API join was executed here.

Documented minimal request, not a live sample

For one market at most, the official public example can be narrowed to curl -G 'https://gamma-api.polymarket.com/markets' --data-urlencode 'closed=false' --data-urlencode 'limit=1'. The documented expected response is a JSON array of up to one market object, not a Data API v2 data envelope. Inspect id, conditionId, outcomes and clobTokenIds only if present; parse both outcome arrays and match indices. This directory did not run the request, capture a market, observe a price or test a book. Stop at an empty list, missing token or unavailable book rather than invent a join.

Trader ranking is not builder attribution

Public Data GET /v2/leaderboard?time_period=day&limit=1 ranks trader wallets by the selected PnL or volume board; GET /v2/builders/leaderboard?time_period=day&limit=1 ranks builder integrations by attributed volume and active users. Both document data plus pagination with opaque next_cursor, unlike Gamma's market array. A builder_code identifies an integration, not a trader wallet; neither rank proves profits, execution quality or a directory relationship. Read the selected window, metric and units before interpreting a result.

Before you start

  • Decide whether the task is market discovery, one outcome's book, a public wallet's holdings/activity or a trader-versus-builder ranking.
  • For books obtain a token ID from the same Gamma market and check its book status; keep that market's Gamma id and conditionId separate.
  • For wallet reads use a public proxy-wallet address you are entitled to examine; never submit addresses, wallet secrets, signatures or keys to Polytoolhub. The cited public reads do not require an account.

Follow the steps

  1. Discover a market on Gamma

    Input: A market discovery task or a known Gamma market id; no wallet credentials.

    Action: Consult gamma-api.polymarket.com public GET /markets?closed=false&limit=1 or GET /markets/{id} for a known Gamma id; check question and market status before selecting an outcome.

    Expected result: Documented expectation: a JSON array of at most one market for the list request, or one market object for a valid id, with id and conditionId; no live result was obtained here.

    Choose another tool from Polymarket APIs and Data Providers

    Check the result

    • Check an array rather than a Data v2 envelope; do not invent an id when no market is returned.

    Limitations

    • An empty result or market without an enabled book is not evidence of a current tradable market.

  2. Select an outcome identifier

    Input: One Gamma market object with id, conditionId, outcomes and clobTokenIds.

    Action: Parse the JSON-encoded outcome-label and token-id arrays; match by index. Retain Gamma market id and on-chain conditionId separately from the selected token ID.

    Expected result: A documented mapping: Gamma market id for lookup, conditionId for Data condition filters and one outcome token ID for a CLOB book; not interchangeable identifiers.

    Choose another tool from Polymarket APIs and Data Providers

    Check the result

    • Check array lengths and label/token pairing; stop if a selected outcome lacks its token.

    Limitations

    • Fields can be absent; multi-market events need selection of the actual market, and no live cross-API join was performed.

  3. Distinguish a public book from private orders

    Input: The selected outcome token ID and a decision to read a book or the operator's own open orders.

    Action: Consult clob.polymarket.com public GET /book?token_id={token ID} for bids/asks, market, asset_id and timestamp; for private GET /data/orders read the official L2 HMAC request-signing requirements instead of sending a request.

    Expected result: A documented public book response class or a private-access checklist, not an executed book or authenticated response.

    Polymarket CLOB API

    Choose another tool from Polymarket APIs and Data Providers

    Check the result

    • For a returned book, match asset_id to the token and market to conditionId; reading a book never proves a signed order worked.

    Limitations

    • A missing book can return an error. No credential was created or used; order submission needs an additional wallet signature and was not tested.

  4. Select a public Data API v2 read

    Input: A public proxy-wallet address for positions/activity, or a conditionId for market-scoped reads; no API key.

    Action: Consult data-api.polymarket.com GET /v2/positions?user={proxy wallet}&limit=1 for holdings or GET /v2/activity?user={proxy wallet} for actions. Use condition, not Gamma market id, for an on-chain market filter.

    Expected result: Documented expectation: a data array plus pagination.next_cursor for paged routes; position rows include condition_id and token_id, and an empty array is possible. No wallet data was queried.

    Polymarket Data API

    Choose another tool from Polymarket APIs and Data Providers

    Check the result

    • Compare condition_id to Gamma conditionId and token_id to the selected outcome, and follow next_cursor until null.

    Limitations

    • Public address data is not private order state or an attributed human identity. Positions default to OPEN, not all closed holdings.

  5. Separate trader and builder boards

    Input: A ranking question, time window and entity type (trader wallet or builder integration).

    Action: Compare Data GET /v2/leaderboard?time_period=day&limit=1 (trader PNL or VOLUME) with GET /v2/builders/leaderboard?time_period=day&limit=1 (builder-attributed volume and active users).

    Expected result: Documented expectation: paged data of ranked user_id rows or builder_code rows, respectively; no current rank was observed.

    Polymarket Data API

    Choose another tool from Polymarket APIs and Data Providers

    Check the result

    • Label wallet versus builder_code, requested window and PNL versus VOLUME, and use next_cursor rather than a page number.

    Limitations

    • Daily marked PnL and all-time realized PnL differ; volume is in shares, not USD or guaranteed profit. Rankings do not identify people or establish integrations.

Check the result

  • Name the exact host and path for your task and distinguish documented public GET from private credentialed CLOB actions.
  • Keep Gamma id, conditionId and a labeled outcome token ID distinct; compare CLOB book market to conditionId and asset_id to that token ID.
  • For paged Data v2 reads expect data plus pagination and follow next_cursor until null, but do not report these documented shapes as locally observed.
  • For rankings state whether the row is a trader user_id or a builder_code and name its window and metric.

Limitations

  • Official documentation was read September 29, 2026; no live Gamma, CLOB or Data response, private request, signed order, wallet or latency was tested here.
  • A documented response format is not an observed response. Market IDs, books, wallet activity, ranks and availability change; no price, address or live quote is stored as a stable example.
  • Public Data API wallet activity is not private CLOB order state; CLOB order management has a separate authentication boundary, and order placement also requires a wallet signature.
  • Paged Data v2 reads use opaque cursors; pagination.offset is display metadata, not a request parameter. Check filters, defaults, limits and empty results per endpoint.

Continue with official documentation

Continue researching

  • Polymarket Data API · next: Review the stable Data API profile for public positions, activity and rankings; runtime is not tested here.
  • Polymarket CLOB API · next: Review the stable CLOB profile for outcome-token books and the private signing boundary; no order was tested.
  • Polymarket APIs and Data Providers · context: Browse the published API category for reviewed profiles, not the unfinished Gamma profile.