Skip to main content
TL;DR: Added tokenAmountUSD and percentageOfTotalSupply fields to both /api/2/token/holder-positions and /api/2/token/trader-positions endpoints.

​
New Fields for Holder & Trader Positions

Both the Get Token Holder Positions and Get Token Trader Positions endpoints now include two new fields to provide better insights into holder distribution:

​
New Response Fields

FieldTypeDescription
tokenAmountUSDstringToken balance value in USD (tokenAmount × current price)
percentageOfTotalSupplystringPercentage of total supply held by this wallet

​
Example Response

{
  "data": [
    {
      "chainId": "evm:1",
      "walletAddress": "0xad6dc16e2b447d3941a531ae70b1e179df7ed17e",
      "tokenAddress": "0x68bbed6a47194eff1cf514b50ea91895597fc91e",
      "tokenAmount": "1000000",
      "tokenAmountRaw": "1000000000000000000000000",
      "tokenAmountUSD": "50000.50",
      "percentageOfTotalSupply": "0.5",
      "pnlUSD": "12500.25",
      "buys": 5,
      "sells": 2,
      ...
    }
  ]
}

​
Use Cases

  • Portfolio Valuation: Instantly get the USD value of any holder’s position without additional price lookups
  • Whale Detection: Quickly identify wallets holding significant percentages of total supply
  • Distribution Analysis: Analyze token concentration across top holders

​
Affected Endpoints

Both fields are calculated using the token’s current price and total supply. If price data is unavailable, tokenAmountUSD will be “0”. If total supply is zero or unavailable, percentageOfTotalSupply will be “0”.