Get top trading 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. This documentation follows our standard streaming API structure.

Credit Cost

TBD

Supported Chains

• Base Mainnet
• BSC Mainnet
• Ethereum Mainnet
• Gnosis Mainnet
• Polygon Mainnet
• Optimism 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
    volume
    balance
    pnl_realized_usd
    pnl_unrealized_usd
  }
}

Complete Query

query {
 upnlForToken(
    chain_name: ETH_MAINNET
    token_address: "0x7ABc8A5768E6bE61A6c693a6e4EAcb5B60602C4D"
  ) {
    token
    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": "0x7abc8a5768e6be61a6c693a6e4eacb5b60602c4d",
        "address": "0x91d40e4818f4d4c57b4578d9eca6afc92ac8debe",
        "volume": 56708716,
        "transactions_count": 554,
        "pnl_realized_usd": -43239.81,
        "balance": 3.2944375440228563e+25,
        "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": "0x7abc8a5768e6be61a6c693a6e4eacb5b60602c4d",
        "address": "0xfe97b0c517a84f98fc6ede3cd26b43012d31992a",
        "volume": 39102028,
        "transactions_count": 241,
        "pnl_realized_usd": 8799.58,
        "balance": 3.2313896033867796e+26,
        "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	string	Token contract address, represented in lowercase with a 0x prefix
address	string	Wallet address of the token trader, also in lowercase with a 0x prefix
volume	BigInteger	Total volume of tokens transferred by this wallet in the past 30 days
transactions_count	integer	Number of transactions involving this wallet and token in the past 30 days
pnl_realized_usd	float	Realized profit or loss in USD from completed trades
balance	BigInteger	Current token balance in raw format (full decimal precision)
balance_pretty	string	Human-readable token balance formatted to 4 decimal places
pnl_unrealized_usd	float	Unrealized profit or loss in USD based on the current token price
contract_metadata	object	Contains metadata details for the token contract

GraphQL Playground