Top Trader Wallets for Token Query

This GraphQL query returns the top 20 trader wallets - ranked by trading volume over the last 30 days - for a specific token, along with detailed information about their holdings, transaction activity, and realized and unrealized profit/loss metrics.

Credit Cost

1 per call

Supported Chains

• BASE_MAINNET
• BSC_MAINNET
• ETH_MAINNET
• GNOSIS_MAINNET
• MEGAETH_MAINNET
• OPTIMISM_MAINNET
• POLYGON_MAINNET
• ROBINHOOD_MAINNET

Estimate your monthly cost for this API using the Pricing Calculator.

Parameters

chain_name · enum · required

Blockchain network to filter events

token_address · string · required

Token contract address on a supported DEX and chain

Query

You can query the upnlForToken endpoint to retrieve top wallet trading data.

query {
  upnlForToken(
    chain_name: ETH_MAINNET
    token_address: "0x7ABc8A5768E6bE61A6c693a6e4EAcb5B60602C4D"
  ) {
    volume
    wallet_address
    transactions_count
    balance
    contract_metadata {
      contract_name
      contract_address
      contract_decimals
      contract_ticker_symbol
    }
    token_address
    pnl_realized_usd
    pnl_unrealized_usd
    marketcap_usd
    balance_pretty
  }
}

Response Format

Here’s an example of the response data structure:

{
  "data": {
    "upnlForToken": [
      {
        "token_address": "0x7abc8a5768e6be61a6c693a6e4eacb5b60602c4d",
        "wallet_address": "0x91d40e4818f4d4c57b4578d9eca6afc92ac8debe",
        "volume": "56708716",
        "transactions_count": 554,
        "pnl_realized_usd": -43239.81,
        "balance": "32944375440228563000000000",
        "balance_pretty": "32944375.4402",
        "pnl_unrealized_usd": 535182,
        "contract_metadata": {
          "contract_address": "0x7ABc8A5768E6bE61A6c693a6e4EAcb5B60602C4D",
          "contract_name": "Covalent X Token",
          "contract_ticker_symbol": "CXT",
          "contract_decimals": 18
        }
      },
      {
        "token_address": "0x7abc8a5768e6be61a6c693a6e4eacb5b60602c4d",
        "wallet_address": "0xfe97b0c517a84f98fc6ede3cd26b43012d31992a",
        "volume": "39102028",
        "transactions_count": 241,
        "pnl_realized_usd": 8799.58,
        "balance": "323138960338677960000000000",
        "balance_pretty": "323138960.3387",
        "pnl_unrealized_usd": 6417132,
        "contract_metadata": {
          "contract_address": "0x7ABc8A5768E6bE61A6c693a6e4EAcb5B60602C4D",
          "contract_name": "Covalent X Token",
          "contract_ticker_symbol": "CXT",
          "contract_decimals": 18
        }
      }
    ]
  }
}

Field Descriptions

volume · string

Total volume of tokens transferred (string to avoid JS precision loss)

wallet_address · string

Wallet address of the token holder (lowercase with 0x prefix)

transactions_count · int

Total number of transactions

balance · string

Current token balance (string to avoid JS precision loss)

contract_metadata · object

Token contract metadata

Type: TokenContractMetadata

Show properties

contract_name · string

Name of the token contract

contract_address · string

Address of the token contract

contract_decimals · int

Number of decimal places for the token

contract_ticker_symbol · string

Ticker symbol of the token

token_address · string

Token contract address (lowercase with 0x prefix)

pnl_realized_usd · float

Realized profit and loss in USD

pnl_unrealized_usd · float

Unrealized profit and loss in USD

marketcap_usd · string

Market capitalization in USD

balance_pretty · string

Human-readable token balance with proper decimal places