> ## 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. Reference for the predictionTraders 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).

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

## Query Example

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

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

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


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