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

ParameterTypeRequiredDescription
chain_nameenumYesChain name to filter events (e.g., BASE_MAINNET, ETH_MAINNET, BSC_MAINNET)
token_addressstringYesThe 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

FieldTypeDescription
tokenstringToken contract address, represented in lowercase with a 0x prefix
addressstringWallet address of the token trader, also in lowercase with a 0x prefix
volumeBigIntegerTotal volume of tokens transferred by this wallet in the past 30 days
transactions_countintegerNumber of transactions involving this wallet and token in the past 30 days
pnl_realized_usdfloatRealized profit or loss in USD from completed trades
balanceBigIntegerCurrent token balance in raw format (full decimal precision)
balance_prettystringHuman-readable token balance formatted to 4 decimal places
pnl_unrealized_usdfloatUnrealized profit or loss in USD based on the current token price
contract_metadataobjectContains metadata details for the token contract

​
GraphQL Playground