Top Trader Wallets for Token

This GraphQL query provides a list of wallets with the highest trading volume for a specific token over the last 30 days, along with detailed information about their holdings, transaction activity, realized and unrealized profit/loss metrics.

Credit Cost

TBD

Supported Chains

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

This query is currently in Beta. It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. No API credits are currently charged.

We welcome your feedback so please reach out to us directly to report issues or request features.

Parameters

Parameter	Type	Required	Description
chain_name	enum	Yes	Chain name to filter events (e.g., BASE_MAINNET, ETH_MAINNET, BSC_MAINNET)
token_address	string	Yes	The deployed token contract address to query

Query

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

Basic Query

query {
 upnlForToken(
    chain_name: ETH_MAINNET
    token_address: "0x7ABc8A5768E6bE61A6c693a6e4EAcb5B60602C4D"
  ) {
    token_address
    wallet_address
    volume
    balance
    pnl_realized_usd
    pnl_unrealized_usd
  }
}

Complete Query

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

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

Field	Type	Description
token_address	string	Token contract address (lowercase, 0x-prefixed)
wallet_address	string	Wallet address of the trader (lowercase, 0x-prefixed)
volume	string	Total token volume transferred in the past 30 days
transactions_count	integer	Transaction count for this wallet and token (past 30 days)
pnl_realized_usd	float	Realized PnL in USD from completed trades
balance	string	Current token balance in raw format
balance_pretty	string	Human-readable balance (4 decimal places)
pnl_unrealized_usd	float	Unrealized PnL in USD at the current token price
contract_metadata	object	Token contract metadata