token_rank_single¶

Returns the community rank and top holders for a specific token, identified by contract address and network. Unlike token_rank_list which returns ranked lists for discovery, this tool deep-dives into a single token — surfacing its strongest holders with full wallet-level intelligence including balance, wallet age, transaction count, and global rank.

Use this when you need to understand who holds a token and how strong those holders are.

MCP Endpoint: https://prediction.mcp.chainaware.ai/sse

---

Supported Networks¶

---

Input Schema¶

---

Output Schema¶

{
  "message": "string",
  "data": {
    "contract": {
      "contractAddress": "string",
      "contractName": "string",
      "ticker": "string",
      "chain": "string",
      "category": "string",
      "type": "string",
      "communityRank": 0,
      "normalizedRank": 0,
      "totalHolders": 0,
      "lastProcessedAt": "ISO-8601",
      "createdAt": "ISO-8601",
      "updatedAt": "ISO-8601"
    },
    "topHolders": [
      {
        "contractAddress": "string",
        "Holder": {
          "walletAddress": "string",
          "chain": "string",
          "balance": "string",
          "walletAgeInDays": 0,
          "transactionsNumber": 0,
          "totalPoints": 0.0,
          "globalRank": 0
        }
      }
    ]
  }
}

---

Key Output Fields Explained¶

data.contract — Token Summary¶

data.topHolders[] — Strongest Holders¶

Each entry contains a Holder object with full wallet-level intelligence:

globalRank Interpretation¶

---

Code Examples¶

Node.js¶

const result = await client.callTool({
  name: "token_rank_single",
  arguments: {
    contract_address: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    network: "ETH"
  }
});

const { contract, topHolders } = result.data;
console.log(`${contract.contractName} (${contract.ticker})`);
console.log(`Community Rank: ${contract.communityRank}`);
console.log(`Total Holders: ${contract.totalHolders}`);

topHolders.forEach((entry, i) => {
  const h = entry.Holder;
  console.log(
    `  ${i + 1}. ${h.walletAddress} — ` +
    `Balance: ${h.balance}, Global Rank: ${h.globalRank}, Age: ${h.walletAgeInDays}d`
  );
});

Python¶

result = await session.call_tool("token_rank_single", {
    "contract_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "network": "ETH"
})

contract = result["data"]["contract"]
print(f"{contract['contractName']} ({contract['ticker']})")
print(f"Community Rank: {contract['communityRank']}")
print(f"Total Holders: {contract['totalHolders']}")

for i, entry in enumerate(result["data"]["topHolders"]):
    h = entry["Holder"]
    print(
        f"  {i+1}. {h['walletAddress']} — "
        f"Balance: {h['balance']}, Global Rank: {h['globalRank']}, Age: {h['walletAgeInDays']}d"
    )

Example Agent Prompts¶

"What is the community rank for USDT on Ethereum?"
"Who are the top holders of 0xdAC17F958D2ee523a2206206994597C13D831ec7 on ETH?"
"Show me the best holders of this Solana token."
"How strong is the holder base of this contract on BNB?"
"Are the top holders of this token experienced or new wallets?"
"Compare holder quality: is this token held by whales or retail?"
"Deep-dive into the community quality of this BASE token."

---

Use Cases¶

• Token due diligence — before investing, check whether a token is held by experienced, high-rank wallets or fresh/suspicious ones
• Whale analysis — identify top holders and assess whether they are long-term participants or short-term flippers
• Community health monitoring — track whether a token's top holders are strengthening or weakening over time
• Governance intelligence — understand who the most influential holders are for DAO voting and proposals
• Exchange listing decisions — evaluate holder quality as a factor in token listing approvals
• Portfolio risk assessment — pair with predictive_rug_pull on the same contract for a complete safety + community quality picture

---

Composability¶

token_rank_single pairs naturally with other ChainAware tools:

• Run predictive_behaviour on a top holder's walletAddress to get their full behavioural profile
• Run predictive_fraud on top holders to check whether any major holders are fraud-flagged
• Use token_rank_list first to discover tokens by category, then token_rank_single to deep-dive into the best candidates

---

Error Codes¶

---

Further Reading¶

• Token Rank Guide — TokenRank system: community strength scoring, holder analysis, and global rank
• Prediction MCP for AI Agents

---

See also: Prediction MCP Overview | token_rank_list | predictive_fraud