Skip to main content

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.

This endpoint requires a Growth or Enterprise plan. Learn more.

​
Returns

​
TokenTopTradersConnection
TokenTopTradersConnection!
See TokenTopTradersConnection

​
Arguments

​
input
TokenTopTradersInput!
required
See TokenTopTradersInput

​
Example

Test this query in the Explorer → 
{
  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 (default pagination applies)
  • 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

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.
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.
Traders are ranked by total USD volume (volumeUsd), which is the sum of amountBoughtUsd and amountSoldUsd within the selected trading period.
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.
  • Detailed Token Page: Build a comprehensive token detail page with price, holders, trades, and real-time updates