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

# predictionMarketBars

> Returns OHLC-style bar data for a prediction market. Reference for the predictionMarketBars query in the Codex API: arguments, response fields, and usage.

> [!NOTE]
>
> 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).

## GraphQL

```
type Query {
  # Requires a Growth or Enterprise plan.
  predictionMarketBars(
    input: PredictionMarketBarsInput!
  ): PredictionMarketBarsResponse
}

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
}

enum PredictionEventStatus {
  OPEN
  SUSPENDED
  RESOLVED
  CANCELLED
  PENDING
}

type KalshiSportsTickerComponents {
  rawTicker: String!
  seriesPrefix: String!
  seriesSport: String
  teamTailRaw: String
  homeAbbreviation: String
  awayAbbreviation: String
}

type DecomposedVenueTicker {
  kalshiSports: KalshiSportsTickerComponents
}

type SportsEventEnrichedMetadata {
  league: String
  teams: [SportsTeam!]
  gameStartDate: String
  gameStartTime: String
  gameStartTimeSeconds: Int
  gameStartTimezone: SportsTimezone
  decomposedVenueTicker: DecomposedVenueTicker
}

type PredictionEventEnrichedMetadata {
  metadataType: PredictionMetadataType!
  sports: SportsEventEnrichedMetadata
}

type PredictionEvent {
  id: String!
  protocol: PredictionProtocol!
  venueEventId: String!
  venueSeriesId: String
  status: PredictionEventStatus!
  question: String!
  url: String!
  rulesPrimary: String!
  rulesSecondary: String
  tags: [String!]!
  opensAt: Int!
  closesAt: Int
  resolvesAt: Int
  resolvedAt: Int
  resolution: PredictionResolution
  imageLargeUrl: String
  imageThumbUrl: String
  imageSmallUrl: String
  createdAt: Int!
  updatedAt: Int!
  networkId: Int
  marketIds: [String!]
  categories: [PredictionCategory!]
  enrichedMetadata: PredictionEventEnrichedMetadata
}

type PredictionMarketBarOhlc {
  o: String!
  h: String!
  l: String!
  c: String!
}

type PredictionOutcomeBar {
  venueOutcomeId: String!
  trades: Int
  buys: Int
  sells: Int
  volumeShares: String
  buyVolumeShares: String
  sellVolumeShares: String
  volumeUsd: String
  buyVolumeUsd: String
  sellVolumeUsd: String
  volumeCollateralToken: String
  buyVolumeCollateralToken: String
  sellVolumeCollateralToken: String
  priceUsd: PredictionMarketBarOhlc
  priceCollateralToken: PredictionMarketBarOhlc
  liquidityUsd: PredictionMarketBarOhlc
  liquidityCollateralToken: PredictionMarketBarOhlc
  bidUsd: PredictionMarketBarOhlc
  bidCollateralToken: PredictionMarketBarOhlc
  askUsd: PredictionMarketBarOhlc
  askCollateralToken: PredictionMarketBarOhlc
  twoPercentBidDepthUsd: PredictionMarketBarOhlc
  twoPercentBidDepthCollateralToken: PredictionMarketBarOhlc
  twoPercentAskDepthUsd: PredictionMarketBarOhlc
  twoPercentAskDepthCollateralToken: PredictionMarketBarOhlc
}

type PredictionMarketBar {
  t: Int!
  volumeUsd: String
  volumeCollateralToken: String
  volumeShares: String
  uniqueTraders: Int
  lastEventTimestamp: Int
  trades: Int
  allTimeVolumeUsd: String
  allTimeVenueVolumeUsd: String
  allTimeVolumeCollateralToken: String
  allTimeVenueVolumeCollateralToken: String
  openInterestUsd: PredictionMarketBarOhlc
  outcome0: PredictionOutcomeBar
  outcome1: PredictionOutcomeBar
}

type PredictionMarketBarsResponse {
  marketId: String!
  predictionMarket: PredictionMarket!
  predictionEvent: PredictionEvent!
  bars: [PredictionMarketBar!]!
}

enum PredictionMarketBarsResolution {
  min1
  min5
  min15
  min30
  hour1
  hour4
  hour12
  day1
  week1
}

input PredictionMarketBarsInput {
  marketId: String!
  from: Int!
  to: Int!
  resolution: PredictionMarketBarsResolution!
  countback: Int
  removeEmptyBars: Boolean
}
```

## Example Query

[Test this query in the Explorer →](https://docs.codex.io/explore.md)

```graphql theme={null}
{
  predictionMarketBars(input: {
    marketId: "0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"
    from: 1772658000
    to: 1773349275
    resolution: day1
  }) {
    bars {
      t
      volumeUsd
      trades
      uniqueTraders
      outcome0 {
        priceUsd {
          o
          h
          l
          c
        }
        volumeUsd
        buyVolumeUsd
        sellVolumeUsd
        liquidityUsd {
          o
          h
          l
          c
        }
      }
      outcome1 {
        priceUsd {
          o
          h
          l
          c
        }
        volumeUsd
        buyVolumeUsd
        sellVolumeUsd
      }
    }
  }
}
```

```json Example Response (truncated) theme={null}
{
  "data": {
    "predictionMarketBars": {
      "bars": [
        {
          "t": 1772582400,
          "volumeUsd": "1073538.078916",
          "trades": 965,
          "uniqueTraders": 337,
          "outcome0": {
            "priceUsd": {
              "o": "0.006",
              "h": "0.008065",
              "l": "0.004",
              "c": "0.005"
            },
            "volumeUsd": "3785.090519",
            "buyVolumeUsd": "2447.47264",
            "sellVolumeUsd": "1337.617879",
            "liquidityUsd": {
              "o": "281814.102498",
              "h": "899479.973067",
              "l": "258871.310908",
              "c": "865147.393041"
            }
          },
          "outcome1": {
            "priceUsd": {
              "o": "0.992977",
              "h": "0.996131",
              "l": "0.991936",
              "c": "0.995994"
            },
            "volumeUsd": "1069752.988397",
            "buyVolumeUsd": "1019145.40634",
            "sellVolumeUsd": "50607.582057"
          }
        },
        // ... 8 more bars
      ]
    }
  }
}
```

## Usage Guidelines

Bar data provides time-series OHLC (Open, High, Low, Close) aggregates for individual prediction markets. Each bar represents a time period and includes comprehensive metrics for both outcomes, including price movements, volume, liquidity, bid/ask spreads, and order book depth.

Key characteristics:

* **Market ID formats** vary by protocol:
  * **Polymarket**: `<marketAddress>:Polymarket:<exchangeAddress>:<networkId>` (e.g., `0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137`)
  * **Kalshi**: `<marketSlug>:Kalshi` (e.g., `KXMVECROSSCATEGORY-S2026A4A05B370DF-F1FBA451AA9:Kalshi`)
* **Outcome-level OHLC data**: Separate price and liquidity metrics for `outcome0` and `outcome1`
* **Detailed market microstructure**: Includes bid/ask prices, spreads, and 2% depth metrics
* **Volume breakdown**: Track buys, sells, and total volume in USD, collateral tokens, and shares
* **Time-series format**: Each bar has a timestamp (`t`) representing the period start
* **Multiple resolutions**: From 1-minute to 1-week intervals for granular or aggregate analysis

## Troubleshooting Tips

> [accordion] Why don't outcome prices sum to 1.00?
>
> In real markets, outcome prices may not sum exactly to 1.00 due to bid/ask spreads, liquidity constraints, and market inefficiencies. The sum typically ranges from 0.98 to 1.02. Large deviations may indicate arbitrage opportunities or data issues.

> [accordion] What's the difference between volumeUsd, volumeShares, and volumeCollateralToken?
>
> * `volumeUsd`: Trading volume denominated in US dollars
> * `volumeShares`: Volume measured in outcome token shares
> * `volumeCollateralToken`: Volume in the market's collateral token (e.g., USDC)
>
> All three represent the same trading activity in different units. Use USD for cross-market comparison.

> [accordion] How do I calculate the bid/ask spread?
>
> Spread = `askUsd.c` - `bidUsd.c` for the close of each bar. A wider spread indicates lower liquidity or higher market uncertainty. Monitor spreads to assess market health and trading conditions.

> [accordion] What does twoPercentBidDepthUsd measure?
>
> This measures the total USD value of bid orders within 2% of the best bid price. It's a measure of order book depth and liquidity resilience. Higher values mean the market can absorb larger trades without significant price impact.

> [accordion] Why might some outcome fields be null?
>
> Some fields like `liquidityUsd`, `bidUsd`, and depth metrics may be null for older data or during periods when orderbook snapshots weren't available. Always check for null values before processing these fields.

> [accordion] How should I interpret high/low vs open/close in OHLC?
>
> * `o` (open): Value at the start of the bar period
> * `h` (high): Maximum value during the period
> * `l` (low): Minimum value during the period
> * `c` (close): Value at the end of the period
>
> For price data, this shows volatility. For liquidity, it shows liquidity fluctuations.

> [accordion] What does allTimeVolumeUsd represent?
>
> This is the cumulative volume for the market from inception up to the close of this bar. It's useful for tracking market maturity and total activity. Compare it to `volumeUsd` in the bar to understand what percentage of total volume occurred in that period.

### Related Recipes

* [Prediction Event Dashboard](https://docs.codex.io/recipes/predictions/event-dashboard.md): Use market bars for the single-market drill-down chart
* [Prediction Charts](https://docs.codex.io/recipes/predictions/charts.md): Render outcome probability candlesticks, bid/ask spreads, and volume overlays


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.