Vike Data API

Token Holders

token_holders

Read-onlyIdempotent

Top holders of an ERC-20 token by cumulative net inflow USD. Returns wallet, net flow USD, volume USD, tx count, first/last seen dates, and known labels. Use when the user asks 'top holders of X' or 'who holds the most of token Y'. sort='flow' (default) ranks by cumulative net inflow USD, a flow and not a holding. sort='balance' ranks by the on-chain balanceOf among candidate wallets chosen by net inflow and by volume (a holder outside both is not in it) and adds balance, value_usd, supply_pct, balance_basis, balance_approximate and candidate_coverage to each row; balance_basis is 'chain' for a balance read from the chain ('unsupported' means the row is still ranked by flow, as for a chain's native coin), balance_approximate is true when a candidate's balance could not be read or the total supply is unknown, and candidate_coverage is the share of the total supply the candidates' balances add up to. sort='balance' is not available on every chain (the error names it). exclude_exchanges=true drops wallets labelled as an exchange.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "token_address": "<token_address>"
    },
    "name": "token_holders"
  }
}

Input Schema

Name	Required	Description	Default
`sort`	No	flow = cumulative net inflow USD (default); balance = on-chain balanceOf among candidate wallets	flow
`chain`	No	Chain (default ethereum)	ethereum
`limit`	No	Max holders (default 10, max 50)
`token_address`	Yes	ERC-20 token contract address (0x-prefixed)
`exclude_exchanges`	No	Drop wallets labelled as an exchange (default false)

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 26, 2026

addedInput schema / properties / exclude_exchanges

Added value: +{
+  "default": false,
+  "description": "Drop wallets labelled as an exchange (default false)",
+  "type": "boolean"
+}

addedInput schema / properties / sort

Added value: +{
+  "default": "flow",
+  "description": "flow = cumulative net inflow USD (default); balance = on-chain balanceOf among candidate wallets",
+  "enum": [
+    "flow",
+    "balance"
+  ],
+  "type": "string"
+}

First observedOct 25, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the read-only, idempotent annotations, the description discloses important behavioral traits: balance sorting is not available on every chain and the error names it, balance_basis can be 'unsupported' or approximate, candidate_coverage indicates supply coverage, and exclude_exchanges filters labelled exchange wallets. These are substantive operational details an agent would otherwise not know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose, outputs, and usage, and every major detail is relevant. However, the long sentence covering balance sorting and its caveats is dense and could be structured more readably, even if it is not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema and complex sort behavior, but the description explains returned fields, ranking semantics, caveats for balance mode, chain availability errors, and exchange filtering. An agent has enough information to call the tool correctly and interpret the main behavioral constraints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is already 100%, the description adds significant meaning beyond the schema. It explains that 'flow' is cumulative net inflow rather than holdings, details how 'balance' ranks candidates and what extra fields appear, clarifies when balance may be approximate or unsupported, and explains exclude_exchanges.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: top holders of an ERC-20 token by cumulative net inflow USD. It clearly differentiates the tool's two ranking modes and the returned fields, so an agent can distinguish it from sibling tools like token_transfers or wallet_token_balances without needing to inspect schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit user-intent examples ('top holders of X' or 'who holds the most of token Y') and explains when to use sort='flow' versus sort='balance'. It does not name alternative sibling tools or state when not to use this tool, but the usage context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Vike Data API tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.