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

# predictionTraderBars

> Returns bar data for a prediction trader over a time range.

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

<Info>
  **Kalshi does not provide trader data**. These endpoints only work with Polymarket data. Kalshi's API does not expose individual trader information due to privacy considerations on their regulated exchange.
</Info>

<div data-generated>
  ## GraphQL

  ```
  type Query {
    # Requires a Growth or Enterprise plan.
    predictionTraderBars(
      input: PredictionTraderBarsInput!
    ): PredictionTraderBarsResponse!
  }

  enum PredictionProtocol {
    POLYMARKET
    KALSHI
  }

  type PredictionTrader {
    id: String!
    protocol: PredictionProtocol!
    venueTraderId: String!
    alias: String
    primaryAddress: String
    linkedAddresses: [String!]
    profileImageUrl: String
    profileUrl: String
    totalTradesCount: Int!
    totalVolumeUsd: String!
    totalVolumeCT: String!
    firstTradeTimestamp: Int!
    lastTradeTimestamp: Int!
    biggestWinUsd: String!
    biggestWinCT: String!
    biggestLossUsd: String!
    biggestLossCT: String!
    allTimeProfitUsd: String!
    allTimeProfitCT: String!
    activeMarketsCount: Int!
    labels: [String!]
    createdAt: Int!
    updatedAt: Int!
  }

  type PredictionTraderBar {
    t: Int!
    trades: Int
    buys: Int
    sells: Int
    uniqueMarkets: Int
    volumeUsd: String
    buyVolumeUsd: String
    sellVolumeUsd: String
    volumeCT: String
    buyVolumeCT: String
    sellVolumeCT: String
    wins: Int
    losses: Int
    realizedPnlUsd: String
    realizedPnlCT: String
    cumulativeRealizedPnlUsd: String
    cumulativeRealizedPnlCT: String
  }

  type PredictionTraderBarsResponse {
    traderId: String!
    trader: PredictionTrader
    bars: [PredictionTraderBar!]!
  }

  enum PredictionTraderBarsResolution {
    hour1
    hour4
    day1
    week1
  }

  input PredictionTraderBarsInput {
    traderId: String!
    from: Int!
    to: Int!
    resolution: PredictionTraderBarsResolution!
    countback: Int
    removeEmptyBars: Boolean
  }
  ```
</div>

## Example Query

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

```graphql theme={null}
{
  predictionTraderBars(input: {
    traderId: "0x02227b8f5a9636e895607edd3185ed6ee5598ff7:Polymarket"
    from: 1772658000
    to: 1773349275
    resolution: day1
  }) {
    bars {
      t
      trades
      buys
      sells
      uniqueMarkets
      volumeUsd
      buyVolumeUsd
      sellVolumeUsd
      wins
      losses
      realizedPnlUsd
      cumulativeRealizedPnlUsd
    }
  }
}
```

```json Example Response (truncated) theme={null}
{
  "data": {
    "predictionTraderBars": {
      "bars": [
        {
          "t": 1772582400,
          "trades": 511,
          "buys": 510,
          "sells": 1,
          "uniqueMarkets": 1,
          "volumeUsd": "4708891.840898",
          "buyVolumeUsd": "1169859.482646",
          "sellVolumeUsd": "3539032.358252",
          "wins": 1,
          "losses": 0,
          "realizedPnlUsd": "2369172.875606",
          "cumulativeRealizedPnlUsd": "2369172.875606"
        },
        {
          "t": 1772755200,
          "trades": 273,
          "buys": 273,
          "sells": 0,
          "uniqueMarkets": 1,
          "volumeUsd": "509897.415985",
          "buyVolumeUsd": "509897.415985",
          "sellVolumeUsd": "0",
          "wins": 0,
          "losses": 0,
          "realizedPnlUsd": "0",
          "cumulativeRealizedPnlUsd": "2369172.875606"
        },
        {
          "t": 1772841600,
          "trades": 1,
          "buys": 0,
          "sells": 1,
          "uniqueMarkets": 1,
          "volumeUsd": "0",
          "buyVolumeUsd": "0",
          "sellVolumeUsd": "0",
          "wins": 0,
          "losses": 1,
          "realizedPnlUsd": "-509897.415985",
          "cumulativeRealizedPnlUsd": "1859275.4596209999"
        }
        // ... 5 more bars
      ]
    }
  }
}
```

## Usage Guidelines

Bar data provides time-series aggregates for individual trader activity. Each bar represents a time period and tracks trading behavior, volume, profit/loss, and market participation for a specific trader.

Key characteristics:

* **Trader ID format**: The `traderId` format is `<address>:<protocol>` (e.g., `0x742d35cc6634c0532925a3b844bc9e7595f0beb6:Polymarket`)
* **Trading activity metrics**: Count trades, buys, sells, and unique markets traded
* **Volume tracking**: Monitor trading volume in both USD and collateral tokens (CT)
* **Performance analysis**: Track realized PnL (profit and loss) and cumulative performance
* **Win/loss tracking**: Count profitable vs unprofitable positions resolved during the period
* **Time-series format**: Each bar has a timestamp (`t`) representing the period start
* **Coarser resolutions**: Available in hourly, 4-hour, daily, and weekly intervals (no minute-level data)

## Troubleshooting Tips

<AccordionGroup>
  <Accordion title="Why are minute-level resolutions not available?">
    Trader bars are designed for analyzing trading patterns over longer periods. Minute-level granularity would produce sparse data for most traders and isn't useful for typical trader analysis. Use hourly or daily resolutions for meaningful insights.
  </Accordion>

  <Accordion title="What's the difference between realizedPnlUsd and cumulativeRealizedPnlUsd?">
    * `realizedPnlUsd`: Profit/loss from positions that were opened AND closed during this specific bar period
    * `cumulativeRealizedPnlUsd`: Total all-time realized PnL as of the end of this bar

    The cumulative value helps track overall trader performance, while the per-bar value shows period-specific gains/losses.
  </Accordion>

  <Accordion title="How are wins and losses calculated?">
    Wins and losses count the number of positions that were resolved (closed) during the bar period:

    * `wins`: Positions closed at a profit
    * `losses`: Positions closed at a loss

    Note: These only count resolved positions, not unrealized gains on open positions.
  </Accordion>

  <Accordion title="Why might volumeUsd and volumeCT have different values?">
    While often similar (especially for USDC-based markets), these can differ due to:

    * Exchange rate fluctuations if the collateral token isn't a stablecoin
    * Timing differences in data collection
    * Different calculation methodologies at the venue level

    For most Polymarket data, expect these to be nearly identical since USDC is the collateral.
  </Accordion>

  <Accordion title="What does uniqueMarkets count?">
    This counts the number of distinct prediction markets the trader participated in during the bar period. A high value indicates diversification, while a low value suggests focused trading on specific events.
  </Accordion>

  <Accordion title="Why are some bars showing zero wins and losses despite having trades?">
    Wins and losses only count when positions are fully closed and resolved. If a trader only opened new positions or partially closed existing ones during the bar period, trades will be non-zero but wins/losses will be zero.
  </Accordion>

  <Accordion title="How should I calculate a trader's win rate?">
    Win rate = `wins / (wins + losses)`. Only calculate this when `(wins + losses) > 0` to avoid division by zero. Note that win rate doesn't account for position sizing - a trader could have a high win rate but negative PnL if their losses are larger than their wins.
  </Accordion>
</AccordionGroup>

### Related Recipes

* [Prediction Traders](/recipes/predictions/traders): Chart cumulative P\&L, volume, and win/loss over time for trader profiles