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

# tokenTopTraders

> Returns a list of top traders for a given token. Reference for the tokenTopTraders query in the Codex API: arguments, response fields, and usage.

## GraphQL

```
type Query {
  # Requires a Growth or Enterprise plan.
  tokenTopTraders(
    input: TokenTopTradersInput!
  ): TokenTopTradersConnection!
}

enum TradingPeriod {
  DAY
  WEEK
  MONTH
  YEAR
}

enum WalletCategory {
  NORMIE
  TOKEN_CREATOR
  EXCHANGE
  DEFI_EXCHANGE
  PAIR
  PAIR_TOKEN_HOLDER
  POOL_AUTHORITY
  STAKING_VAULT
  NOTORIOUS
  BURN
  LOCKER
}

type WalletFunding {
  fundedByAddress: String!
  fundedByLabel: String
  fundedAt: Int!
  tokenAddress: String!
  networkId: Int!
  amount: String!
  transactionHash: String!
}

type WalletPolymarketProfile {
  proxyWallet: String!
  xUsername: String
  displayName: String
  pseudonym: String
  profileImageUrl: String
  verifiedBadge: Boolean
  displayUsernamePublic: Boolean
  fetchedAt: Int!
}

type Wallet {
  address: String!
  category: WalletCategory
  firstSeenTimestamp: Int
  firstFunding: WalletFunding
  identityLabels: [String!]
  avatarUrl: String
  displayName: String
  twitterId: String
  twitterUsername: String
  telegramId: String
  telegramUsername: String
  website: String
  discordId: String
  discordUsername: String
  githubId: String
  githubUsername: String
  farcasterId: String
  farcasterUsername: String
  description: String
  ethosScore: Int
  ethosLevel: String
  ethosVerified: Boolean
  tradeSourceIds: [String!]
  identitySource: String
  identityUpdatedAt: Int
  polymarket: WalletPolymarketProfile
  tokensCreatedCount: Int
  tokensMigratedCount: Int
}

type TokenTopTrader {
  walletAddress: String!
  tokenAddress: String!
  networkId: Int!
  tokenAmountBought: String!
  tokenAmountSold: String!
  amountBoughtUsd: String!
  amountSoldUsd: String!
  volumeUsd: String!
  realizedProfitUsd: String!
  realizedProfitPercentage: Float!
  singleTokenAcquisitionCostUsd: String!
  buys: Int!
  sells: Int!
  tokenBalance: String!
  firstTransactionAt: Int
  lastTransactionAt: Int!
  labels: [String!]!
  scammerScore: Int
  botScore: Int
  wallet: Wallet
}

type TokenTopTradersConnection {
  tokenAddress: String!
  networkId: Int!
  tradingPeriod: TradingPeriod!
  items: [TokenTopTrader]!
  offset: Int
}

enum TokenTopTradersRankingAttribute {
  realizedProfitUsd
  volumeUsd
}

enum RankingDirection {
  ASC
  DESC
}

input TokenTopTradersRanking {
  attribute: TokenTopTradersRankingAttribute!
  direction: RankingDirection!
}

input TokenTopTradersInput {
  tokenAddress: String!
  networkId: Int!
  tradingPeriod: TradingPeriod!
  ranking: TokenTopTradersRanking
  limit: Int
  offset: Int
}
```

### Example

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

```graphql theme={null}
{
  tokenTopTraders(
    input: {tokenAddress: "So11111111111111111111111111111111111111112", networkId: 1399811149, tradingPeriod: WEEK, limit: 10}
  ) {
    tokenAddress
    networkId
    tradingPeriod
    offset
    items {
      walletAddress
      tokenAmountBought
      tokenAmountSold
      amountBoughtUsd
      amountSoldUsd
      volumeUsd
      realizedProfitUsd
      realizedProfitPercentage
      singleTokenAcquisitionCostUsd
      buys
      sells
      tokenBalance
      firstTransactionAt
      lastTransactionAt
    }
  }
}
```

### Usage Guidelines

* Requires `tokenAddress`, `networkId`, and `tradingPeriod` (`DAY`, `WEEK`, `MONTH`, `YEAR`)
* Returns traders sorted by volume, with buy/sell breakdowns, realized P\&L, and current token balance
* Use `limit` to control how many traders are returned
* Use `offset` for pagination through the full list of top traders
* `realizedProfitUsd` and `realizedProfitPercentage` reflect closed P\&L from sells — unrealized gains on held tokens are not included
* `singleTokenAcquisitionCostUsd` shows the average cost basis per token for the trader

### Troubleshooting Tips

> [accordion] What does realizedProfitUsd measure?
>
> `realizedProfitUsd` tracks profit from tokens that have been sold — it compares the sell price to the acquisition cost. Tokens still held in the wallet (unrealized gains/losses) are not factored in. Use `tokenBalance` to see how much the trader is still holding.

> [accordion] How is the trading period applied?
>
> The `tradingPeriod` filters to trades within that window (e.g., `WEEK` = last 7 days). All metrics — volume, buys, sells, profit — are scoped to that period. A trader active over the past month won't appear in `DAY` results if they had no trades in the last 24 hours.

> [accordion] How are top traders ranked?
>
> Traders are ranked by total USD volume (`volumeUsd`), which is the sum of `amountBoughtUsd` and `amountSoldUsd` within the selected trading period.

> [accordion] Can I use this for wallet-level analysis?
>
> Yes. Each result includes `walletAddress`, so you can combine this with other queries like `balances` or `detailedWalletStats` to build a fuller profile of a token's most active traders.

### Related Recipes

* [Detailed Token Page](https://docs.codex.io/recipes/detailed-token-page.md): Build a comprehensive token detail page with price, holders, trades, and real-time updates


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