Nansen

Checking fund holdings

fund_token_balances

Read-only

Get the CURRENT token holdings aggregated (not per wallet) across Fund-labelled wallets only, per chain for all chains (default is ['all']) or specific chain(s). Funds are a separate cohort from Smart Money: use this for fund-only holdings questions, and smart_traders_and_funds_token_balances for Smart Money as a whole. This is a snapshot of now: it has no date range and no history, and it does not list individual fund wallets. Stablecoins, native tokens and tokens with less than minValueUsd (default $1,000) of combined Fund balance are excluded by default. The default sort is the largest absolute 24h balance change, increases and decreases together. Large percentage changes can come from small positions or one wallet, and balance changes alone do not prove purchases or sales. minValueUsd applies to the current balance, so a token that funds sold to below it does not show in decreases. Which arguments to use:

What funds are buying: balanceChange='increase', orderBy='balance_24h_percent_change', orderByDirection='DESC'.
What funds are trading: two calls, the buying call above and balanceChange='decrease', orderBy='balance_24h_percent_change', orderByDirection='ASC'.
What funds are holding: orderBy='value_usd', orderByDirection='DESC'.
Which tokens have the most fund holders: orderBy='holders_count', orderByDirection='DESC'.
Broad fund overview: also call with orderBy='value_usd' and with orderBy='holders_count', because the largest percentage changes can be small positions or one wallet.
Fund holdings of one token: do not use this tool. Use token_current_top_holders with labelType='top_100_holders' and includeLabels=['Fund'], then add up the balances. A sum of one page covers only the listed wallets.

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": {
      "request": "<request>"
    },
    "name": "fund_token_balances"
  }
}

Input Schema

Name	Required	Description	Default
`request`	Yes	Request for current token holdings aggregated across Fund wallets (v1beta1 API).

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 6, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnly/openWorld/non-destructive annotations, the description discloses that results are a now-snapshot with no history or date range, that data is aggregated rather than wallet-level, and that stablecoins, native tokens and sub-threshold balances are excluded by default. It also warns about interpretation pitfalls (percentage changes from tiny positions, balance changes not proving purchases/sales, minValueUsd applying to current balance so sold-down tokens vanish from decreases) — context an agent cannot obtain from annotations.

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 core scoping statement is front-loaded, and the bulleted argument recipes make the long text scannable rather than rambling. It is on the verbose side and repeats a few defaults already stated in the schema, but nearly every sentence carries decision-relevant information.

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?

With an output schema present, the description does not need to explain return values, and it still covers the behaviors that matter for correct invocation: aggregation level, snapshot semantics, default exclusions, sorting defaults and tool-selection boundaries. Nothing an agent needs in order to call this correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, and the description does add genuine meaning on top: the semantics of the default sort (largest absolute change, excluding zero-change tokens), the interaction between minValueUsd and decrease filtering, and intent-to-parameter mappings for orderBy/balanceChange/orderByDirection. It still restates some defaults already present in the schema (chains 'all', minValueUsd $1,000), which keeps it short of a 5.

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 opening sentence states a precise verb and resource (current token holdings), the aggregation scope (across Fund wallets, not per wallet), the grouping unit (per chain), and the default chain scope. It also explicitly distinguishes itself from the two nearest alternatives, smart_traders_and_funds_token_balances and token_current_top_holders, so an agent can route without opening any schema.

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

Usage Guidelines5/5

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

The 'Which arguments to use' block maps concrete user intents (what funds are buying, trading, holding, most holders, broad overview) to exact parameter combinations, and it names the anti-pattern case — single-token fund holdings — with the specific replacement tool and its parameters. Both when-to-use and when-not-to-use are covered explicitly.

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

All Nansen 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.

Resources

Need Help?