> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# predictionMarkets

> Returns prediction markets by ID.

<Info>
  **Prediction Market data is currently in beta**. It is actively being worked on and improved, but may be unreliable. Polymarket and Kalshi data are live.

  At least for the time being, this endpoint requires a Growth or Enterprise plan. [Learn more](https://dashboard.codex.io/dashboard/billing?utm_source=codex\&utm_medium=docs\&utm_campaign=billing).
</Info>

<div data-generated>
  ## GraphQL

  ```
  type Query {
    # Requires a Growth or Enterprise plan.
    predictionMarkets(
      input: PredictionMarketsInput!
    ): [PredictionMarket!]!
  }

  enum PredictionProtocol {
    POLYMARKET
    KALSHI
  }

  type PredictionResolution {
    result: String
    source: String
  }

  type PredictionSubSubcategory {
    name: String!
    slug: String!
  }

  type PredictionSubcategory {
    name: String!
    slug: String!
    subcategories: [PredictionSubSubcategory!]
  }

  type PredictionCategory {
    name: String!
    slug: String!
    subcategories: [PredictionSubcategory!]
  }

  enum PredictionMetadataType {
    SPORTS
  }

  type SportsTeam {
    abbreviation: String!
    altAbbreviations: [String!]
    name: String
    league: String
    logo: String
    alias: String
    color: String
    providerId: Int
    isHome: Boolean
  }

  enum SportsTimezone {
    UTC
  }

  type SportsMarketEnrichedMetadata {
    sportsMarketType: String
    league: String
    teams: [SportsTeam!]
    gameStartDate: String
    gameStartTime: String
    gameStartTimeSeconds: Int
    gameStartTimezone: SportsTimezone
  }

  type PredictionMarketEnrichedMetadata {
    metadataType: PredictionMetadataType!
    sports: SportsMarketEnrichedMetadata
  }

  type PredictionMarket {
    id: String!
    protocol: PredictionProtocol!
    venueMarketId: String!
    venueMarketSlug: String
    eventId: String
    venueEventId: String
    question: String
    label: String
    suggestedLabel: String
    eventLabel: String
    rules: String
    rules2: String
    venueOutcomeIds: [String!]!
    outcomeIds: [String!]!
    outcomeLabels: [String!]
    resolution: PredictionResolution
    imageLargeUrl: String
    imageThumbUrl: String
    imageSmallUrl: String
    createdAt: Int
    updatedAt: Int
    opensAt: Int
    closesAt: Int
    resolvesAt: Int
    resolvedAt: Int
    observedAt: Int!
    networkId: Int
    exchangeAddress: String
    categories: [PredictionCategory!]
    winningOutcomeId: String
    enrichedMetadata: PredictionMarketEnrichedMetadata
  }

  input PredictionMarketsInput {
    marketIds: [String!]!
  }
  ```
</div>

## Query Example

<a href="/explore" target="_blank" rel="noopener noreferrer">Test this query in the Explorer →</a>

Fetch a single prediction market by its ID to get comprehensive market details including outcomes, categories, resolution status, and timestamps.

```graphql theme={null}
{
  predictionMarkets(input: {
    marketIds: ["0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"]
  }) {
    id
    question
    label
    rules
    outcomeLabels
    outcomeIds
    imageThumbUrl
    createdAt
    closesAt
    resolvesAt
    resolvedAt
    winningOutcomeId
    categories {
      name
      slug
      subcategories {
        name
        slug
			}
    }
    resolution {
      result
      source
    }
  }
}
```

<Accordion title="Example Response">
  ```json theme={null}
  {
    "data": {
      "predictionMarkets": [
        {
          "id": "0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
          "question": "Will the Fed increase interest rates by 25+ bps after the March 2026 meeting?",
          "label": "25+ bps increase",
          "rules": "The FED interest rates are defined in this market by the upper bound of the target federal funds range. The decisions on the target federal fund range are made by the Federal Open Market Committee (FOMC) meetings.\n\nThis market will resolve to the amount of basis points the upper bound of the target federal funds rate is changed by versus the level it was prior to the Federal Reserve's March 2026 meeting.\n\nIf the target federal funds rate is changed to a level not expressed in the displayed options, the change will be rounded up to the nearest 25 and will resolve to the relevant bracket. (e.g. if there's a cut/increase of 12.5 bps it will be considered to be 25 bps)\n\nThe resolution source for this market is the FOMC’s statement after its meeting scheduled for March 17 - 18, 2026 according to the official calendar: https://www.federalreserve.gov/monetarypolicy/fomccalendars.htm.\n\nThe level and change of the target federal funds rate is also published at the official website of the Federal Reserve at https://www.federalreserve.gov/monetarypolicy/openmarket.htm.\n\nThis market may resolve as soon as the FOMC’s statement for their March meeting with relevant data is issued. If no statement is released by the end date of the next scheduled meeting, this market will resolve to the \"No change\" bracket.",
          "outcomeLabels": [
            "Yes",
            "No"
          ],
          "outcomeIds": [
            "54073086346734626735797775941991553522163760164405051969883391401961188364109:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
            "111080671036126109659854287535401661966194360665829017654832975124868412594547:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"
          ],
          "imageThumbUrl": "https://polymarket-upload.s3.us-east-2.amazonaws.com/jerome+powell+glasses1.png",
          "createdAt": 1761685086,
          "closesAt": 1773792000,
          "resolvesAt": 1773792000,
          "resolvedAt": null,
          "winningOutcomeId": null,
          "categories": [
            {
              "name": "Economy",
              "slug": "economy",
              "subcategories": [
                {
                  "name": "Fed",
                  "slug": "fed"
                }
              ]
            },
            {
              "name": "Finance",
              "slug": "finance",
              "subcategories": []
            },
            {
              "name": "Politics",
              "slug": "politics",
              "subcategories": []
            },
            {
              "name": "Sports",
              "slug": "sports",
              "subcategories": []
            }
          ],
          "resolution": null,
          "networkId": 137,
          "exchangeAddress": "0xc5d563a36ae78145c45a50134d48a1215220f80a"
        }
      ]
    }
  }
  ```
</Accordion>

## Usage Guidelines

### Market ID Format

Market IDs follow platform-specific formats:

* **Polymarket**: `<marketAddress>:Polymarket:<exchangeAddress>:<networkId>` (e.g., `0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137`)
* **Kalshi**: `<marketSlug>:Kalshi` (e.g., `KXMVECROSSCATEGORY-S2026A4A05B370DF-F1FBA451AA9:Kalshi`)

These composite IDs uniquely identify a market across protocols and networks.

### Batch Queries

You can query up to multiple markets in a single request by providing an array of `marketIds`. This is more efficient than making individual requests for each market. Consider batching when:

* Displaying multiple markets on a single page
* Comparing related markets
* Building dashboards or aggregated views

### Timestamps

All timestamp fields are returned as Unix timestamps (seconds since epoch). Note:

* `closesAt`: When the market stops accepting new positions
* `resolvesAt`: Expected resolution time (may differ from actual)
* `resolvedAt`: Actual resolution time (null if unresolved)

## Troubleshooting

<AccordionGroup>
  <Accordion title="Why am I getting 'null' for some fields?">
    Not all fields are available for every market or protocol. Different prediction protocols provide different levels of detail. Common null fields include:

    * `venueMarketSlug`: Some markets don't have slugs
    * `eventId`, `venueEventId`: Only present for markets that are part of a larger event
    * `rules2`: Secondary rules are optional
    * `imageLargeUrl`, `imageThumbUrl`, `imageSmallUrl`: Images are not required
    * `resolution`: Only populated after market resolution

    Always handle null values gracefully in your application code.
  </Accordion>

  <Accordion title="Market IDs not returning results">
    If your query returns an empty array or no results:

    1. Verify the market ID format is correct for the platform:
       * **Polymarket**: `<marketAddress>:Polymarket:<exchangeAddress>:<networkId>`
       * **Kalshi**: `<marketSlug>:Kalshi`
    2. Ensure the market exists on the specified protocol (POLYMARKET or KALSHI)
    3. Check that you're using the complete Codex market ID, not just the address portion
    4. The market may have been delisted or removed from the platform
    5. Try querying a known valid market ID to verify your API connection
  </Accordion>

  <Accordion title="Timestamps are showing incorrect dates">
    Timestamps are returned as Unix timestamps (seconds since epoch). Common issues:

    * **JavaScript**: Use `new Date(timestamp * 1000)` - multiply by 1000 to convert to milliseconds
    * **Python**: Use `datetime.fromtimestamp(timestamp)`
    * **Timezone**: Timestamps are in UTC; convert to your local timezone for display

    If a timestamp is null, the event hasn't occurred yet or the data isn't available.
  </Accordion>

  <Accordion title="Categories or subcategories are empty">
    Not all markets are categorized. Categories are provided by the prediction protocol and may not be comprehensive. If `categories` is null or empty:

    * The market hasn't been assigned to a category yet
    * The protocol doesn't use categories for this market
    * Categories may be updated over time as markets are reclassified

    Don't rely solely on categories for filtering; consider using question text or labels instead.
  </Accordion>

  <Accordion title="Protocol field shows POLYMARKET but I expected KALSHI">
    Each market belongs to a specific protocol:

    * Market IDs are protocol-specific and cannot be used interchangeably
    * Verify you're querying the correct market ID for your intended protocol
    * The `protocol` field indicates the source platform, not your preference
  </Accordion>

  <Accordion title="Getting authentication or permission errors">
    Prediction market data requires a Growth or Enterprise plan:

    1. Verify your API key is valid and has the correct permissions
    2. Check your plan tier at [dashboard.codex.io/dashboard/billing](https://dashboard.codex.io/dashboard/billing)
    3. Ensure you're including the Authorization header in your request
    4. Contact support if you believe you should have access

    This is a beta feature with limited availability.
  </Accordion>
</AccordionGroup>