Polymarket Gamma API: Discovery Across 16 Venues

What is the Polymarket Gamma API?

Gamma is Polymarket's catalog and metadata service at https://gamma-api.polymarket.com. It lets developers discover events and markets, look up records by id or slug, filter listings and obtain the condition and token identifiers needed by the CLOB.

The current Polymarket API overview separates its services clearly:

Gamma is not the order book and it is not the wallet activity API. It supplies the catalog record that connects a human-readable event to the condition and outcome-token ids used by those other services.

How do you list current Gamma events and markets?

Polymarket now documents keyset-paginated listing endpoints for new catalog walks:

# Events
curl -s \
  "https://gamma-api.polymarket.com/events/keyset?limit=50"

# Markets
curl -s \
  "https://gamma-api.polymarket.com/markets/keyset?limit=50"

The event listing can include nested markets. Market records contain Polymarket-specific metadata such as conditionId, clobTokenIds, outcomes, status flags, dates, liquidity, volume, fees and resolution information. The exact field set is useful when the product is designed specifically around Polymarket.

const url = new URL(
  'https://gamma-api.polymarket.com/events/keyset',
);
url.searchParams.set('limit', '50');

const response = await fetch(url);
if (!response.ok) {
  throw new Error('Gamma returned ' + response.status);
}

const page = await response.json();

for (const event of page.events) {
  console.log({
    id: event.id,
    slug: event.slug,
    title: event.title,
    markets: event.markets?.length ?? 0,
  });
}

Direct Gamma access is public and introduces no extra provider layer. The tradeoff is that your data model becomes Polymarket-specific. Fields such as outcomes and CLOB token ids have historically appeared as JSON-encoded strings on some Gamma responses, so defensive parsers should validate the runtime type instead of assuming every array is already decoded.

What does Predictefy normalize?

Predictefy maps venue records into a common market contract. A normalized record includes a venue-scoped market id, title, outcomes, prices where available, volume and liquidity where available, a URL and honest-data fields.

{
  "marketId": "0x...",
  "title": "Will ...?",
  "outcomes": [
    {
      "outcomeId": "123...",
      "label": "Yes",
      "price": 0.61
    },
    {
      "outcomeId": "456...",
      "label": "No",
      "price": 0.39
    }
  ],
  "volume24h": 123456.78,
  "liquidity": 98765.43,
  "asOf": "2026-09-18T05:00:00.000Z",
  "provenance": {
    "source": "venue-rest"
  },
  "capabilities": {
    "read": true,
    "trade": false,
    "depth": true,
    "history": false
  }
}

Normalization deliberately does not reproduce every Gamma field. It provides the portable subset needed to discover, display and route into common market-data operations. Keep the raw Gamma response when a Polymarket-only field is a product requirement.

Which 16 venues does Predictefy serve?

The current official Predictefy skill lists these served product venues:

polymarket, kalshi, opinion, myriad, gemini, hyperliquid, limitless, polymarket_us, rain, predictfun, sxbet, pascal, xo, pred, predictstreet and novig.

router is the all-served-venues union. It is a query surface, not another exchange. Coverage is capability-qualified, so a venue being discoverable does not mean every venue exposes depth, history, wallet intelligence or execution.

TypeScript: discover Polymarket or all venues

Use the current exact beta version verified on npm:

npm install @predictefy/sdk@1.0.0-beta.9

import Predictefy from '@predictefy/sdk';

const client = new Predictefy({
  apiKey: process.env.PREDICTEFY_API_KEY,
});

const polymarketOnly = await client.polymarket.fetchMarkets({
  query: 'election',
  status: 'active',
  sort: 'volume',
  limit: 25,
});

const everyVenue = await client.router.fetchMarkets({
  query: 'election',
  status: 'active',
  sort: 'volume',
  limit: 25,
});

for (const market of everyVenue) {
  console.log({
    marketId: market.marketId,
    title: market.title,
    outcomes: market.outcomes,
    asOf: market.asOf,
    provenance: market.provenance,
    capabilities: market.capabilities,
  });
}

console.log({
  polymarketRows: polymarketOnly.length,
  crossVenueRows: everyVenue.length,
  nextCursor: everyVenue.nextCursor,
});

Python: run the same discovery workflow

pip install predictefy==1.0.0b7

import os

from predictefy import Predictefy

filters = {
    "query": "election",
    "status": "active",
    "sort": "volume",
    "limit": 25,
}

with Predictefy(api_key=os.environ["PREDICTEFY_API_KEY"]) as client:
    polymarket_only = client.polymarket.fetch_markets(filters)
    every_venue = client.router.fetch_markets(filters)

    for market in every_venue:
        print({
            "market_id": market["marketId"],
            "title": market["title"],
            "outcomes": market["outcomes"],
            "as_of": market.get("asOf"),
            "provenance": market.get("provenance"),
            "capabilities": market.get("capabilities"),
        })

    print({
        "polymarket_rows": len(polymarket_only),
        "cross_venue_rows": len(every_venue),
        "next_cursor": every_venue.next_cursor,
    })

The Python list result is a PageList, so it behaves like a normal list while also exposing page metadata and next_cursor. The TypeScript list similarly attaches page, metadata and cursor information to the returned array.

How do search and pagination differ?

Gamma and Predictefy both support paginated catalog discovery, but their contracts are not interchangeable.

One Predictefy response contains at most 100 markets. Follow its cursor for a catalog sweep. The screening guide also documents lexical, semantic and hybrid search modes. Use an explicit sort such as volume, liquidity or newest instead of treating default response order as a ranking.

Does normalized discovery match equivalent markets?

No. A router catalog search returns markets from several venues. It does not prove that similarly worded contracts are economically equivalent.

Before comparing prices, check:

• The exact resolution question and outcome meaning.
• The resolution source and authority.
• Cutoff times, time zones and early-close rules.
• Void, cancellation and edge-case treatment.
• Whether each venue is open and available to the user.

Predictefy exposes separate router-only matching and comparison operations. Their outputs must still be described accurately. Indicative price discrepancies are not executable arbitrage unless they pass the live assessment gates documented for the assessed surface.

When is Gamma the better choice?

• The product supports only Polymarket.
• You need Gamma-only metadata that is outside Predictefy's common schema.
• You want the shortest direct dependency chain.
• Your team already maintains Polymarket-specific models and identifiers.

Direct access is not a bad architecture. It is often the simplest architecture for a single-venue product.

When is Predictefy the better choice?

• The same discovery screen must cover Polymarket and other venues.
• Your downstream code needs one market and outcome model.
• You want freshness, provenance and capabilities presented consistently.
• Discovery will lead into normalized order books, trades, history or cross-venue workflows.
• You want both TypeScript and Python clients over the same hosted contract.

Predictefy's TypeScript SDK and Python SDK are currently beta packages. Pin exact versions and test upgrades. The registries list the current versions as TypeScript 1.0.0-beta.9 and Python 1.0.0b7, which were confirmed against their registries for this article.

What is a sensible hybrid architecture?

A multi-venue application can use Predictefy for its portable catalog while retaining native Gamma records for Polymarket-specific screens:

1. Search through router.fetchMarkets for the cross-venue result set.
2. Preserve venue, native market id, outcome ids, freshness and provenance.
3. When a user opens a Polymarket-specific detail view, fetch the Gamma record by id or slug.
4. Keep the raw native record separate from the normalized record instead of merging fields ambiguously.
5. Use explicit matching logic before any cross-venue price comparison.

This keeps the general product portable without throwing away venue-specific detail where it adds value.

Frequently Asked Questions