> ## 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. predictionTraderMarketsStats query reference: arguments and response fields.

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

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

## 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!]
}
```

## Example: Get all market statistics for a trader

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

```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`](https://docs.codex.io/api-reference/queries/predictiontraders) or [`filterPredictionTraders`](https://docs.codex.io/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`](https://docs.codex.io/api-reference/enums/predictiontradermarketpnlstatus) enum for all possible PnL status values and their meanings.

### Troubleshooting Tips

> [accordion] 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] 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] 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] 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.

### Related Recipes

* [Prediction Traders](https://docs.codex.io/recipes/predictions/traders.md): Use as a simpler alternative to filterPredictionTraderMarkets for trader position lists


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