[
    {
        "role": "user",
        "content": "is%20gamma%20api%20the%20correct%20one%20to%20use%20for%20polymarket%20market%20data%3F%20or%20has%20it%20been%20superceeded%3F"
    },
    {
        "role": "assistant",
        "content": "Here\u2019s how Polymarket\u2019s APIs are structured *as of late April 2026*\u2014and whether using the Gamma API is still appropriate for getting market data.\n\n---\n\n## API Layers at Polymarket\n\nPolymarket now clearly divides its API functionality into three separate \u201cdomains\u201d:\n\n1. **Gamma API**  \n   Base URL: `https://gamma-api.polymarket.com`  \n   Scope: Market discovery and metadata\u2014events, markets, categorization, search, tags, outcome prices. Read-only. No authentication required. ([docs.polymarket.com](https://docs.polymarket.com/api-reference?utm_source=openai))\n\n2. **Data API**  \n   Base URL: `https://data-api.polymarket.com`  \n   Scope: Analytics, account/user-level data like open interest, trade history, positions, holders, etc. Some endpoints (e.g. user positions) may require authentication. ([docs.polymarket.com](https://docs.polymarket.com/api-reference?utm_source=openai))\n\n3. **CLOB API**  \n   Base URL: `https://clob.polymarket.com`  \n   Scope: The order book, prices, actual trading (placing/canceling orders), spreads, tick data, etc. Some endpoints provide public (read-only) data; others (especially order placement) require authentication. ([docs.polymarket.com](https://docs.polymarket.com/api-reference?utm_source=openai))\n\n---\n\n## What \"Market Data\" Means & Where to Get It\n\n\u201cMarket data\u201d often has different meanings depending on how much detail you need. Here\u2019s how the APIs map to those needs:\n\n| Data Requirement | Best API(s) |\n|------------------|-------------|\n| Discovery & metadata (market titles, descriptions, outcomes, tags, resolution dates, etc.) | **Gamma API** ([docs.polymarket.com](https://docs.polymarket.com/developers/gamma-markets-api/overview?dub_id=Pu93SRzVLZfFlDx3&utm_source=openai)) |\n| Real-time prices (Yes/No outcome prices), current volume, & funding event status | Gamma API for basic info; **CLOB** API for accurate, low-latency price, orderbook, trades ([polybuild.app](https://www.polybuild.app/blog/polymarket-api-guide?utm_source=openai)) |\n| Full orderbook or level-2 (L2) data, live trade ticks, placing/canceling orders | **CLOB API** (REST + WebSocket/gRPC) ([docs.polymarket.us](https://docs.polymarket.us/data-guide/market-data?utm_source=openai)) |\n| Historical trades, user-specific history, positions, open interest | **Data API** ([docs.polymarket.com](https://docs.polymarket.com/api-reference?utm_source=openai)) |\n\n---\n\n## Has Gamma API Been Superseded?\n\nShort answer: **No, it hasn\u2019t been superseded. It still plays a critical role\u2014but its role is specific.**\n\n- **Gamma API is still current and maintained.** It remains the \u201ccatalog\u201d or \u201cdiscovery\u201d layer of Polymarket. If you need to find markets, get descriptions, see what is available, fetch current implied probabilities per outcome (like \u201cYes\u201d or \u201cNo\u201d prices), Gamma is the correct API to use for those purposes. ([docs.polymarket.com](https://docs.polymarket.com/developers/gamma-markets-api/overview?dub_id=Pu93SRzVLZfFlDx3&utm_source=openai))\n- For trading, real-time data, or anything that requires more granular, accurate, or lower-latency data (such as orderbook updates, fills, placing or cancelling orders), **you\u2019ll need to use the CLOB API**. Gamma might lag behind CLOB slightly when reflecting the latest trades because it\u2019s more about metadata and aggregated outcomePrices. ([polybuild.app](https://www.polybuild.app/blog/polymarket-api-guide?utm_source=openai))\n\n---\n\n## Use Cases to Help You Choose\n\nTo be concrete, here\u2019s when you should use each API:\n\n- If you're building a *dashboard*, website, or tool that lists available markets and shows approximate current odds, resolution date, tags \u2014 **use Gamma**.\n- If you're doing *signal generation* using live prices, or want to see orderbook spreads, or need confirmed fills \u2014 **use CLOB**.\n- If you need *user-specific analytics*, trade history, open interest, or historical market stats \u2014 then utilize **Data API**.\n\n---\n\n## Summary / Recommendation\n\n- **Gamma API is correct and still very much in use** for market discovery & metadata. It is not outdated or deprecated.\n- But it is *not sufficient alone* for real trading or full data\u2014especially if you need real-time orderbooks or trades.\n- For a \u201cone stop shop\u201d market data tool (for trading bots, backtesting, etc.), you\u2019ll often need to use **Gamma + CLOB + Data API** together.\n\nIf you tell me exactly which pieces of \"market data\" you're after (like Yes/No outcome probabilities, full orderbook, historical trades, etc.), I can suggest which combination of API endpoints will best serve your needs."
    },
    {
        "role": "user",
        "content": "ok%2C%20it%27s%20gamma%20data%20i%20want%2C%20data%20on%20markets%2C%20events%2C%20etc.%20explain%20how%20the%20data%20structures%20work%20here%2C%20i.e.%20we%20have%20markets%20at%20the%20top%2C%20then%20within%20markets%20events%2C%20then%20within%20events%20outcomes%3F%20something%20like%20that%3F%20how%20are%20they%20all%20keyed%20together%2C%20i.e.%20markets%20to%20events%20to%20outcomes%20or%20whatever%3F"
    },
    {
        "role": "assistant",
        "content": "Here\u2019s how Polymarket\u2019s **Gamma API** data model is structured (as of April 2026) for markets / events / outcomes, how the hierarchy works, what fields to expect, and how they\u2019re keyed.  \n\n---\n\n## Hierarchy: Events \u2192 Markets \u2192 Outcomes\n\nPolymarket arranges its public metadata with this structure:\n\n- **Event**: A container for one or more markets. Examples of events:\n  - Single-market events: \u201cWill BTC reach \\$100k by Dec 2026?\u201d \u2192 one market (Yes/No). ([docs.polymarket.com](https://docs.polymarket.com/developers/misc-endpoints/data-api-activity?utm_source=openai))\n  - Multi-market events: \u201cWho will win the 2024 U.S. Presidential Election?\u201d \u2192 multiple markets under one event (Trump, Biden, Other...) each as binary (Yes/No) markets. ([docs.polymarket.com](https://docs.polymarket.com/developers/misc-endpoints/data-api-activity?utm_source=openai))\n\n- **Market**: A single binary outcome \u201cYes vs. No\u201d prediction that is tradable. Each market belongs to exactly one event. ([docs.polymarket.com](https://docs.polymarket.com/concepts/markets-events?utm_source=openai))\n\n- **Outcomes**: Typically two outcomes (\u201cYes\u201d, \u201cNo\u201d) per market. Their current implied probabilities (\u201cprices\u201d) are given. ([docs.polymarket.com](https://docs.polymarket.com/developers/misc-endpoints/data-api-activity?utm_source=openai))\n\n---\n\n## Key Identifiers & Fields\n\nHere are the critical keys and metadata fields for linking and interpreting data in Gamma:\n\n| Field | What it Uniquely Identifies / Connects | Notes |\n|-------|------------------------------------------|-------|\n| `event.id` | Unique event identifier (hex string) \u2014 top level. | Use this to link markets under events. ([polytrackhq.app](https://www.polytrackhq.app/blog/gamma-api-events-guide?utm_source=openai)) |\n| `event.slug` | URL-friendly identifier (e.g. \u201ctrump-2028\u201d) for events. | Helps get event from URL or filter with slug. ([docs.polymarket.com](https://docs.polymarket.com/developers/gamma-markets-api/get-events?utm_source=openai)) |\n| `market.conditionId` | Unique ID for the market\u2019s condition (hex string) in Polymarket\u2019s conditional tokens framework. | It links the market to on-chain contracts. ([docs.polymarket.com](https://docs.polymarket.com/concepts/markets-events?utm_source=openai)) |\n| `market.slug` | URL-friendly identifier for the market. Often same slug as event in single-market events. | Useful for lookups with slug queries. ([docs.polymarket.com](https://docs.polymarket.com/developers/gamma-markets-api/get-events?utm_source=openai)) |\n| `market.clobTokenIds` | Two token IDs\u2014one for each outcome\u2014that identify the ERC-1155 assets in the CLOB system. | `clobTokenIds[0]` matches `outcomes[0]`, same for prices. ([docs.polymarket.com](https://docs.polymarket.com/concepts/markets-events?utm_source=openai)) |\n\n---\n\n## Typical Data Objects & Field Layout\n\nHere\u2019s a sketch of what the API returns and how to interpret it:\n\n---\n\n### Event Object\n\nTypical fields in `GET /events` or `GET /events/{id}`:\n\n- `id`: hex string, global unique event ID. ([polytrackhq.app](https://www.polytrackhq.app/blog/gamma-api-events-guide?utm_source=openai))  \n- `slug`: string, URL identifier for the event. ([docs.polymarket.com](https://docs.polymarket.com/developers/gamma-markets-api/get-events?utm_source=openai))  \n- `title` or `question` or `name`: human-readable event title. ([polytrackhq.app](https://www.polytrackhq.app/blog/gamma-api-events-guide?utm_source=openai))  \n- `description`: maybe markdown, criteria for resolution. ([rekko.ai](https://rekko.ai/docs/guides/polymarket-api-guide?utm_source=openai))  \n- Boolean flags: `active` (live/tradingable), `closed` (resolved / no longer active). ([docs.polymarket.com](https://docs.polymarket.com/developers/misc-endpoints/data-api-activity?utm_source=openai))  \n- `markets`: array of market objects under this event. Each market object has fields like those below. ([polytrackhq.app](https://www.polytrackhq.app/blog/gamma-api-events-guide?utm_source=openai))  \n\n---\n\n### Market Object (nested in event or via `GET /markets`)\n\nKey fields:\n\n- `conditionId`: hex condition-ID for linking to contracts. ([docs.polymarket.com](https://docs.polymarket.com/concepts/markets-events?utm_source=openai))  \n- `question`: the market question text (often repeated from the event). ([docs.polymarket.com](https://docs.polymarket.com/developers/gamma-markets-api/overview?dub_id=Pu93SRzVLZfFlDx3&utm_source=openai))  \n- `slug`: slug of this market. In many single-market events the event & market slug overlap. ([docs.polymarket.com](https://docs.polymarket.com/developers/gamma-markets-api/get-events?utm_source=openai))  \n- `outcomes`: array of outcome labels (typically `[\"Yes\", \"No\"]`). ([docs.polymarket.com](https://docs.polymarket.com/developers/misc-endpoints/data-api-activity?utm_source=openai))  \n- `outcomePrices`: array of strings (floats) for each outcome\u2019s implied probability. Length matches `outcomes`. ([docs.polymarket.com](https://docs.polymarket.com/developers/misc-endpoints/data-api-activity?utm_source=openai))  \n- `clobTokenIds`: array of token IDs, one for each outcome token. Used with CLOB if doing trading or wants on-chain token identifiers. ([rekko.ai](https://rekko.ai/docs/guides/polymarket-api-guide?utm_source=openai))  \n- `volume`, `volume24hr`: lifetime & recent volumes. ([rekko.ai](https://rekko.ai/docs/guides/polymarket-api-guide?utm_source=openai))  \n- `liquidity`: available in order book, if enabled. ([rekko.ai](https://rekko.ai/docs/guides/polymarket-api-guide?utm_source=openai))  \n- `startDate` / `endDate`: ISO timestamps. `endDate` often denotes resolution date. ([rekko.ai](https://rekko.ai/docs/guides/polymarket-api-guide?utm_source=openai))  \n- `active`, `closed`: same concept as event flags but per market. ([docs.polymarket.com](https://docs.polymarket.com/developers/misc-endpoints/data-api-activity?utm_source=openai))  \n\n---\n\n## How It All Ties Together\n\n- An **Event** can have **one or more Markets**.  \n- Each **Market** has exactly two **Outcomes** (Yes/No), each with its own outcome label, price, and token ID.  \n- A Market is linked to its Event via `event.markets` (if fetched via the event endpoint) or via `market` responses that supply keys like `conditionId`, which correspond to an event, or via separate queries if needed.  \n\nTo map things:\n\n1. Fetch `GET /events?active=true&closed=false` \u2192 you get events + their markets.  \n2. In each event, loop through `markets` array to examine markets.  \n3. For each market, `outcomes[i]` corresponds to `outcomePrices[i]`, and `clobTokenIds[i]` corresponds to each.  \n\n---\n\n## Peculiarities & Things to Watch\n\n- **JSON-encoded arrays in strings** for some fields:  \n  Fields like `outcomePrices`, `clobTokenIds`, `outcomes` are sometimes returned *as strings* that themselves are JSON arrays, not as native arrays. You often need to `JSON.parse(...)` on them. ([polytrackhq.app](https://www.polytrackhq.app/blog/gamma-api-events-guide?utm_source=openai))  \n\n- **Paginated listing**:  \n  Both `GET /events` and `GET /markets` support keyset pagination using `after_cursor`. Offset-based pagination may be rejected. ([polymarketarbitragebot.net](https://www.polymarketarbitragebot.net/guides/polymarket-gamma-api-tutorial?utm_source=openai))  \n\n- **Filtering by tag, slug, conditionId, etc.** supported on both event & market endpoints. ([docs.polymarket.com](https://docs.polymarket.com/developers/gamma-markets-api/get-events?utm_source=openai))  \n\n---\n\nIf you want, I can pull up the *exact OpenAPI schema* for each endpoint (market & event) so you can generate typed objects in your codebase. Do you want that?"
    },
    {
        "role": "user",
        "content": "good.%20now%2C%20we%20have%20many%20events.%20are%20they%20categorized%2C%20so%20for%20example%20we%20might%20have%20finance%2C%20sports%2C%20crypto%3F%20You%20mentioned%20tag%2C%20slug%2C%20conditionId%2C%20--%20are%20any%20of%20these%20useful%20for%20finding%20all%20events%20within%20some%20given%20category%2C%20say%20finance%3F"
    },
    {
        "role": "assistant",
        "content": "Yes \u2014 Polymarket *does* categorize events and markets using **tags and sports metadata**, which lets you filter down to specific categories like *Finance*, *Crypto*, *Sports*, etc. Here\u2019s how it works and what you can use:\n\n---\n\n## Tags \u2014 Primary Tool for Categorization & Filtering\n\n- Every **event** (and market) can have multiple **tags**, which are string labels with a `slug` and `id`. These represent topics (\"finance\", \"crypto\", \"politics\", etc.) or more specific ones like \"elections\", \"futures\", \"crypto-15min\". ([polymarket-data.com](https://polymarket-data.com/gamma/events-tags?utm_source=openai))  \n- You can query events or markets by tag using parameters:\n  - `tag_id=[...]` to include a specific tag  \n  - `exclude_tag_id=[...]` to exclude some tags  \n  - `tag_slug=[...]` may also be supported depending on client or endpoint. ([docs.polymarket.com](https://docs.polymarket.com/developers/gamma-markets-api/get-events?utm_source=openai))  \n\nFor example, to fetch all active events in the \u201cfinance\u201d category/tag, you\u2019d first find the tag for \u201cfinance\u201d by listing all tags, get its `id`, then call:\n\n```\nGET /events?active=true&closed=false&tag_id=<finance-tag-id>\n```\n\n\u2014 which returns only events with that tag. ([docs.polymarket.com](https://docs.polymarket.com/developers/gamma-markets-api/get-events?utm_source=openai))\n\n---\n\n## Sports / Series \u2014 Dedicated Structure for Sports Category\n\n- Polymarket has a `/sports` endpoint in Gamma API that returns metadata on various sports. Each sport has:\n  - `sport` name/slug\n  - image assets\n  - `tags` (comma-separated list of tag IDs) that relate the sport to tags/categories. ([docs.polymarket.com](https://docs.polymarket.com/api-reference/sports/get-sports-metadata-information?utm_source=openai))  \n- If you want **Sports** events specifically, you can use tag filtering (`tag_id`) with the events/markets endpoints *or* check the `/sports` endpoints. The sports metadata helps map sports \u2192 tags \u2192 events. This is useful when you want all events in \"soccer\", \"basketball\", etc. ([docs.polymarket.com](https://docs.polymarket.com/api-reference/sports/get-sports-metadata-information?utm_source=openai))  \n\n---\n\n## Other Identifiers: `slug`, `conditionId`\n\n- `slug`: URL\u2010friendly string for events/markets; good for finding specific ones when you already know the slug. Not useful for broad category filtering unless slugs systematically include categories. ([docs.polymarket.com](https://docs.polymarket.com/developers/gamma-markets-api/get-events?utm_source=openai))  \n- `conditionId`: Unique condition/market identifier. Useful for downstream linking (like connecting markets to outcome tokens), but not a categorical attribute. ([docs.polymarket.com](https://docs.polymarket.com/developers/misc-endpoints/data-api-activity?utm_source=openai))  \n\n---\n\n## \u201cCategories\u201d Field\n\n- There *is* a `category` (and sometimes `subcategory`) field in some endpoints / response schemas, especially for sports and generic event classification. This can directly indicate main groupings like \u201csports\u201d, \u201cpolitics\u201d, etc. ([docs.polymarket.us](https://docs.polymarket.us/api-reference/events/overview?utm_source=openai))  \n- However, usage and consistency may vary; tags offer more flexibility and are broadly supported for filtering. ([haut.github.io](https://haut.github.io/polymarket/polymarket/Polymarket/Gamma/index.html?utm_source=openai))  \n\n---\n\n## Summary: How to Filter Events by Category\n\nPutting it all together, here\u2019s how you\u2019d reliably find events in a category like *finance* or *crypto*:\n\n1. **Fetch all tags**: `GET /tags` via Gamma API to get list of tag `id`, `slug`, `label`. Look for `finance` or `crypto`. ([docs.polymarket.com](https://docs.polymarket.com/api-reference?utm_source=openai))  \n2. **Use tag-based filtering**:  \n   ```\n   GET /events?active=true&closed=false&tag_id=<finance tag id>\n   ```\n3. **(Optional)** Use `category` if available in schema to double-check or further restrict.  \n4. If you need **sports** specifically, use the `/sports` endpoint to get sports metadata, then filter events with tag\u2010ids related to that sport. ([docs.polymarket.us](https://docs.polymarket.us/api-reference/sports/overview?utm_source=openai))  \n\n---\n\nIf you like, I can also pull together a full list of current \u201cfinance/crypto\u201d tags in Polymarket\u2019s Gamma API (with IDs), so you can integrate them directly in your app."
    },
    {
        "role": "user",
        "content": "where%20do%20i%20get%20the%20list%20of%20tag_id%20and%20description%3F"
    },
    {
        "role": "assistant",
        "content": "You can retrieve the full list of tags (their `tag_id`, `label`, `slug`, etc.) via the Gamma API. Here are the relevant endpoints + field descriptions and an example response.\n\n---\n\n## \ud83d\udd0d Tag Endpoints & How to Use Them\n\n### 1. **List all tags**\n\n- **Endpoint**: `GET https://gamma-api.polymarket.com/tags`\n- Returns: All tags used for categorization. Useful if you want to know all possible categories, including \u2018finance\u2019, \u2018crypto\u2019, etc. ([docs.polymarket.com](https://docs.polymarket.com/api-reference/tags/list-tags?utm_source=openai))\n\n### 2. **Get a specific tag by ID**\n\n- **Endpoint**: `GET https://gamma-api.polymarket.com/tags/{id}`\n- Returns: Tag data for that single tag. Use this if you already know `tag_id`. ([docs.polymarket.us](https://docs.polymarket.us/api-reference/tags/overview?utm_source=openai))\n\n### 3. **Get a specific tag by slug**\n\n- **Endpoint**: `GET https://gamma-api.polymarket.com/tags/slug/{slug}`\n- Returns: Tag data when you know the slug (like `crypto`, `sports`, etc.). ([docs.polymarket.us](https://docs.polymarket.us/api-reference/tags/overview?utm_source=openai))\n\n### 4. **Featured tags**\n\n- **Endpoint**: `GET https://gamma-api.polymarket.com/tags/featured`\n- Returns: Tags curated for display, often popular or newly relevant ones. ([docs.polymarket.us](https://docs.polymarket.us/api-reference/tags/overview?utm_source=openai))\n\n---\n\n## \ud83d\udce6 Tag Object Structure\n\nHere's a simplified example of what each tag object looks like in the `List tags` response:\n\n```json\n{\n  \"id\": \"100381\",              // the tag_id (string)\n  \"label\": \"Crypto\",           // human-readable name\n  \"slug\": \"crypto\",            // URL/text-friendly identifier\n  \"forceShow\": true,           // internal display rules\n  \"publishedAt\": \"2023-11-07T05:31:56Z\",  // when the tag was made public\n  \"createdBy\": 123,            // user or system ID who created it\n  \"updatedBy\": 123,            // last updated by\n  \"createdAt\": \"2023-11-07T05:31:56Z\",\n  \"updatedAt\": \"2023-11-07T05:31:56Z\",\n  \"forceHide\": false,          // internal display flag\n  \"isCarousel\": true           // whether to show in carousel/UIs\n}\n```\n\nFields you\u2019ll want for filtering are `id`, `label`, and `slug`. The rest are metadata mostly for front-end behavior. ([docs.polymarket.com](https://docs.polymarket.com/api-reference/tags/list-tags?utm_source=openai))\n\n---\n\n## \u2705 How to Fetch & Use Them\n\nHere\u2019s a quick recipe:\n\n1. Hit `GET /tags` to get every tag.\n2. Search for the tag of interest (e.g. `slug: \"finance\"`) or scan labels until you find what you want.\n3. Note down its `id` (let\u2019s say it\u2019s `100381`)\u2014that is your `tag_id`.\n4. Use that in queries like:\n   ```\n   GET /events?tag_id=100381&active=true&closed=false\n   ```\n   or\n   ```\n   GET /markets?tag_id=100381&active=true\n   ```\n   etc., to fetch events/markets in that category. ([docs.polymarket.com](https://docs.polymarket.com/developers/gamma-markets-api/fetch-markets-guide?utm_source=openai))\n\n---\n\nIf you want, I can pull **today\u2019s full tag list** for you\u2014just tell me finance, crypto, politics, etc.\u2014so you have the current IDs and labels."
    }
]