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

# predictionTraderMarketsStats

> Returns per-market performance stats for a specific trader.

<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.
    predictionTraderMarketsStats(
      input: PredictionTraderMarketsStatsInput!
    ): PredictionTraderMarketsStatsConnection!
  }

  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 PredictionTraderMarketPnlStatus {
    WIN
    LOSS
    NEUTRAL
  }

  type PredictionTraderOutcomeStats {
    outcomeId: String!
    sharesHeld: String!
    actualSharesHeld: String!
    avgEntryPriceUsd: String!
    avgEntryPriceCT: String!
    costBasisUsd: String!
    costBasisCT: String!
    buys: Int!
    sells: Int!
    buyVolumeUsd: String!
    sellVolumeUsd: String!
    buyVolumeCT: String!
    sellVolumeCT: String!
    buyVolumeShares: String!
    sellVolumeShares: String!
    realizedPnlUsd: String!
    realizedPnlCT: String!
    pnlStatus: PredictionTraderMarketPnlStatus!
    firstTradeTimestamp: Int!
    lastTradeTimestamp: Int!
  }

  type PredictionTraderMarketStats {
    traderId: String!
    marketId: String!
    predictionMarket: PredictionMarket
    hasOpenPosition: Boolean!
    outcome0Stats: PredictionTraderOutcomeStats!
    outcome1Stats: PredictionTraderOutcomeStats!
    createdAt: Int!
    updatedAt: Int!
  }

  type PredictionTraderMarketsStatsConnection {
    items: [PredictionTraderMarketStats!]!
    cursor: String
  }

  input PredictionTraderMarketsStatsInput {
    traderId: String!
    limit: Int
    cursor: String
    marketIds: [String!]
  }
  ```
</div>

## Example: Get all market statistics for a trader

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

```graphql theme={null}
{
  predictionTraderMarketsStats(
    input: {
      traderId: "0x6904db029589e17f69209646381b6d663d695b63:Polymarket"
      limit: 20
    }
  ) {
    items {
      marketId
      hasOpenPosition
      predictionMarket {
        protocol
        question
        outcomeLabels
        closesAt
        resolvedAt
        winningOutcomeId
      }
      outcome0Stats {
        outcomeId
        sharesHeld
        avgEntryPriceUsd
        costBasisUsd
        buys
        sells
        buyVolumeUsd
        sellVolumeUsd
        realizedPnlUsd
        pnlStatus
        firstTradeTimestamp
        lastTradeTimestamp
      }
      outcome1Stats {
        outcomeId
        sharesHeld
        avgEntryPriceUsd
        costBasisUsd
        buys
        sells
        buyVolumeUsd
        sellVolumeUsd
        realizedPnlUsd
        pnlStatus
      }
      createdAt
      updatedAt
    }
    cursor
  }
}
```

```json Example Response (truncated) theme={null}
{
  "data": {
    "predictionTraderMarketsStats": {
      "items": [
        {
          "marketId": "0xff0cfa9506cfa95759e4c7591654195bd26e3011f9882b51439135e04f2b69f1:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
          "hasOpenPosition": false,
          "predictionMarket": {
            "protocol": "POLYMARKET",
            "question": "Will Tunisia win the 2026 FIFA World Cup?",
            "outcomeLabels": [
              "Yes",
              "No"
            ],
            "closesAt": 1784505600,
            "resolvedAt": null,
            "winningOutcomeId": null
          },
          "outcome0Stats": {
            "outcomeId": "86035858416252385053603758548087253570549129844230230783932738372075949702177:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
            "sharesHeld": "0",
            "avgEntryPriceUsd": "0",
            "costBasisUsd": "0",
            "buys": 0,
            "sells": 0,
            "buyVolumeUsd": "0",
            "sellVolumeUsd": "0",
            "realizedPnlUsd": "0",
            "pnlStatus": "NEUTRAL",
            "firstTradeTimestamp": 0,
            "lastTradeTimestamp": 0
          },
          "outcome1Stats": {
            "outcomeId": "110028171623846551687151479494325822981244001939750602839571004785511377900325:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
            "sharesHeld": "0.008",
            "avgEntryPriceUsd": "0.997880",
            "costBasisUsd": "0.00798303846851751",
            "buys": 1,
            "sells": 1,
            "buyVolumeUsd": "43.994525",
            "sellVolumeUsd": "43.946115",
            "realizedPnlUsd": "-0.040427",
            "pnlStatus": "LOSS"
          },
          "createdAt": 1770982346,
          "updatedAt": 1771006584
        }
        // ... 19 more results
      ],
      "cursor": "{\"cTraderId\":{\"S\":\"0x6904db029589e17f69209646381b6d663d695b63:Polymarket\"},\"cMarketId\":{\"S\":\"0x298157e618b5729dafd742eec9b21e040a13da0bb09ff1fa4492360c347e3824:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137\"}}"
    }
  }
}
```

## Example: Filter trader stats for specific markets

```graphql theme={null}
{
  predictionTraderMarketsStats(
    input: {
      traderId: "0x6904db029589e17f69209646381b6d663d695b63:Polymarket"
      marketIds: [
        "0xff0cfa9506cfa95759e4c7591654195bd26e3011f9882b51439135e04f2b69f1:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
        "0x84edef36bded182da6a395ac6c785dba8f3e09b6c5ad041385b2042536cbef25:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"
      ]
      limit: 10
    }
  ) {
    items {
      marketId
      hasOpenPosition
      predictionMarket {
        question
        outcomeLabels
        resolvedAt
        winningOutcomeId
      }
      outcome0Stats {
        sharesHeld
        realizedPnlUsd
        pnlStatus
      }
      outcome1Stats {
        sharesHeld
        realizedPnlUsd
        pnlStatus
      }
    }
  }
}
```

```json Example Response theme={null}
{
  "data": {
    "predictionTraderMarketsStats": {
      "items": [
        {
          "marketId": "0xff0cfa9506cfa95759e4c7591654195bd26e3011f9882b51439135e04f2b69f1:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
          "hasOpenPosition": false,
          "predictionMarket": {
            "question": "Will Tunisia win the 2026 FIFA World Cup?",
            "outcomeLabels": [
              "Yes",
              "No"
            ],
            "resolvedAt": null,
            "winningOutcomeId": null
          },
          "outcome0Stats": {
            "sharesHeld": "0",
            "realizedPnlUsd": "0",
            "pnlStatus": "NEUTRAL"
          },
          "outcome1Stats": {
            "sharesHeld": "0.008",
            "realizedPnlUsd": "-0.040427",
            "pnlStatus": "LOSS"
          }
        },
        {
          "marketId": "0x84edef36bded182da6a395ac6c785dba8f3e09b6c5ad041385b2042536cbef25:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
          "hasOpenPosition": true,
          "predictionMarket": {
            "question": "Will Iran win the 2026 FIFA World Cup?",
            "outcomeLabels": [
              "Yes",
              "No"
            ],
            "resolvedAt": null,
            "winningOutcomeId": null
          },
          "outcome0Stats": {
            "sharesHeld": "0",
            "realizedPnlUsd": "0",
            "pnlStatus": "NEUTRAL"
          },
          "outcome1Stats": {
            "sharesHeld": "6.012",
            "realizedPnlUsd": "-0.032802",
            "pnlStatus": "LOSS"
          }
        }
      ]
    }
  }
}
```

### Usage Guidelines

* The `traderId` format is `<address>:<protocol>` (e.g., `0x6904db029589e17f69209646381b6d663d695b63:Polymarket`)
* Use this query to analyze a trader's performance across all markets they've participated in
* Returns per-market breakdowns showing positions, costs, volumes, and realized profits for each outcome
* Find trader IDs using [`predictionTraders`](/api-reference/queries/predictiontraders) or [`filterPredictionTraders`](/api-reference/queries/filterpredictiontraders)
* Optionally filter results to specific markets using the `marketIds` array
* `hasOpenPosition` indicates whether the trader currently holds shares in any outcome for this market
* Returns paginated results - use `cursor` for pagination through large position lists
* Stats are separated into `outcome0Stats` and `outcome1Stats` for binary markets

### Understanding Trader Market Statistics

* Positions are tracked separately for each outcome (outcome0 and outcome1 in binary markets)
* `realizedPnlUsd` shows profit/loss from closed positions only (not unrealized gains on open positions)
* All volume and PnL metrics are available in both USD and CT (Collateral Token) units

**PnL Status Values**:

See the [`PredictionTraderMarketPnlStatus`](/api-reference/enums/predictiontradermarketpnlstatus) enum for all possible PnL status values and their meanings.

### Troubleshooting Tips

<AccordionGroup>
  <Accordion title="Why are some outcome stats showing zero values?">
    If a trader only traded one side of a binary market, the other outcome will show zeros for all metrics. For example, if a trader only bought "Yes" shares, `outcome1Stats` (the "No" side) will have:

    * `sharesHeld: "0"`
    * `buys: 0`, `sells: 0`
    * `realizedPnlUsd: "0"`
    * `pnlStatus: "NEUTRAL"`

    This is normal behavior - traders often take positions on only one outcome per market.
  </Accordion>

  <Accordion title="What's the difference between realized and unrealized PnL?">
    The `realizedPnlUsd` field shows only profit/loss from shares that have been sold (closed positions). It does NOT include unrealized PnL from shares still held (`sharesHeld > 0`). To calculate total PnL including unrealized gains/losses, you need to:

    1. Get current market prices for the outcome
    2. Calculate unrealized PnL: `(current_price - avgEntryPriceUsd) * sharesHeld`
    3. Add to `realizedPnlUsd`

    For resolved markets where the trader held shares to resolution, the payout is reflected in `realizedPnlUsd` after settlement.
  </Accordion>

  <Accordion title="Why is pnlStatus showing WIN but realizedPnlUsd is zero?">
    The `pnlStatus` reflects the overall profit/loss status for that outcome, including both realized and unrealized PnL. If a trader has an open position with unrealized gains, `pnlStatus` can be `WIN` while `realizedPnlUsd` is still `"0"` (meaning they haven't sold yet to realize the profit).

    Similarly, after a market resolves favorably, `pnlStatus` will be `WIN` even before settlement is processed.
  </Accordion>

  <Accordion title="What does avgEntryPriceUsd represent for closed positions?">
    The `avgEntryPriceUsd` is the weighted average price paid across all buy transactions for that outcome. This value persists even after shares are sold, allowing you to understand the trader's historical entry price. Combined with `sellVolumeUsd` and `sellVolumeShares`, you can calculate the trader's average exit price.
  </Accordion>
</AccordionGroup>

### Related Recipes

* [Prediction Traders](/recipes/predictions/traders): Use as a simpler alternative to filterPredictionTraderMarkets for trader position lists