Top Trader Wallets for Token Query

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
• MEGAETH_MAINNET
• OPTIMISM_MAINNET
• POLYGON_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

chain_name · enum · required

Blockchain network to filter events

Type: ChainNameUpnl

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