Skip to main content
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
Chain name to filter events (e.g., BASE_MAINNET, ETH_MAINNET, BSC_MAINNET)Available values: BASE_MAINNET, BSC_MAINNET, ETH_MAINNET, GNOSIS_MAINNET, OPTIMISM_MAINNET, POLYGON_MAINNET, SOLANA_MAINNET
​
token_address
string
required
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

​
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