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

# predictionTraders

> Returns prediction traders 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>

<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.
    predictionTraders(
      input: PredictionTradersInput!
    ): [PredictionTrader!]!
  }

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

  input PredictionTradersInput {
    traderIds: [String!]!
  }
  ```
</div>

## Query Example

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

Query comprehensive performance statistics about a specific trader:

```graphql theme={null}
{
  predictionTraders(input: { 
    traderIds: ["0x02227b8f5a9636e895607edd3185ed6ee5598ff7:Polymarket"] 
  }) {
    alias
    protocol
    totalTradesCount
    totalVolumeUsd
    totalVolumeCT
    allTimeProfitUsd
    allTimeProfitCT
    biggestWinUsd
    biggestLossCT
    activeMarketsCount
    firstTradeTimestamp
    lastTradeTimestamp
  }
}
```

```json Example response theme={null}
{
  "data": {
    "predictionTraders": [
      {
        "alias": "HorizonSplendidView",
        "totalTradesCount": 3891,
        "totalVolumeUsd": "21346770.014588",
        "totalVolumeCT": "21347078.158539",
        "allTimeProfitUsd": "1710754.682204",
        "allTimeProfitCT": "1710624.919679",
        "biggestWinUsd": "2369172.875606",
        "biggestLossCT": "1319295.162985",
        "activeMarketsCount": 3,
        "firstTradeTimestamp": 1770564381,
        "lastTradeTimestamp": 1773276976
      }
    ]
  }
}
```

## Usage Guidelines

* **Trader ID format**: `<address>:<protocol>` (e.g., `0x02227b8f5a9636e895607edd3185ed6ee5598ff7:Polymarket`)
* **USD vs CT fields**: USD values are denominated in dollars, CT values in Conditional Tokens. For USDC markets, these are typically 1:1
* **Monetary precision**: All monetary values returned as strings to maintain precision
* **Timestamps**: Unix timestamps in seconds (convert with `new Date(timestamp * 1000)`)
* **Batch queries**: Query up to 100 traders in a single request for leaderboards
* **Linked addresses**: Track traders using multiple wallets via `linkedAddresses` field

## Troubleshooting

<AccordionGroup>
  <Accordion title="Why is a trader ID returning null or empty results?">
    If a trader ID returns no results, verify:

    * The trader ID format matches the protocol (Ethereum address for Polymarket)
    * The trader has actually made trades on the platform
    * The trader ID hasn't been mistyped (addresses are case-insensitive but must be valid hex)

    Try querying a known active trader first to confirm your API setup is working correctly.
  </Accordion>

  <Accordion title="What's the difference between USD and CT values?">
    **USD values** represent the dollar value of trades, while **CT (Conditional Token) values** represent the native token amounts. For most Polymarket markets using USDC, these values are identical. However:

    * CT values represent the raw blockchain token amounts
    * USD values are the dollar-equivalent at the time of trade
    * In USDC markets, 1 CT = 1 USD

    Use USD values for financial reporting and CT values when analyzing on-chain activity.
  </Accordion>

  <Accordion title="Why are some traders missing alias or profile information?">
    Not all traders set up public profiles on prediction market platforms. Fields like `alias`, `profileImageUrl`, and `profileUrl` are optional and may be null for traders who:

    * Haven't created a profile
    * Prefer to trade anonymously
    * Are using the platform programmatically

    The `primaryAddress` and `venueTraderId` are always available as fallback identifiers.
  </Accordion>

  <Accordion title="How do I interpret negative profit values?">
    Negative values in `allTimeProfitUsd` or `allTimeProfitCT` indicate the trader has net losses across all their resolved positions. This is calculated as:

    **Total Profit = (Winnings from resolved positions) - (Total amount spent on positions)**

    Note that this only includes resolved markets. Active positions are not factored into profit calculations until they settle.
  </Accordion>

  <Accordion title="Why might totalVolumeUsd differ from totalVolumeCT?">
    While typically identical for USDC-based markets, these values can differ when:

    * Markets use different token denominations
    * Currency conversion rates have changed over time
    * The platform uses different pricing mechanisms

    For Polymarket (USDC-based), expect these values to match. Significant differences may indicate data inconsistencies worth investigating.
  </Accordion>

  <Accordion title="What does activeMarketsCount represent?">
    `activeMarketsCount` shows how many prediction markets the trader currently has open positions in. This number:

    * Only counts markets that haven't resolved yet
    * Includes any market where the trader holds conditional tokens
    * Decreases when markets resolve or when the trader exits all positions

    A high active markets count suggests an actively diversified trader.
  </Accordion>

  <Accordion title="How frequently is trader data updated?">
    Trader statistics are updated in near real-time as trades occur on the blockchain. However:

    * There may be a 1-5 minute delay for data indexing
    * Profit calculations update when markets resolve
    * Profile information (alias, images) may take longer to sync if changed

    For high-frequency trading applications, expect metrics like `totalTradesCount` and `totalVolumeUsd` to be current within a few minutes of blockchain confirmation.
  </Accordion>
</AccordionGroup>