The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Read the authenticated account's saved automatic feedback preference. Free; no report quota.
Before a new automatic report about useful Nansen friction, draft a concise
report without secrets or unnecessary conversation details and call this tool.
Enabled permits sending subject to host and local-deny controls and account
rollout. If off, unconfigured or unavailable, show the report and ask first.
Refusal, host denial or inability to ask means no submission. An explicit
request or approval permits only that report. Never enable the preference
automatically. Direct lasting changes to Superapp settings. Reads are fresh,
use this account only, and do not authorize another account or server key.
The description explains the capability, when to use it, and what to expect.
Inputs0/100
0 of 1 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Submit product feedback for the authenticated Nansen account. Costs zero credits, including with zero balance.
Send when the user requests or approves this report. Before a new automatic
report, call get_feedback_preferences for a fresh account preference. If it is off, unconfigured or
unavailable, show the report and ask before sending. If the user refuses or
you cannot ask, do not send. Enabled permits sending subject to host controls.
One report approval does not change the preference. Never enable it yourself.
Host denial means no submission. A feedback_not_enabled refusal means stop
automatic retries and tell the user the feature is not enabled for this
account. Approval and saved preferences do not override rollout.
Seven accepted reports per account per week across all clients, resetting Monday
00:00 UTC. Generate submission_id once per new report; reuse it and the exact
report for retries and re-invocations. Never replace an ID after a timeout.
Limits: description/goal/expected/observed/workaround 2,000 Unicode characters
each; endpoint/tool 256; 10 distinct request IDs of 128 characters; client
name/version 64; total JSON body 16 KiB UTF-8. Use category missing_capability
for a feature request or a product gap. Missing capabilities need no
endpoint, tool, or request ID. Omit secrets. Received means saved, not fixed.
Failures preserve recovery guidance. No alternate-account or server-key fallback.
Do not redirect failed submissions to unrelated feedback channels.
The description explains the capability, when to use it, and what to expect.
Inputs71/100
10 of 12 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › submission_id
Your ID for this report. Make a new ID for each new report. Use the same ID when you send the same report again.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › category
The type of problem. Use missing_capability for a feature request or a product gap.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › description
What occurred and what you needed.
Clear enough to supply this argument.
request › endpoint
The API endpoint path that the report is about. Do not include a query string or credentials.
Clear enough to supply this argument.
request › tool
The name of the tool that the report is about.
Clear enough to supply this argument.
request › goal
What you tried to do.
Clear enough to supply this argument.
request › expected_behavior
What you expected to occur.
Explain the meaning of this value, not just its name.
request › observed_behavior
What occurred instead.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › workaround
A workaround that you used, if you used one.
Clear enough to supply this argument.
request › request_ids
Request IDs from your own requests that show the problem. Each ID must be different.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › client › anyOf › 0 › name
Not provided
Missing description. Explain what this value means and how to supply it.
request › client › anyOf › 0 › version
Not provided
Missing description. Explain what this value means and how to supply it.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Read a Nansen feedback receipt for the same authenticated account. Costs zero credits.
Lookup uses feedback_id, consumes no report slot, and returns fresh status.
Received means saved; reviewed means triaged; closed has a public disposition.
No fix or delivery date is promised. Unknown, expired, and other-account IDs
return the same not-found response. Never create a replacement report or use
another account or an internal server key when lookup fails.
Do not redirect failed lookups to unrelated feedback channels.
The description explains the capability, when to use it, and what to expect.
Inputs0/100
0 of 1 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › feedback_id
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
Align the title with the capability actually described by this tool.
Description78/100
Get aggregated (not per wallet) smart trader (EXCLUDES whales, large holders, influencers, etc.) token balances and 24h change per chain for all chains (default is ['all'], which queries all supported chains) or specific chain(s).
Use filters to narrow down the results.
The description explains the capability, when to use it, and what to expect.
Inputs72/100
7 of 8 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › chains
Optional list of chains to include. If omitted, defaults to ['all'] (all supported chains). Use 'all' to query all supported chains. Supported chains: arbitrum, arc, avalanche, base, bnb, ethereum, hyperevm, iotaevm, linea, mantle, monad, optimism, plasma, polygon, robinhood, sei, solana, sonic, all
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeSmartMoneyLabels
Smart money category filters to include. 'Fund' is not supported here: this tool has no Fund data
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeStablecoin
Whether to include stablecoins in results
Clear enough to supply this argument.
request › includeNativeTokens
Whether to include native tokens (ETH, SOL, etc.) in results
Clear enough to supply this argument.
request › orderBy
Sort field. Pass an exact value above or None for default ('value_usd').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderByDirection
Sort direction: 'ASC' or 'DESC' (case-insensitive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › minHolders
Minimum number of smart money holders a token must have to be included (default: 0, no filter)
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
Shorten the title to an action and subject; move usage details into the description.
Description95/100
Get recent Hyperliquid perpetual futures trades from Smart Money addresses across all tokens.
For a broad view of Smart Money activity across all tokens, use token_discovery_screener with traderType="sm".
**Note:** This endpoint is Hyperliquid-only (perpetual futures data). It returns recent trades only (no date filtering available).
Columns returned:
- **Time**: Timestamp when the trade occurred (datetime: YYYY-MM-DD HH:MM:SS)
- **Side**: Position direction - Long or Short
- **Action**: Order action - Add, Reduce, Open, Close
- **Token**: Symbol of the perpetual contract
- **Size**: Quantity of the perpetual contract (numeric)
- **Price USD**: Price per token at time of trade (price formatted)
- **Value USD**: Total USD value of the trade (currency formatted)
- **Trader**: Nansen label of the trading address
- **Address**: Full trading wallet address
- **Tx Hash**: Blockchain transaction hash for verification
Sorting Options (all fields support "asc"/"desc"):
Available for sorting: timestamp, amount, price_usd
Examples:
# Get recent smart money perp trades (sorted by amount)
```
{
"orderBy": "amount",
"order_by_direction": "desc"
}
```
# Filter by action and side
```
{
"action": "Open",
"side": "Long"
}
```
The description explains the capability, when to use it, and what to expect.
Inputs56/100
6 of 8 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › valueUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › valueUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › action
Filter by action: 'Add'/'Reduce'/'Open'/'Close' (can combine with side for precise filtering).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › side
Filter by position side: 'Long'/'Short'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › traderAddress
Filter by trader address
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. Pass an exact value above or None for default ('amount'). Native token amount is preferred over USD value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › order_by_direction
Not provided
Missing description. Explain what this value means and how to supply it.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Get aggregated (not per wallet) smart trader (EXCLUDES whales, large holders, influencers, etc.) net USD flow per token over 1h/24h/7d/30d, per chain for all chains (default is ['all']) or specific chain(s).
Use this for what smart money is buying or selling right now; use smart_traders_and_funds_token_balances for what they hold.
The description explains the capability, when to use it, and what to expect.
Inputs72/100
9 of 10 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › chains
Optional list of chains to include. If omitted, defaults to ['all'] (all supported chains). Use 'all' to query all supported chains. Supported chains: arbitrum, arc, avalanche, base, bnb, ethereum, hyperevm, iotaevm, linea, mantle, monad, optimism, plasma, polygon, robinhood, sei, solana, sonic, all
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeSmartMoneyLabels
Smart money category filters to include
Explain the meaning of this value, not just its name.
request › tokenAddress
Restrict results to a single token address
Clear enough to supply this argument.
request › includeStablecoin
Whether to include stablecoins in results
Clear enough to supply this argument.
request › includeNativeTokens
Whether to include native tokens (ETH, SOL, etc.) in results
Clear enough to supply this argument.
request › marketCapUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › marketCapUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. Pass an exact value above or None for default ('net_flow_24h_usd').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderByDirection
Sort direction: 'ASC' or 'DESC' (case-insensitive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
Get individual (per wallet, per transaction) DEX trades made by smart traders (EXCLUDES whales, large holders, influencers, etc.) across all chains (default is ['all']) or specific chain(s).
Use this to see exactly which wallet bought or sold what; use smart_traders_and_funds_netflow for the aggregated view.
The description explains the capability, when to use it, and what to expect.
Inputs68/100
9 of 10 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › chains
Optional list of chains to include. If omitted, defaults to ['all'] (all supported chains). Use 'all' to query all supported chains. Supported chains: arbitrum, arc, avalanche, base, bnb, ethereum, hyperevm, iotaevm, linea, mantle, monad, optimism, plasma, polygon, robinhood, sei, solana, sonic, all
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeSmartMoneyLabels
Smart money category filters to include
Explain the meaning of this value, not just its name.
request › traderAddress
Filter by trader address
Explain the meaning of this value, not just its name.
request › tokenBoughtSymbol
Filter to trades that bought this token symbol
Clear enough to supply this argument.
request › tokenSoldSymbol
Filter to trades that sold this token symbol
Clear enough to supply this argument.
request › tradeValueUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › tradeValueUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. Pass an exact value above or None for default ('block_timestamp').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderByDirection
Sort direction: 'ASC' or 'DESC' (case-insensitive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
Expand internal abbreviations and remove technical prefixes from the display title.
Description94/100
Get Jupiter DCA (dollar-cost-averaging) orders opened by smart traders on Solana, including deposit size, amount spent so far and order status.
Use this for scheduled accumulation intent; use smart_traders_and_funds_dex_trades for one-off swaps.
The description explains the capability, when to use it, and what to expect.
Inputs64/100
8 of 9 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › includeSmartMoneyLabels
Smart money category filters to include
Explain the meaning of this value, not just its name.
request › traderAddress
Filter by trader address
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › inputTokenSymbol
Filter by the token symbol being spent by the DCA order
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › outputTokenSymbol
Filter by the token symbol being accumulated by the DCA order
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › depositTokenAmount › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › depositTokenAmount › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. Pass an exact value above or None for default ('dca_created_at').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderByDirection
Sort direction: 'ASC' or 'DESC' (case-insensitive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
Get the day-by-day history of aggregated smart trader token balances (EXCLUDES whales, large holders, influencers, etc.) for a date range on base, bnb, ethereum, monad, robinhood or solana.
Use this to see how smart money holdings changed over time; use smart_traders_and_funds_token_balances for the current snapshot.
This endpoint uses inclusive UTC calendar dates, not rolling timestamps.
The description explains the capability, when to use it, and what to expect.
Inputs77/100
10 of 11 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › dateRange › anyOf › 0 › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › anyOf › 0 › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Clear enough to supply this argument.
request › chains
Chains to include. Supported: base, bnb, ethereum, monad, robinhood, solana.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeSmartMoneyLabels
Smart money category filters to include
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › tokenSymbol
Restrict the history to a single token symbol
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › tokenAddress
Restrict the history to a single token address
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeStablecoin
Whether to include stablecoins in results
Clear enough to supply this argument.
request › includeNativeTokens
Whether to include native tokens (ETH, SOL, etc.) in results
Clear enough to supply this argument.
request › orderBy
Sort field. Pass an exact value above or None for default ('date').
Clear enough to supply this argument.
request › orderByDirection
Sort direction: 'ASC' or 'DESC' (case-insensitive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Rank smart trader addresses (EXCLUDES whales, large holders, influencers, etc.) by realized, unrealized and total USD PnL over a 1/7/30/90/180 day window, with ROI, win rate and trade counts.
Use this to find the best performing smart money wallets; use token_pnl_leaderboard for the best performers on one specific token.
The description explains the capability, when to use it, and what to expect.
Inputs58/100
5 of 6 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › chains
Optional list of chains to include. If omitted, defaults to ['all'] (all supported chains). Use 'all' to query all supported chains. Supported chains: arbitrum, arc, avalanche, base, bnb, ethereum, hyperevm, iotaevm, linea, mantle, monad, optimism, plasma, polygon, robinhood, sei, solana, sonic, all
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
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.
The description explains the capability, when to use it, and what to expect.
Inputs86/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › chains
Chains to include. Defaults to ['all'] (all supported chains). Supported: all, arbitrum, arc, avalanche, base, bnb, ethereum, hyperevm, iotaevm, linea, mantle, monad, optimism, plasma, polygon, robinhood, sei, solana, sonic.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeStablecoin
Whether to include stablecoins (default: false)
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeNativeTokens
Whether to include native tokens (default: false). This flag also covers wrapped-native, native derivative, chain-governance, liquid staking and restaking tokens. Some wrapped-native tokens still appear when it is false (for example WETH on Arbitrum or Base, WBNB, WAVAX): treat them as native tokens.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › minHolders
Minimum number of Fund wallets (each holding more than $1) a token must have to be included (default: 0, no filter)
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › minValueUsd
Minimum combined USD balance of all Fund wallets, per token and chain (default: 1000). Change it only when the user asks for a different minimum.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › balanceChange
Keep only tokens whose 24h Fund balance went up ('increase') or down ('decrease'). Both values leave out zero changes (default: 'any', no filter).
Clear enough to supply this argument.
request › orderBy
Sort field. Pass an exact value above or None for default ('balance_24h_percent_change_abs'). 'balance_24h_percent_change_abs' ranks the largest increases and decreases together, largest first, and leaves out tokens with no change.
Clear enough to supply this argument.
request › orderByDirection
Sort direction: 'ASC' or 'DESC' (case-insensitive).
Clear enough to supply this argument.
request › page
Page number, starting at 1
Clear enough to supply this argument.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "fund_token_balances",
"title": "Checking fund holdings",
"description": "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).\nFunds 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.\nThis is a snapshot of now: it has no date range and no history, and it does not list individual fund wallets.\nStablecoins, native tokens and tokens with less than minValueUsd (default $1,000) of combined Fund balance are excluded by default.\nThe default sort is the largest absolute 24h balance change, increases and decreases together.\nLarge percentage changes can come from small positions or one wallet, and balance changes alone do not prove purchases or sales.\nminValueUsd applies to the current balance, so a token that funds sold to below it does not show in decreases.\nWhich arguments to use:\n- What funds are buying: balanceChange='increase', orderBy='balance_24h_percent_change', orderByDirection='DESC'.\n- What funds are trading: two calls, the buying call above and balanceChange='decrease', orderBy='balance_24h_percent_change', orderByDirection='ASC'.\n- What funds are holding: orderBy='value_usd', orderByDirection='DESC'.\n- Which tokens have the most fund holders: orderBy='holders_count', orderByDirection='DESC'.\n- 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.\n- 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.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number, starting at 1"
},
"chains": {
"type": "array",
"items": {
"enum": [
"all",
"arbitrum",
"arc",
"avalanche",
"base",
"bnb",
"ethereum",
"hyperevm",
"iotaevm",
"linea",
"mantle",
"monad",
"optimism",
"plasma",
"polygon",
"robinhood",
"sei",
"solana",
"sonic"
],
"type": "string"
},
"description": "Chains to include. Defaults to ['all'] (all supported chains). Supported: all, arbitrum, arc, avalanche, base, bnb, ethereum, hyperevm, iotaevm, linea, mantle, monad, optimism, plasma, polygon, robinhood, sei, solana, sonic."
},
"orderBy": {
"anyOf": [
{
"enum": [
"balance_24h_percent_change_abs",
"value_usd",
"balance_24h_percent_change",
"holders_count"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort field. Pass an exact value above or None for default ('balance_24h_percent_change_abs'). 'balance_24h_percent_change_abs' ranks the largest increases and decreases together, largest first, and leaves out tokens with no change."
},
"minHolders": {
"type": "integer",
"default": 0,
"minimum": 0,
"description": "Minimum number of Fund wallets (each holding more than $1) a token must have to be included (default: 0, no filter)"
},
"minValueUsd": {
"type": "number",
"default": 1000,
"minimum": 0,
"description": "Minimum combined USD balance of all Fund wallets, per token and chain (default: 1000). Change it only when the user asks for a different minimum."
},
"balanceChange": {
"enum": [
"any",
"increase",
"decrease"
],
"type": "string",
"default": "any",
"description": "Keep only tokens whose 24h Fund balance went up ('increase') or down ('decrease'). Both values leave out zero changes (default: 'any', no filter)."
},
"orderByDirection": {
"enum": [
"ASC",
"DESC",
"asc",
"desc"
],
"type": "string",
"default": "DESC",
"description": "Sort direction: 'ASC' or 'DESC' (case-insensitive)."
},
"includeStablecoin": {
"type": "boolean",
"default": false,
"description": "Whether to include stablecoins (default: false)"
},
"includeNativeTokens": {
"type": "boolean",
"default": false,
"description": "Whether to include native tokens (default: false). This flag also covers wrapped-native, native derivative, chain-governance, liquid staking and restaking tokens. Some wrapped-native tokens still appear when it is false (for example WETH on Arbitrum or Base, WBNB, WAVAX): treat them as native tokens."
}
},
"description": "Request for current token holdings aggregated across Fund wallets (v1beta1 API).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Get upto 25 (per page) top holders information for a specific token.
**Note:** Using `labelType: smart_money` is not a good proxy for an overall market view. Use it only if user explicitly requests it, or to combine it with other non smart money data.
**Modes:**
- `onchain_tokens` (default): Analyze on-chain tokens by contract address
- `perps`: Analyze Hyperliquid perpetual futures by symbol (chain auto-set to "hyperliquid")
Columns returned (onchain_tokens mode):
- **Address**: Wallet/contract address of the token holder
- **Label**: Nansen label (e.g., exchange, whale, etc.)
- **Balance**: Current balance held (numeric with K/M/B formatting)
- **Balance USD**: USD value of token holdings (currency formatted)
- **Ownership %**: Percentage of total token supply owned (percentage, 2 decimal places)
- **Sent**: Total tokens sent from this address historically (numeric)
- **Received**: Total tokens received by this address historically (numeric)
- **24h Change**: Balance change in last 24 hours (numeric, can be negative)
- **7d Change**: Balance change in last 7 days (numeric, can be negative)
- **30d Change**: Balance change in last 30 days (numeric, can be negative)
Columns returned (perps mode):
- **Trader Address**: Address of the trader
- **Trader Label**: Nansen label for the trader
- **Side**: Position direction (Long/Short)
- **Position Value USD**: Total USD value of the position (currency formatted)
- **Position Size**: Size of the position in tokens (numeric)
- **Leverage**: Leverage multiplier (e.g., "20X")
- **Leverage Type**: Type of leverage (cross/isolated)
- **Entry Price**: Average entry price (price formatted)
- **Mark Price**: Current mark price (price formatted)
- **Liquidation Price**: Liquidation price (price formatted)
- **Funding USD**: Cumulative funding payments (currency formatted)
- **Unrealized PnL USD**: Unrealized profit/loss (currency formatted)
Sorting Options (default: holding_size desc):
onchain_tokens mode: holding_size, total_outflow, total_inflow, balance_change_24h, balance_change_7d, balance_change_30d
perps mode: holding_size, side, entry_price, leverage, liquidation_price, funding_usd, upnl_usd
Use only a value listed for the selected mode. A value from the wrong
mode is not an error: the call falls back to holding_size and the
output notes the changed sort.
Examples:
# On-chain tokens (default mode)
```
{
"mode": "onchain_tokens",
"chain": "ethereum",
"token_address": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"label_type": "top_100_holders"
}
```
# Fund holders (general labels; Fund is not a Smart Money label)
```
{
"mode": "onchain_tokens",
"chain": "ethereum",
"token_address": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"label_type": "top_100_holders",
"includeLabels": ["Fund"]
}
```
# Hyperliquid perpetual futures
```
{
"mode": "perps",
"token_address": "PENGU",
"label_type": "smart_money"
}
```
# Find most active senders using filters
```
{
"mode": "onchain_tokens",
"chain": "ethereum",
"token_address": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"label_type": "smart_money",
"includeSmartMoneyLabels": ["Smart Trader"],
"orderBy": "total_outflow",
"order_by_direction": "desc"
}
```
# Find biggest accumulators (who received most tokens)
```
{
"mode": "onchain_tokens",
"chain": "ethereum",
"token_address": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"label_type": "whale",
"orderBy": "total_inflow",
"order_by_direction": "desc"
}
```
# Perps mode with filters
```
{
"mode": "perps",
"token_address": "ETH",
"label_type": "smart_money",
"side": "Long",
"upnlUsd": {"from": 10000},
"positionValueUsd": {"from": 100000},
"orderBy": "holding_size",
"order_by_direction": "desc"
}
```
**Native-token / stablecoin `orderBy` restriction:**
With `labelType='top_100_holders'` (the default), native tokens
(`0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` and native SUI) and
stablecoins/pegged tokens support `orderBy='holding_size'` only. To
sort such a token by another onchain field, use `labelType='whale'`,
`smart_money`, `exchange` or `public_figure` instead. An unsupported
combination is not an error: the call falls back to `holding_size`
and the output notes the changed sort.
**Other `top_100_holders` limits for native tokens:** limited filters
(holding_size, total_outflow, total_inflow, address, smart money
labels). For advanced filters use a different `labelType` or set
`aggregateByEntity=true`.
**Does not** work for SOL in onchain_tokens mode (tokenAddress So11111111111111111111111111111111111111112). For SOL analysis, use perps mode instead.
The description explains the capability, when to use it, and what to expect.
Inputs65/100
14 of 17 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › tokenAddress
Not provided
Missing description. Explain what this value means and how to supply it.
request › mode
Analysis mode: 'onchain_tokens' for on-chain tokens by contract address, 'perps' for Hyperliquid perpetual futures by symbol. If mode is omitted and token_address is a symbol (not a contract address), mode defaults to 'perps'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › aggregateByEntity
Whether to aggregate data by entity instead of individual addresses. For on-chain tokens, includeSmartMoneyLabels turns it off, because labels need per-wallet rows.
Clear enough to supply this argument.
request › labelType
Label type for holder analysis and filtering
Explain the meaning of this value, not just its name.
request › includeSmartMoneyLabels
List of smart money labels to filter by (default: empty list). Use 'Any Smart Money' to include all smart money types. Smart Money does not include Fund wallets: use includeLabels=['Fund'] for Fund wallets. On-chain labels need labelType 'smart_money' or 'top_100_holders', and they turn aggregateByEntity off.
Clear enough to supply this argument.
request › includeLabels
General Nansen labels to keep, e.g. 'Fund', 'Whale', 'Exchange', 'Public Figure'. onchain_tokens mode with labelType='top_100_holders' only. Returns one row per wallet (no entity aggregation). Use this, not includeSmartMoneyLabels, for Fund holders: Funds are not Smart Money.
Clear enough to supply this argument.
request › side
Position side filter: Long or Short (case-insensitive). Perps mode only.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › entryPrice › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › entryPrice › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › upnlUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › upnlUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › positionValueUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › positionValueUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. holding_size works in both modes. onchain_tokens only: total_inflow, total_outflow, balance_change_24h, balance_change_7d, balance_change_30d. perps only: side, entry_price, leverage, liquidation_price, funding_usd, upnl_usd. Native tokens with labelType='top_100_holders' support holding_size only; use another labelType for other on-chain sorts. An unsupported combination is not an error: the call falls back to holding_size and the output notes the changed sort.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › order_by_direction
Not provided
Missing description. Explain what this value means and how to supply it.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "token_current_top_holders",
"title": "Finding top token holders",
"description": "Get upto 25 (per page) top holders information for a specific token.\n\n**Note:** Using `labelType: smart_money` is not a good proxy for an overall market view. Use it only if user explicitly requests it, or to combine it with other non smart money data.\n\n**Modes:**\n- `onchain_tokens` (default): Analyze on-chain tokens by contract address\n- `perps`: Analyze Hyperliquid perpetual futures by symbol (chain auto-set to \"hyperliquid\")\n\nColumns returned (onchain_tokens mode):\n- **Address**: Wallet/contract address of the token holder\n- **Label**: Nansen label (e.g., exchange, whale, etc.)\n- **Balance**: Current balance held (numeric with K/M/B formatting)\n- **Balance USD**: USD value of token holdings (currency formatted)\n- **Ownership %**: Percentage of total token supply owned (percentage, 2 decimal places)\n- **Sent**: Total tokens sent from this address historically (numeric)\n- **Received**: Total tokens received by this address historically (numeric)\n- **24h Change**: Balance change in last 24 hours (numeric, can be negative)\n- **7d Change**: Balance change in last 7 days (numeric, can be negative)\n- **30d Change**: Balance change in last 30 days (numeric, can be negative)\n\nColumns returned (perps mode):\n- **Trader Address**: Address of the trader\n- **Trader Label**: Nansen label for the trader\n- **Side**: Position direction (Long/Short)\n- **Position Value USD**: Total USD value of the position (currency formatted)\n- **Position Size**: Size of the position in tokens (numeric)\n- **Leverage**: Leverage multiplier (e.g., \"20X\")\n- **Leverage Type**: Type of leverage (cross/isolated)\n- **Entry Price**: Average entry price (price formatted)\n- **Mark Price**: Current mark price (price formatted)\n- **Liquidation Price**: Liquidation price (price formatted)\n- **Funding USD**: Cumulative funding payments (currency formatted)\n- **Unrealized PnL USD**: Unrealized profit/loss (currency formatted)\n\nSorting Options (default: holding_size desc):\n onchain_tokens mode: holding_size, total_outflow, total_inflow, balance_change_24h, balance_change_7d, balance_change_30d\n perps mode: holding_size, side, entry_price, leverage, liquidation_price, funding_usd, upnl_usd\n Use only a value listed for the selected mode. A value from the wrong\n mode is not an error: the call falls back to holding_size and the\n output notes the changed sort.\n\nExamples:\n # On-chain tokens (default mode)\n ```\n {\n \"mode\": \"onchain_tokens\",\n \"chain\": \"ethereum\",\n \"token_address\": \"0xa0b86a33e6b6c4b3add000b44b3a1234567890ab\",\n \"label_type\": \"top_100_holders\"\n }\n ```\n\n # Fund holders (general labels; Fund is not a Smart Money label)\n ```\n {\n \"mode\": \"onchain_tokens\",\n \"chain\": \"ethereum\",\n \"token_address\": \"0xa0b86a33e6b6c4b3add000b44b3a1234567890ab\",\n \"label_type\": \"top_100_holders\",\n \"includeLabels\": [\"Fund\"]\n }\n ```\n\n # Hyperliquid perpetual futures\n ```\n {\n \"mode\": \"perps\",\n \"token_address\": \"PENGU\",\n \"label_type\": \"smart_money\"\n }\n ```\n\n # Find most active senders using filters\n ```\n {\n \"mode\": \"onchain_tokens\",\n \"chain\": \"ethereum\",\n \"token_address\": \"0xa0b86a33e6b6c4b3add000b44b3a1234567890ab\",\n \"label_type\": \"smart_money\",\n \"includeSmartMoneyLabels\": [\"Smart Trader\"],\n \"orderBy\": \"total_outflow\",\n \"order_by_direction\": \"desc\"\n }\n ```\n\n # Find biggest accumulators (who received most tokens)\n ```\n {\n \"mode\": \"onchain_tokens\",\n \"chain\": \"ethereum\",\n \"token_address\": \"0xa0b86a33e6b6c4b3add000b44b3a1234567890ab\",\n \"label_type\": \"whale\",\n \"orderBy\": \"total_inflow\",\n \"order_by_direction\": \"desc\"\n }\n ```\n\n # Perps mode with filters\n ```\n {\n \"mode\": \"perps\",\n \"token_address\": \"ETH\",\n \"label_type\": \"smart_money\",\n \"side\": \"Long\",\n \"upnlUsd\": {\"from\": 10000},\n \"positionValueUsd\": {\"from\": 100000},\n \"orderBy\": \"holding_size\",\n \"order_by_direction\": \"desc\"\n }\n ```\n\n **Native-token / stablecoin `orderBy` restriction:**\n With `labelType='top_100_holders'` (the default), native tokens\n (`0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` and native SUI) and\n stablecoins/pegged tokens support `orderBy='holding_size'` only. To\n sort such a token by another onchain field, use `labelType='whale'`,\n `smart_money`, `exchange` or `public_figure` instead. An unsupported\n combination is not an error: the call falls back to `holding_size`\n and the output notes the changed sort.\n\n **Other `top_100_holders` limits for native tokens:** limited filters\n (holding_size, total_outflow, total_inflow, address, smart money\n labels). For advanced filters use a different `labelType` or set\n `aggregateByEntity=true`.\n\n **Does not** work for SOL in onchain_tokens mode (tokenAddress So11111111111111111111111111111111111111112). For SOL analysis, use perps mode instead.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"tokenAddress"
],
"properties": {
"mode": {
"enum": [
"onchain_tokens",
"perps"
],
"type": "string",
"default": "onchain_tokens",
"description": "Analysis mode: 'onchain_tokens' for on-chain tokens by contract address, 'perps' for Hyperliquid perpetual futures by symbol. If mode is omitted and token_address is a symbol (not a contract address), mode defaults to 'perps'."
},
"page": {
"type": "integer",
"default": 1
},
"side": {
"anyOf": [
{
"enum": [
"Long",
"Short"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Position side filter: Long or Short (case-insensitive). Perps mode only."
},
"chain": {
"type": "string",
"default": "ethereum",
"description": "Blockchain network. Supported: arbitrum, arc, avalanche, base, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, robinhood, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync"
},
"orderBy": {
"anyOf": [
{
"enum": [
"holding_size",
"total_outflow",
"total_inflow",
"balance_change_24h",
"balance_change_7d",
"balance_change_30d",
"side",
"entry_price",
"leverage",
"liquidation_price",
"funding_usd",
"upnl_usd"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort field. holding_size works in both modes. onchain_tokens only: total_inflow, total_outflow, balance_change_24h, balance_change_7d, balance_change_30d. perps only: side, entry_price, leverage, liquidation_price, funding_usd, upnl_usd. Native tokens with labelType='top_100_holders' support holding_size only; use another labelType for other on-chain sorts. An unsupported combination is not an error: the call falls back to holding_size and the output notes the changed sort."
},
"upnlUsd": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value (inclusive), optional"
},
"from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value (inclusive), optional"
}
},
"description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Unrealized PnL range filter in USD - perps mode only"
},
"labelType": {
"enum": [
"whale",
"public_figure",
"smart_money",
"top_100_holders",
"exchange"
],
"type": "string",
"default": "top_100_holders",
"description": "Label type for holder analysis and filtering"
},
"entryPrice": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value (inclusive), optional"
},
"from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value (inclusive), optional"
}
},
"description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Entry price range filter - perps mode only"
},
"tokenAddress": {
"type": "string"
},
"includeLabels": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"Whale",
"Public Figure",
"Exchange",
"Fund",
"Smart Trader"
],
"type": "string",
"description": "Wallet labels for holder analysis and filtering."
}
},
{
"type": "null"
}
],
"default": null,
"description": "General Nansen labels to keep, e.g. 'Fund', 'Whale', 'Exchange', 'Public Figure'. onchain_tokens mode with labelType='top_100_holders' only. Returns one row per wallet (no entity aggregation). Use this, not includeSmartMoneyLabels, for Fund holders: Funds are not Smart Money."
},
"positionValueUsd": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value (inclusive), optional"
},
"from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value (inclusive), optional"
}
},
"description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Position value range filter in USD - perps mode only"
},
"aggregateByEntity": {
"type": "boolean",
"default": false,
"description": "Whether to aggregate data by entity instead of individual addresses. For on-chain tokens, includeSmartMoneyLabels turns it off, because labels need per-wallet rows."
},
"order_by_direction": {
"enum": [
"ASC",
"DESC",
"asc",
"desc"
],
"type": "string",
"default": "DESC"
},
"includeSmartMoneyLabels": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"Smart Trader",
"Smart HL Perps Trader",
"Any Smart Money"
],
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "List of smart money labels to filter by (default: empty list). Use 'Any Smart Money' to include all smart money types. Smart Money does not include Fund wallets: use includeLabels=['Fund'] for Fund wallets. On-chain labels need labelType 'smart_money' or 'top_100_holders', and they turn aggregateByEntity off."
}
},
"description": "Pass these fields inside the tool's request argument.\n\nFor on-chain holders, specify the token contract and its supported chain.\nNative SOL holders are unavailable; use perps mode for SOL positions.\nFor Hyperliquid positions, use mode='perps' and a symbol such as BTC.\nPerps mode returns positions, not spot token holders.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description76/100
Get DEX trades for a specific token.
For the trades of one wallet, also on Hyperliquid, use `address_dex_trades`.
**Modes:**
- `onchain_tokens` (default): Analyze on-chain tokens by contract address
- `perps`: Analyze Hyperliquid perpetual futures by symbol (chain auto-set to "hyperliquid")
**NOTE:** In onchain_tokens mode, only ETH is supported among native tokens. For other native tokens (SOL, BTC, BNB, etc.), use perps mode instead.
The description explains the capability, when to use it, and what to expect.
Inputs54/100
11 of 14 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › tokenAddress
Not provided
Missing description. Explain what this value means and how to supply it.
request › mode
Analysis mode: 'onchain_tokens' for on-chain tokens by contract address, 'perps' for Hyperliquid perpetual futures by symbol. If mode is omitted and token_address is a symbol (not a contract address), mode defaults to 'perps'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Resolve the mismatch between this description and its schema constraints.
request › includeSmartMoneyLabels
List of smart money labels to filter by (default: empty list). Use 'Any Smart Money' to include all smart money types.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › valueUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › valueUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › action
Filter by action: 'buy'/'sell' (onchain), 'Add'/'Reduce'/'Open'/'Close' (perps, can combine with side for precise filtering).
Clear enough to supply this argument.
request › side
Position side filter: Long or Short (case-insensitive). Perps mode only.
Explain the meaning of this value, not just its name.
request › traderAddress
Filter by trader address
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. Pass an exact value above or None for default ('timestamp').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › order_by_direction
Not provided
Missing description. Explain what this value means and how to supply it.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Get 25 token transfers (per page) for a specific token based on the sort order.
Default: the last 24 hours, largest transfers first (orderBy "amount", "desc").
Direction rules (fromAddress = the sender, toAddress = the receiver):
- "Transfers of X", "X's transfers", "track X", and "what is X doing" do not
name a direction. For these, make two calls with the same address: one
with fromAddress, one with toAddress. Sort both by amount. Each call then
shows different transactions: the largest sent and the largest received.
- Use only fromAddress when the user asks what X sent (outflows,
withdrawals, "sent to", "moved to an exchange").
- Use only toAddress when the user asks what X received (inflows, deposits,
"where did X get").
- Do not put the same address in fromAddress and toAddress of one call. The
filters combine with AND, so the call returns only transfers from the
wallet to itself (usually none).
- If the user names no wallet, do not add an address filter.
**NOTE:** This tool does not support native tokens (so11111111111111111111111111111111111111112, 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee).
Columns returned:
- **Time**: Timestamp when the transfer occurred (block_timestamp: ISO 8601 format)
- **From Label**: Source address label (from_address_label: sender of tokens)
- **To Label**: Destination address label (to_address_label: receiver of tokens)
- **From Address**: Raw source address (from_address: hex address)
- **To Address**: Raw destination address (to_address: hex address)
- **Amount**: Quantity of tokens transferred (transfer_amount: numeric)
- **Value USD**: USD value of the transfer at time of transaction (transfer_value_usd: currency formatted)
- **Type**: Transfer category (transaction_type: DEX, CEX, transfer, etc.)
- **Tx Hash**: Blockchain transaction hash for verification (transaction_hash)
Sorting Options (all fields support "asc"/"desc"):
Available for sorting: timestamp, amount
- amount (default): largest transfers first. Use it when the user asks
about size, value, dollar amounts, the largest transfers, or whales.
- timestamp: latest transfers first. Use it only when the user asks for
the latest transfers or for a time order.
A page shows at most 25 transfers. For every total, min, max, mean, count
or list of wallets ("which wallets", "all wallets", "how much in total"),
use `columns` with `aggregations`, also when the transfers fit on one page.
The tool then computes the result from the raw values of all matching
transfers.
Examples:
# Basic request (largest transfers in the last 24 hours, the default sort)
```
{
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"dateRange": {"from": "24H_AGO", "to": "NOW"},
"orderBy": "amount",
"order_by_direction": "desc"
}
```
# Latest transfers first (only when the user asks for the latest)
```
{
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"dateRange": {"from": "24H_AGO", "to": "NOW"},
"orderBy": "timestamp",
"order_by_direction": "desc"
}
```
# Smart money only filter (largest transfers first)
```
{
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"dateRange": {"from": "7D_AGO", "to": "NOW"},
"transferOriginCategories": ["all_transfers"],
"onlySmartTradersAndFunds": true,
"orderBy": "amount",
"order_by_direction": "desc"
}
```
# Filter by DEX only with minimum transfer value (USD)
```
{
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"dateRange": {"from": "24H_AGO", "to": "NOW"},
"transferOriginCategories": ["dex"],
"transferValueUsd": {"from": 1000}
}
```
# Every wallet that received the token from one sender, all pages
```
{
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"dateRange": {"from": "2026-10-02", "to": "2026-10-02"},
"fromAddress": "0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72",
"columns": ["to_address"],
"aggregations": ["unique"]
}
```
# Total amount that one wallet received, without transfers below 1 token
```
{
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"dateRange": {"from": "7D_AGO", "to": "NOW"},
"toAddress": "0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72",
"min_amount": 1,
"columns": ["amount"],
"aggregations": ["sum"]
}
```
# One wallet, no direction named: make two calls, both sorted by amount
# Call 1: what the wallet sent
```
{
"chain": "base",
"tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"dateRange": {"from": "7D_AGO", "to": "NOW"},
"fromAddress": "0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72",
"orderBy": "amount",
"order_by_direction": "desc"
}
```
# Call 2: what the wallet received
```
{
"chain": "base",
"tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"dateRange": {"from": "7D_AGO", "to": "NOW"},
"toAddress": "0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72",
"orderBy": "amount",
"order_by_direction": "desc"
}
```
**Available Filters:**
Address Filters:
- **fromAddress** (str or list[str], optional): the wallet(s) that SENT the tokens
Example: "0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72"
Example: ["0xaddr1", "0xaddr2"]
- **toAddress** (str or list[str], optional): the wallet(s) that RECEIVED the tokens
See the Direction rules at the top.
Transfer Origin Categories:
- **transferOriginCategories** (list[str]): List of transfer types to include
Possible values: ['dex', 'cex', 'non_exchange_transfers', 'all_transfers']
Default: ['all_transfers']
Examples:
- ['dex'] - only DEX transfers
- ['cex'] - only CEX transfers
- ['dex', 'cex'] - both DEX and CEX
- ['non_exchange_transfers'] - only non-exchange transfers
- ['all_transfers'] - all types (default)
Smart Money Filter:
- **onlySmartTradersAndFunds** (bool): Only show smart money transfers (default: false)
When true, filters to show **only** transfers involving profitable addresses
Numeric Range Filter:
- **transferValueUsd** (object, optional): Filter by USD value of transfer
Format: {"from": X, "to": Y} or {"from": X} or {"to": Y}
- Specify only `from` for minimum bound (no maximum)
- Specify only `to` for maximum bound (no minimum)
- Specify both for a bounded range
Example: {"from": 1000} - only transfers worth at least $1,000 USD
Example: {"to": 50000} - only transfers up to $50,000 USD
Example: {"from": 1000, "to": 50000} - transfers between $1,000 and $50,000 USD
Note: This filters by the USD value of the transfer at time of transaction
Notes:
- Use fromAddress/toAddress for a specific wallet (see Direction rules)
- Use transferOriginCategories to control which transfer origins are included
- Smart Money filter shows **only** transfers involving profitable addresses (definition of *Smart Money*)
- transferValueUsd filters by USD value at time of transaction
The description explains the capability, when to use it, and what to expect.
Inputs62/100
13 of 17 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › chain
Not provided
Missing description. Explain what this value means and how to supply it.
request › tokenAddress
Not provided
Missing description. Explain what this value means and how to supply it.
request › dateRange › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › transferOriginCategories
List of transfer types to include. Possible values: ['dex', 'cex', 'non_exchange_transfers', 'all_transfers']
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › onlySmartTradersAndFunds
Whether to include only smart money transfers.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › transferValueUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › transferValueUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › min_amount
Keep only transfers with amount >= this value, in token units (inclusive). Example: 1 drops dust below 1 token.
Clear enough to supply this argument.
request › max_amount
Keep only transfers with amount <= this value, in token units (inclusive).
Clear enough to supply this argument.
request › columns
Columns to show or summarize. Alone, `columns` gives one page of at most 25 transfers with only these columns. For a list of wallets, a count or a total, also set `aggregations`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › aggregations
Compute the `columns` over ALL matching transfers. Use it for every total, min, max, mean, count or list of wallets (which wallets, all wallets, how many wallets), also when the transfers fit on one page: sum/min/max/mean for amount and value_usd, unique for from_address and to_address. Example: "columns": ["to_address"], "aggregations": ["unique"].
Clear enough to supply this argument.
request › fromAddress
Wallet(s) that SENT the tokens. Use alone only when the user asks what a wallet sent. 'Transfers of X' names no direction: then make a second call with toAddress. Do not put the same address in toAddress: the filters combine with AND.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › toAddress
Wallet(s) that RECEIVED the tokens. Use alone only when the user asks what a wallet received. 'Transfers of X' names no direction: then make a second call with fromAddress. Do not put the same address in fromAddress: the filters combine with AND.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. Pass an exact value above or None for default ('amount', largest first). Use 'timestamp' only when the user asks for the latest transfers or a time order.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › order_by_direction
Not provided
Missing description. Explain what this value means and how to supply it.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "token_transfers",
"title": "Tracking token transfers",
"description": "Get 25 token transfers (per page) for a specific token based on the sort order.\nDefault: the last 24 hours, largest transfers first (orderBy \"amount\", \"desc\").\n\nDirection rules (fromAddress = the sender, toAddress = the receiver):\n- \"Transfers of X\", \"X's transfers\", \"track X\", and \"what is X doing\" do not\n name a direction. For these, make two calls with the same address: one\n with fromAddress, one with toAddress. Sort both by amount. Each call then\n shows different transactions: the largest sent and the largest received.\n- Use only fromAddress when the user asks what X sent (outflows,\n withdrawals, \"sent to\", \"moved to an exchange\").\n- Use only toAddress when the user asks what X received (inflows, deposits,\n \"where did X get\").\n- Do not put the same address in fromAddress and toAddress of one call. The\n filters combine with AND, so the call returns only transfers from the\n wallet to itself (usually none).\n- If the user names no wallet, do not add an address filter.\n\n**NOTE:** This tool does not support native tokens (so11111111111111111111111111111111111111112, 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee).\n\nColumns returned:\n- **Time**: Timestamp when the transfer occurred (block_timestamp: ISO 8601 format)\n- **From Label**: Source address label (from_address_label: sender of tokens)\n- **To Label**: Destination address label (to_address_label: receiver of tokens)\n- **From Address**: Raw source address (from_address: hex address)\n- **To Address**: Raw destination address (to_address: hex address)\n- **Amount**: Quantity of tokens transferred (transfer_amount: numeric)\n- **Value USD**: USD value of the transfer at time of transaction (transfer_value_usd: currency formatted)\n- **Type**: Transfer category (transaction_type: DEX, CEX, transfer, etc.)\n- **Tx Hash**: Blockchain transaction hash for verification (transaction_hash)\n\nSorting Options (all fields support \"asc\"/\"desc\"):\n Available for sorting: timestamp, amount\n - amount (default): largest transfers first. Use it when the user asks\n about size, value, dollar amounts, the largest transfers, or whales.\n - timestamp: latest transfers first. Use it only when the user asks for\n the latest transfers or for a time order.\n\nA page shows at most 25 transfers. For every total, min, max, mean, count\nor list of wallets (\"which wallets\", \"all wallets\", \"how much in total\"),\nuse `columns` with `aggregations`, also when the transfers fit on one page.\nThe tool then computes the result from the raw values of all matching\ntransfers.\n\nExamples:\n # Basic request (largest transfers in the last 24 hours, the default sort)\n ```\n {\n \"chain\": \"ethereum\",\n \"tokenAddress\": \"0xa0b86a33e6b6c4b3add000b44b3a1234567890ab\",\n \"dateRange\": {\"from\": \"24H_AGO\", \"to\": \"NOW\"},\n \"orderBy\": \"amount\",\n \"order_by_direction\": \"desc\"\n }\n ```\n\n # Latest transfers first (only when the user asks for the latest)\n ```\n {\n \"chain\": \"ethereum\",\n \"tokenAddress\": \"0xa0b86a33e6b6c4b3add000b44b3a1234567890ab\",\n \"dateRange\": {\"from\": \"24H_AGO\", \"to\": \"NOW\"},\n \"orderBy\": \"timestamp\",\n \"order_by_direction\": \"desc\"\n }\n ```\n\n # Smart money only filter (largest transfers first)\n ```\n {\n \"chain\": \"ethereum\",\n \"tokenAddress\": \"0xa0b86a33e6b6c4b3add000b44b3a1234567890ab\",\n \"dateRange\": {\"from\": \"7D_AGO\", \"to\": \"NOW\"},\n \"transferOriginCategories\": [\"all_transfers\"],\n \"onlySmartTradersAndFunds\": true,\n \"orderBy\": \"amount\",\n \"order_by_direction\": \"desc\"\n }\n ```\n\n # Filter by DEX only with minimum transfer value (USD)\n ```\n {\n \"chain\": \"ethereum\",\n \"tokenAddress\": \"0xa0b86a33e6b6c4b3add000b44b3a1234567890ab\",\n \"dateRange\": {\"from\": \"24H_AGO\", \"to\": \"NOW\"},\n \"transferOriginCategories\": [\"dex\"],\n \"transferValueUsd\": {\"from\": 1000}\n }\n ```\n\n # Every wallet that received the token from one sender, all pages\n ```\n {\n \"chain\": \"ethereum\",\n \"tokenAddress\": \"0xa0b86a33e6b6c4b3add000b44b3a1234567890ab\",\n \"dateRange\": {\"from\": \"2026-10-02\", \"to\": \"2026-10-02\"},\n \"fromAddress\": \"0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72\",\n \"columns\": [\"to_address\"],\n \"aggregations\": [\"unique\"]\n }\n ```\n\n # Total amount that one wallet received, without transfers below 1 token\n ```\n {\n \"chain\": \"ethereum\",\n \"tokenAddress\": \"0xa0b86a33e6b6c4b3add000b44b3a1234567890ab\",\n \"dateRange\": {\"from\": \"7D_AGO\", \"to\": \"NOW\"},\n \"toAddress\": \"0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72\",\n \"min_amount\": 1,\n \"columns\": [\"amount\"],\n \"aggregations\": [\"sum\"]\n }\n ```\n\n # One wallet, no direction named: make two calls, both sorted by amount\n # Call 1: what the wallet sent\n ```\n {\n \"chain\": \"base\",\n \"tokenAddress\": \"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913\",\n \"dateRange\": {\"from\": \"7D_AGO\", \"to\": \"NOW\"},\n \"fromAddress\": \"0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72\",\n \"orderBy\": \"amount\",\n \"order_by_direction\": \"desc\"\n }\n ```\n # Call 2: what the wallet received\n ```\n {\n \"chain\": \"base\",\n \"tokenAddress\": \"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913\",\n \"dateRange\": {\"from\": \"7D_AGO\", \"to\": \"NOW\"},\n \"toAddress\": \"0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72\",\n \"orderBy\": \"amount\",\n \"order_by_direction\": \"desc\"\n }\n ```\n\n**Available Filters:**\n\nAddress Filters:\n- **fromAddress** (str or list[str], optional): the wallet(s) that SENT the tokens\n Example: \"0x2b060b9c89B8aD04e5E1fD40F1f327e41DD32c72\"\n Example: [\"0xaddr1\", \"0xaddr2\"]\n- **toAddress** (str or list[str], optional): the wallet(s) that RECEIVED the tokens\n See the Direction rules at the top.\n\nTransfer Origin Categories:\n- **transferOriginCategories** (list[str]): List of transfer types to include\n Possible values: ['dex', 'cex', 'non_exchange_transfers', 'all_transfers']\n Default: ['all_transfers']\n Examples:\n - ['dex'] - only DEX transfers\n - ['cex'] - only CEX transfers\n - ['dex', 'cex'] - both DEX and CEX\n - ['non_exchange_transfers'] - only non-exchange transfers\n - ['all_transfers'] - all types (default)\n\nSmart Money Filter:\n- **onlySmartTradersAndFunds** (bool): Only show smart money transfers (default: false)\n When true, filters to show **only** transfers involving profitable addresses\n\nNumeric Range Filter:\n- **transferValueUsd** (object, optional): Filter by USD value of transfer\n Format: {\"from\": X, \"to\": Y} or {\"from\": X} or {\"to\": Y}\n - Specify only `from` for minimum bound (no maximum)\n - Specify only `to` for maximum bound (no minimum)\n - Specify both for a bounded range\n Example: {\"from\": 1000} - only transfers worth at least $1,000 USD\n Example: {\"to\": 50000} - only transfers up to $50,000 USD\n Example: {\"from\": 1000, \"to\": 50000} - transfers between $1,000 and $50,000 USD\n Note: This filters by the USD value of the transfer at time of transaction\n\nNotes:\n - Use fromAddress/toAddress for a specific wallet (see Direction rules)\n - Use transferOriginCategories to control which transfer origins are included\n - Smart Money filter shows **only** transfers involving profitable addresses (definition of *Smart Money*)\n - transferValueUsd filters by USD value at time of transaction",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"chain",
"tokenAddress"
],
"properties": {
"page": {
"type": "integer",
"default": 1
},
"chain": {
"type": "string"
},
"columns": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"time",
"from_address",
"to_address",
"from_label",
"to_label",
"amount",
"value_usd",
"type",
"tx_hash"
],
"type": "string"
},
"minItems": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Columns to show or summarize. Alone, `columns` gives one page of at most 25 transfers with only these columns. For a list of wallets, a count or a total, also set `aggregations`."
},
"orderBy": {
"anyOf": [
{
"enum": [
"timestamp",
"amount"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort field. Pass an exact value above or None for default ('amount', largest first). Use 'timestamp' only when the user asks for the latest transfers or a time order."
},
"dateRange": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight."
},
"from": {
"type": "string",
"description": "Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
}
},
"description": "Date range for transfer analysis. Max window: 365 days — longer ranges are clamped to the most recent year and the effective range is reported in the response. Prefer relative tokens (1H_AGO, 24H_AGO, 7D_AGO, 30D_AGO, 1Y_AGO).",
"additionalProperties": false
},
"toAddress": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Wallet(s) that RECEIVED the tokens. Use alone only when the user asks what a wallet received. 'Transfers of X' names no direction: then make a second call with fromAddress. Do not put the same address in fromAddress: the filters combine with AND."
},
"max_amount": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Keep only transfers with amount <= this value, in token units (inclusive)."
},
"min_amount": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Keep only transfers with amount >= this value, in token units (inclusive). Example: 1 drops dust below 1 token."
},
"fromAddress": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Wallet(s) that SENT the tokens. Use alone only when the user asks what a wallet sent. 'Transfers of X' names no direction: then make a second call with toAddress. Do not put the same address in toAddress: the filters combine with AND."
},
"aggregations": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"sum",
"min",
"max",
"mean",
"count",
"unique"
],
"type": "string"
},
"minItems": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Compute the `columns` over ALL matching transfers. Use it for every total, min, max, mean, count or list of wallets (which wallets, all wallets, how many wallets), also when the transfers fit on one page: sum/min/max/mean for amount and value_usd, unique for from_address and to_address. Example: \"columns\": [\"to_address\"], \"aggregations\": [\"unique\"]."
},
"tokenAddress": {
"type": "string"
},
"transferValueUsd": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value (inclusive), optional"
},
"from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value (inclusive), optional"
}
},
"description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Range of USD values for transfer analysis. Both `from` and `to` are inclusive."
},
"order_by_direction": {
"enum": [
"ASC",
"DESC",
"asc",
"desc"
],
"type": "string",
"default": "DESC"
},
"onlySmartTradersAndFunds": {
"type": "boolean",
"default": false,
"description": "Whether to include only smart money transfers."
},
"transferOriginCategories": {
"type": "array",
"items": {
"type": "string"
},
"default": [
"all_transfers"
],
"description": "List of transfer types to include. Possible values: ['dex', 'cex', 'non_exchange_transfers', 'all_transfers']"
}
},
"description": "Complete request for token transfers (flattened).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
Get hourly token-flow history for ONE holder segment over a date range. Use `token_recent_flows_summary` instead for an on-chain snapshot across ALL wallet categories.
**Note:** Using `holder_segment: smart_money` is not a good proxy for an overall market view. Use it only if user explicitly requests it, or to combine it with other non smart money data.
This is a **more granular** tool than `token_recent_flows_summary` and provides the TOTAL flows over the entire time frame broken down by segment.
**Modes:**
- `onchain_tokens` (default): Analyze on-chain tokens by contract address
- `perps`: Analyze Hyperliquid perpetual futures by symbol (chain auto-set to "hyperliquid") — supports native tokens
**NOTE:** Native tokens (0xeee…, So111…) cannot be queried in `onchain_tokens` mode. If a native placeholder address is supplied, this tool returns Hyperliquid perpetual-futures flows for that chain's native coin instead (e.g. hyperevm → HYPE, bnb → BNB, base → ETH) and prepends a prominent data-source warning. For native-token wallet-category flows on-chain, use `token_recent_flows_summary`.
Resolve contradictions between the description, input schema, and annotations.
Inputs66/100
7 of 8 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › tokenAddress
Not provided
Missing description. Explain what this value means and how to supply it.
request › mode
Analysis mode: 'onchain_tokens' for on-chain tokens by contract address, 'perps' for Hyperliquid perpetual futures by symbol. If mode is omitted and token_address is a symbol (not a contract address), mode defaults to 'perps'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › holder_segment
Label types for holder analysis and filtering.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number, starting at 1
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › perPage
Number of records per page, from 1 to 1000
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
Name the specific action and subject instead of using a generic label such as ‘manage’ or ‘tool’.
Description88/100
Upto 25 results (per page) of trader PnL for a token. Use the sorting and filtering options to narrow down the results.
**Modes:**
- `onchain_tokens` (default): Analyze on-chain tokens by contract address
- `perps`: Analyze Hyperliquid perpetual futures by symbol (chain auto-set to "hyperliquid") — supports native tokens
**NOTE:** This tool does not support native tokens (so11111111111111111111111111111111111111112, 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee) in `onchain_tokens` mode. Native tokens (by symbol - SOL, ETH, ARB etc) ARE fully supported in `perps` mode.
Returns:
Trader performance rankings as markdown. Returns empty string if no trading data found.
Columns returned:
- **Address**: Trader's wallet address
- **Label**: Nansen label of the trader
- **Total PnL**: Combined realized and unrealized PnL (currency formatted, can be negative)
- **Total ROI**: Total return on investment as percentage (percentage formatted)
- **Realized PnL**: Profit/loss from completed trades (currency formatted, can be negative)
- **Realized ROI**: Return on investment from realized trades only (percentage formatted)
- **Unrealized PnL**: Current profit/loss on open positions (currency formatted, can be negative)
- **Unrealized ROI**: Return on investment from unrealized positions only (percentage formatted)
- **Token Holdings**: Current token quantity held (numeric formatted)
- **Holdings USD**: Current USD value of token holdings (currency formatted)
- **Token Price**: Current price per token (price formatted)
- **Peak Token Holdings**: Maximum token quantity ever held in the date range (numeric formatted)
- **Peak Holdings USD**: Maximum USD value ever held in the date range (currency formatted)
- **Still Holding %**: Percentage of peak holdings still held (percentage formatted)
- **Total Trades**: Number of trades executed by this address
- **Net Flow**: Net money flow - negative means net seller (currency formatted, can be negative)
**Sorting** Options
You can **ONLY** sort by pnl_usd_total, roi_percent_total, pnl_usd_realised, roi_percent_realised,
pnl_usd_unrealised, roi_percent_unrealised, holding_amount, max_balance_held, nof_trades,
still_holding_balance_ratio, netflow_amount
**Filtering** Options:
📋 List filters: trader_address, trader_address_label
📊 Numeric range filters: pnl_usd_realised, pnl_usd_unrealised, holding_amount, holding_usd,
nof_trades, still_holding_balance_ratio, max_balance_held, max_balance_held_usd
Examples:
# On-chain tokens (default mode)
```
{
"mode": "onchain_tokens",
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6ba3e5b9e4b1b1b1b1b1b1b1b1b1b1b",
"dateRange": {"from": "30D_AGO", "to": "NOW"},
"orderBy": "pnl_usd_total",
"order_by_direction": "desc"
}
```
# Hyperliquid perpetual futures
```
{
"mode": "perps",
"tokenAddress": "ETH",
"dateRange": {"from": "7D_AGO", "to": "NOW"}
}
```
# Advanced filtering: Find profitable active traders with significant holdings
```
{
"chain": "ethereum",
"tokenAddress": "0xa0b86a33e6ba3e5b9e4b1b1b1b1b1b1b1b1b1b1b",
"dateRange": {"from": "30D_AGO", "to": "NOW"},
"pnlUsdTotal": {"from": 1000, "to": 999999999},
"nofTrades": {"from": 5, "to": 100},
"holdingUsd": {"from": 10000, "to": 999999999},
"stillHoldingBalanceRatio": {"from": 0.1, "to": 1.0},
"orderBy": "roi_percent_total",
"order_by_direction": "desc"
}
```
Notes:
- Ranked by total PnL performance by default
- Useful for identifying successful traders and copying strategies
- Both ascending and descending sorts provide valuable insights (winners vs losers)
- ONLY RETURNS TOP 25 RESULTS for the sort order. Hence the result is NEVER complete.
- Make sure the sort order is relevant to your analysis as otherwise you will miss data.
** This tool does not support hyperevm as chain **
Resolve contradictions between the description, input schema, and annotations.
Inputs65/100
45 of 48 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › tokenAddress
Not provided
Missing description. Explain what this value means and how to supply it.
request › mode
Analysis mode: 'onchain_tokens' for on-chain tokens by contract address, 'perps' for Hyperliquid perpetual futures by symbol. If mode is omitted and token_address is a symbol (not a contract address), mode defaults to 'perps'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › traderAddress
Filter by specific trader addresses
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › fullName
Filter by specific trader labels/names
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › pnlUsdTotal › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › pnlUsdTotal › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › roiPercentTotal › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › roiPercentTotal › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › pnlUsdRealised › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › pnlUsdRealised › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › roiPercentRealised › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › roiPercentRealised › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › pnlUsdUnrealised › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › pnlUsdUnrealised › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › roiPercentUnrealised › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › roiPercentUnrealised › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › holdingUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › holdingUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofTrades › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofTrades › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › stillHoldingBalanceRatio › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › stillHoldingBalanceRatio › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › netflowAmountUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › netflowAmountUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › holdingAmount › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › holdingAmount › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofBuys › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofBuys › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofSells › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofSells › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › boughtAmount › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › boughtAmount › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › soldAmount › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › soldAmount › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › boughtUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › boughtUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › soldUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › soldUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › maxBalanceHeld › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › maxBalanceHeld › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › maxBalanceHeldUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › maxBalanceHeldUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. Pass an exact value above or None for default ('pnl_usd_realised'). Native-balance fields are preferred over USD twins.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › order_by_direction
Not provided
Missing description. Explain what this value means and how to supply it.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Get net buyers or net sellers of a token on DEX (Decentralised Exchanges) only.
Use this tool to find out WHO is buying or selling a token (on DEX) AND then you can check if they are liquidating profits or accumulating more.
Returns:
Aggregated buyer/seller activity as markdown. Returns empty string if no trading data found.
Columns returned:
- **Address**: Trader's wallet address
- **Label**: Nansen label of the address
- **Bought Token Volume**: Total quantity of tokens purchased
- **Sold Token Volume**: Total quantity of tokens sold
- **Total Token Volume**: Bought plus sold
- **Net Bought / Net Sold Token Volume**: Bought minus sold for BUY results, or sold minus bought for SELL results
- **Bought Volume USD**: USD value of all token purchases
- **Sold Volume USD**: USD value of all token sales
- **Total Volume USD**: Bought plus sold
- **Net Bought / Net Sold Volume USD**: Bought minus sold for BUY results, or sold minus bought for SELL results
Sorting Options:
Sort ASC or DESC by net_token_volume (default: biggest net buyers or sellers first), token_trade_volume (total volume: most active traders, such as market-making bots), bought_token_volume, or sold_token_volume.
Notes:
- buy_or_sell parameter filters for "BUY" (net buyers) or "SELL" (net sellers), decided by net token amount
- Net USD volume can be negative while net token volume is zero or positive, because USD is priced per trade
- min_trade_volume_usd applies to the requested side: bought USD for BUY, sold USD for SELL
- Machine-readable rows: token_trade_volume / trade_volume_usd are total volume (bought + sold); net_token_volume / net_volume_usd are net volume.
- Aggregates all trading activity within the specified time range
The description explains the capability, when to use it, and what to expect.
Inputs45/100
6 of 10 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › chain
Not provided
Missing description. Explain what this value means and how to supply it.
request › tokenAddress
Not provided
Missing description. Explain what this value means and how to supply it.
request › buy_or_sell
Select net buyers (BUY) or net sellers (SELL)
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › time_range › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › time_range › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › include_labels
Filter based on a particular set of segments based on label, default is empty which includes all segments
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › min_trade_volume_usd
Minimum USD volume on the requested side (bought for BUY, sold for SELL).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. The default net_token_volume (bought minus sold for BUY, sold minus bought for SELL) ranks the biggest net buyers or sellers. token_trade_volume is total volume (bought plus sold): use it to find the most active traders. USD volume fields are disabled; native token volume is preferred.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › order_by_direction
Not provided
Missing description. Explain what this value means and how to supply it.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
Name the specific action and subject instead of using a generic label such as ‘manage’ or ‘tool’.
Description88/100
Get an on-chain flow snapshot across **ALL** wallet categories in one call. This tool supports native ETH on Ethereum and native SOL on Solana, and is the correct choice for standard lookbacks such as 1d.
Returns **TOTAL** token flows per segment:
1. Public Figures
2. Top PnL Traders
3. Whales
4. Smart Traders
5. Exchanges
6. Fresh Wallets
Inflow and outflow of tokens between the segments is CRITICAL in identifying token price trends.
The values provided are **aggregated over the specific lookback period (last 5min, 1d, 7d etc) specified**. If you have SPECIFIC date ranges in mind, use `token_flows` instead.
**NOTE** Use `token_flows` for more granular data as it can filter between exact dates and provides HOURLY breakdowns.
Returns:
Categorized token flow analysis as markdown.
For each segment, returns:
- Flow amount in USD
- Ratio compared to average flow
- Number of wallets
Format: "{Segment} wallet flow of {amount} ({ratio}x average, from {count} wallets)"
Notes:
- Positive flow = net buying, negative flow = net selling
- For Exchange Flow, positive means more inflow to exchanges, negative means more outflow from exchanges
- Categorizes market participants by their historical behavior and characteristics
- A wallet can be in more than one segment or perps cohort. Do not add segment flows, cohort exposures or wallet counts as if each segment has different wallets.
NOTE: Bitcoin is not supported. DO NOT use this tool for bitcoin.
**Modes:**
- `onchain_tokens` (default): On-chain token flow intelligence across cohorts
- `perps`: Hyperliquid perpetual futures — returns position intelligence (current aggregate long/short/total USD by cohort: Smart Money, Whales, Public Figures). Native tokens (SOL, ETH, BTC etc) are fully supported in perps mode.
Resolve contradictions between the description, input schema, and annotations.
Inputs56/100
3 of 4 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › tokenAddress
Not provided
Missing description. Explain what this value means and how to supply it.
request › mode
Analysis mode: 'onchain_tokens' for on-chain tokens, 'perps' for Hyperliquid perpetual futures by symbol. If mode is omitted and token_address is a symbol (not a contract address), mode defaults to 'perps'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › lookbackPeriod
Lookback period for analysis
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "token_recent_flows_summary",
"title": "Analyzing recent activity",
"description": "Get an on-chain flow snapshot across **ALL** wallet categories in one call. This tool supports native ETH on Ethereum and native SOL on Solana, and is the correct choice for standard lookbacks such as 1d.\n\nReturns **TOTAL** token flows per segment:\n 1. Public Figures\n 2. Top PnL Traders\n 3. Whales\n 4. Smart Traders\n 5. Exchanges\n 6. Fresh Wallets\n\nInflow and outflow of tokens between the segments is CRITICAL in identifying token price trends.\n\nThe values provided are **aggregated over the specific lookback period (last 5min, 1d, 7d etc) specified**. If you have SPECIFIC date ranges in mind, use `token_flows` instead.\n\n**NOTE** Use `token_flows` for more granular data as it can filter between exact dates and provides HOURLY breakdowns.\n\nReturns:\n Categorized token flow analysis as markdown.\n\n For each segment, returns:\n - Flow amount in USD\n - Ratio compared to average flow\n - Number of wallets\n\n Format: \"{Segment} wallet flow of {amount} ({ratio}x average, from {count} wallets)\"\n\nNotes:\n - Positive flow = net buying, negative flow = net selling\n - For Exchange Flow, positive means more inflow to exchanges, negative means more outflow from exchanges\n - Categorizes market participants by their historical behavior and characteristics\n - A wallet can be in more than one segment or perps cohort. Do not add segment flows, cohort exposures or wallet counts as if each segment has different wallets.\n\nNOTE: Bitcoin is not supported. DO NOT use this tool for bitcoin.\n\n**Modes:**\n- `onchain_tokens` (default): On-chain token flow intelligence across cohorts\n- `perps`: Hyperliquid perpetual futures — returns position intelligence (current aggregate long/short/total USD by cohort: Smart Money, Whales, Public Figures). Native tokens (SOL, ETH, BTC etc) are fully supported in perps mode.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"tokenAddress"
],
"properties": {
"mode": {
"enum": [
"onchain_tokens",
"perps"
],
"type": "string",
"default": "onchain_tokens",
"description": "Analysis mode: 'onchain_tokens' for on-chain tokens, 'perps' for Hyperliquid perpetual futures by symbol. If mode is omitted and token_address is a symbol (not a contract address), mode defaults to 'perps'."
},
"chain": {
"type": "string",
"default": "ethereum",
"description": "Blockchain network. Supported: arbitrum, arc, avalanche, base, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, robinhood, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync"
},
"tokenAddress": {
"type": "string"
},
"lookbackPeriod": {
"enum": [
"5m",
"1h",
"6h",
"12h",
"1d",
"7d"
],
"type": "string",
"default": "1d",
"description": "Lookback period for analysis"
}
},
"description": "Complete request for token recent flows summary (flattened).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description95/100
Get comprehensive token screening data across multiple blockchain networks with advanced filtering.
A maximum of 25 results per page are returned out of 1000s of tokens. Use the sorting and filtering options to narrow down the results.
In a mixed spot + hyperliquid request, `page` applies to both the spot and perps sections.
A maximum of 5 chains can be specified per request (excess chains are automatically trimmed).
This tool helps with token discovery and finding trending tokens by combining different metrics: volume, liquidity, market cap,
smart money activity, and token age.
**IMPORTANT - Hyperliquid Special Case:**
- Hyperliquid chain queries perpetual futures (perps), not spot tokens
- When hyperliquid is mixed with other chains, two sections of up to 25 results each are returned - one for spot tokens and one for perps.
- For perps, only these filters are supported: volume, buyVolume, sellVolume, openInterest, netflow, nofTraders, traderType
- Perps support orderBy='price_change' for every traderType. Prices use completed 5-minute buckets at the timeframe boundaries.
- Additional orderBy fields for perps: open_interest, funding (e.g. orderBy 'funding' ascending finds perps that pay longs)
- Unsupported filters/orderBy will fallback to defaults
INPUT EXAMPLES:
# Find tokens which are going up in price.
# Added some liquidity filter to remove spam and low quality tokens.
```
{
"chains": ["ethereum", "solana", "bnb", "base"],
"timeframe": "24h",
"liquidity": {"from": 100000},
"nofTraders": {"from": 10},
"orderBy": "price_change",
"orderByDirection": "desc"
}
```
# Find top stablecoins by market cap
```
{
"chains": ["ethereum", "solana", "bnb", "base"],
"timeframe": "7d",
"sectors": ["Stablecoin"],
"orderBy": "market_cap_usd",
"orderByDirection": "desc"
}
```
# Find AI memecoins with high trading activity
{
"chains": ["ethereum", "solana", "bnb", "base"],
"timeframe": "7d",
"sectors": ["AI Meme"],
"liquidity": {"from": 100000},
"volume": {"from": 1000000}
}
# Find DeFi lending tokens
{
"chains": ["ethereum", "solana", "bnb", "base"],
"timeframe": "24h",
"sectors": ["DeFi Lending (Money Markets)"],
"netflow": {"from": 1000000}
}
# Find tokens which have a lot of buying activity (high nofBuyers and buyVolume)
# Note that we added some filters to remove spam and low quality tokens. We added liquidity filter so that we only surface tokens which we can buy or sell.
# We sort by `netflow` descending to get tokens with the most net buying activity.
```
{
"chains": ["ethereum", "solana", "bnb", "base"],
"timeframe": "24h",
"liquidity": {"from": 100000},
"buyVolume": {"from": 1000000},
"marketCapUsd": {"from": 1000000},
"nofBuyers": {"from": 10},
"orderBy": "netflow",
"orderByDirection": "desc"
}
```
# Find Hyperliquid perps with high open interest and positive net flow
```
{
"chains": ["hyperliquid"],
"timeframe": "7d",
"openInterest": {"from": 100000},
"volume": {"from": 1000000},
"netflow": {"from": 0},
"nofTraders": {"from": 10},
"orderBy": "netflow",
"orderByDirection": "desc"
}
```
WARNING: To avoid timeouts, it's recommended to:
- Use 4 chains or less at a time (API tends to timeout with more chains)
- Use shorter timeframes (e.g., 24h or 1h instead of 7d or 30d)
Args:
Returns:
Comprehensive token metrics as markdown. Returns empty string if no tokens found.
Columns returned:
- **Token Address**: Token address (e.g., 0x1234567890123456789012345678901234567890)
- **Symbol**: Token trading symbol (e.g., ETH, BTC, DOGE)
- **Chain**: Blockchain network (ethereum, solana, polygon, etc.)
- **Price Change**: Price change percentage over the date range (percentage, can be negative)
- **Market Cap**: Current market capitalization (currency formatted)
- **Fully Diluted Valuation (FDV)**: Market cap if all tokens were circulating (currency formatted)
- **FDV/MC Ratio**: Ratio indicating how much supply is locked/vested (numeric, >1 means locked supply)
- **USD Volume**: Total trading volume in USD (currency formatted)
- **Buy USD Volume**: Total buy volume in USD (currency formatted)
- **Sell USD Volume**: Total sell volume in USD (currency formatted)
- **Net Flow USD**: Net flow (buys minus sells) in USD (currency formatted, can be negative)
- **Traders**: Number of wallets of the selected traderType that traded the token. Without traderType, it counts all traders, not Smart Money (shown only with a nofTraders filter or sort). One wallet can cause most of the Net Flow USD also when Traders is more than 1. Use token_who_bought_sold before you report broad Smart Money buying.
- **DEX Liquidity**: Available liquidity for trading (currency formatted)
- **Inflow/FDV**: Inflow as percentage of FDV (percentage formatted)
- **Outflow/FDV**: Outflow as percentage of FDV (percentage formatted)
- **Token Age (Days)**: Days since token was first deployed
- **Sectors**: List of token sectors/categories
Hyperliquid perps columns (smart-money mode, when `onlySmartTradersAndFunds=true`):
- **Net Position** (`LONG $X` / `SHORT $X` / `FLAT`): current net direction. Use this when answering long/short questions.
- **Current Longs USD** / **Current Shorts USD**: gross notional on each side; sizing only, not direction.
- **Net Position Change**: delta over the timeframe — can be positive while Net Position is still SHORT.
Notes:
- Positive Net Flow on spot tokens indicates more buying than selling
- High FDV/MC Ratio suggests significant locked or vested tokens
**Filtering Options** (filters parameter):
- **Numeric Ranges**: volume, liquidity, marketCapUsd, netflow, tokenAgeDays, nofTraders, nofBuyers, nofSellers, nofBuys, nofSells, buyVolume, sellVolume, fdv, fdvMcRatio, inflowFdvRatio, outflowFdvRatio, priceChange (spot, in percent)
- **Categories**: sectors (e.g. ["AI", "Meme"]), includeSmartMoneyLabels
- **Asset class toggles** (spot chains only, default false for both): includeStablecoins, includeNativeTokens. Set true only when the user asks for stablecoins/native tokens specifically.
- **Asset types in results**: spot rows can include tokenized stocks (e.g. TSLAX), wrapped or bridged majors (e.g. WETH, cbBTC) and yield dollar tokens (e.g. sUSDe). Their price follows the underlying asset, and their market cap counts only the supply on that chain, so they are not small caps or new tokens. Leave them out of crypto-token picks unless the user asks for stocks or majors.
- **Trader Type**: traderType (string: "all", "sm", "whale", "public_figure")
- Use "sm" ONLY when user explicitly asks for "smart money".
- Use "whale" ONLY when user specifically asks for whales or large holders.
- Use "public_figure" ONLY when user asks for KOLs or popular figures.
- Data with "sm", "whale", and "public_figure" is sparse — "whale" and "public_figure" are even sparser than "sm". Pairing any of these with other filters (volume, liquidity, netflow) is likely to return no results.
- Only pair traderType="sm/whale/public_figure" with other filters (volume, liquidity, netflow) if the user request explicitly requires it.
- Instead of pairing this with other filters, you can rely on orderBy to sort by netflow, volume, liquidity, etc.
**priceChange** filters spot tokens by price change over the timeframe, in percent: {"to": 20} skips tokens that already rose more than 20%; {"from": 10} keeps tokens up at least 10%.
**Sorting Options** (orderBy field):
Available fields (use with orderByDirection: "asc" or "desc"):
- **priceUsd**: Sort by token price
- **priceChange**: Sort by price change percentage
- **marketCapUsd**: Sort by market capitalization
- **volume**: Sort by total trading volume
- **buyVolume**: Sort by buy volume
- **sellVolume**: Sort by sell volume
- **netflow**: Sort by net flow (buys - sells)
- **liquidity**: Sort by DEX liquidity
- **nofTraders**: Sort by number of traders
(Note: Fields like `tokenAgeDays` or `outflowFdvRatio` are for FILTERING only, not sorting)
Default: orderBy="netflow", orderByDirection="desc"
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › chains
Blockchain networks to query. Maximum of 5 chains can be specified. Supported: arbitrum, arc, avalanche, base, bitcoin, bnb, citrea, ethereum, hyperevm, hyperliquid, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, robinhood, sei, solana, sonic, starknet, sui, ton, tron.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › timeframe
Time window for token data.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › tokenAgeDays › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › tokenAgeDays › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › marketCapUsd › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › marketCapUsd › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › fdv › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › fdv › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › fdvMcRatio › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › fdvMcRatio › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofTraders › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofTraders › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofBuyers › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofBuyers › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofSellers › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofSellers › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofBuys › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofBuys › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofSells › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › nofSells › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › buyVolume › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › buyVolume › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › sellVolume › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › sellVolume › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › volume › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › volume › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › netflow › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › netflow › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › inflowFdvRatio › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › inflowFdvRatio › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › outflowFdvRatio › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › outflowFdvRatio › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › priceChange › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › priceChange › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › liquidity › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › liquidity › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › openInterest › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › openInterest › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › sectors
List of sectors to filter tokens by (on-chain spot only). Leave empty for no filtering.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › perpSectors
Hyperliquid perps sector filter. Only applies when 'hyperliquid' is in chains; ignored for spot. Leave empty for no filtering.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeSmartMoneyLabels
List of smart money labels to filter by (default: empty list). Use 'Any Smart Money' to include all smart money types. Requires traderType 'sm' (omitted/'all' auto-corrects to 'sm'; combining with 'whale' or 'public_figure' is an error).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeStablecoins
Whether to include stablecoins (e.g. USDT, USDC, DAI) in results. Applies to spot chains only. Default false: the screener finds 'interesting' tokens, so set true only when the user asks for stablecoins specifically.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeNativeTokens
Whether to include wrapped native tokens (e.g. WETH, WBNB) in results. Applies to spot chains only. Default false: the screener finds 'interesting' tokens, so set true only when the user asks for native tokens specifically.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › traderType
Filter by trader cohort ('sm' = smart money). Omit or 'all' for all traders. 'high_winrate_hl_perps_trader' is Hyperliquid-perps only. includeSmartMoneyLabels only applies with 'sm'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. Pass an exact value above or None for default ('netflow'). 'funding' and 'open_interest' sort Hyperliquid perps only; spot results fall back to 'netflow'. 'price_change' sorts Hyperliquid perps across all trader types.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderByDirection
Sort direction: 'ASC' or 'DESC' (case-insensitive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number, starting at 1. Each page returns up to 25 tokens.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
Get OHLCV (Open, High, Low, Close, Volume) price data for a token with automatic interval resolution.
Supports EVM chains and Solana for on-chain tokens, AND Hyperliquid perpetual futures.
For Hyperliquid perps, pass `chain="hyperliquid"` and use the perp symbol as `tokenAddress` (e.g. "BTC", "HYPE" for native perps; "XYZ:ORDI" for XYZ-namespaced perps — prefix is normalized automatically).
Use this tool for current and historical prices. The output starts with the current price.
To get **LATEST** price set from to '5MIN_AGO' and to to 'NOW'.
Resolution is automatically calculated based on the date range
- < 6 hours: 5 minutes
- 6 hours - 1 day: 15 minutes
- 1-3 days: 30 minutes
- 3-7 days: 60 minutes (1 hour)
- 7-90 days: Daily
- 90+ days: Weekly
Columns returned:
- **Interval Start**: Timestamp of the start of the interval (datetime: YYYY-MM-DD HH:MM:SS)
- **Open**: Opening price of the interval
- **High**: Highest price of the interval
- **Low**: Lowest price of the interval
- **Close**: Closing price of the interval
- **Volume USD**: Volume in USD of the interval
Additional columns (when includeMarketCap=true):
- **Open Market Cap**: Opening market cap in USD
- **Close Market Cap**: Closing market cap in USD
- **High Market Cap**: Highest market cap in USD
- **Low Market Cap**: Lowest market cap in USD
Example Usage:
Get OHLCV for WETH over the past week (auto-resolution):
```
{
"chain": "ethereum",
"tokenAddress": "0xba5ddd1f9d7f570dc94a51479a000e3bce967196",
"date": {
"from": "7D_AGO",
"to": "NOW"
}
}
```
Get OHLCV for WETH over 30 days (will use daily resolution):
```
{
"chain": "ethereum",
"tokenAddress": "0xba5ddd1f9d7f570dc94a51479a000e3bce967196",
"date": {
"from": "30D_AGO",
"to": "NOW"
}
}
```
Get OHLCV for WETH for last 20 minutes (will use 5 minute resolution):
```
{
"chain": "ethereum",
"tokenAddress": "0xba5ddd1f9d7f570dc94a51479a000e3bce967196",
"date": {
"from": "20MIN_AGO",
"to": "NOW"
}
}
```
Get OHLCV for the BTC Hyperliquid perp over 7 days:
```
{
"chain": "hyperliquid",
"tokenAddress": "BTC",
"date": {
"from": "7D_AGO",
"to": "NOW"
}
}
```
The description explains the capability, when to use it, and what to expect.
Inputs49/100
3 of 5 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › chain
Not provided
Missing description. Explain what this value means and how to supply it.
request › tokenAddress
Not provided
Missing description. Explain what this value means and how to supply it.
request › date › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › date › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeMarketCap
Include market cap fields (openMcap, closeMcap, highMcap, lowMcap). Default: false for cleaner output
Clear enough to supply this argument.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "token_ohlcv",
"title": "Loading price data",
"description": "Get OHLCV (Open, High, Low, Close, Volume) price data for a token with automatic interval resolution.\n\nSupports EVM chains and Solana for on-chain tokens, AND Hyperliquid perpetual futures.\nFor Hyperliquid perps, pass `chain=\"hyperliquid\"` and use the perp symbol as `tokenAddress` (e.g. \"BTC\", \"HYPE\" for native perps; \"XYZ:ORDI\" for XYZ-namespaced perps — prefix is normalized automatically).\n\nUse this tool for current and historical prices. The output starts with the current price.\nTo get **LATEST** price set from to '5MIN_AGO' and to to 'NOW'.\n\n\nResolution is automatically calculated based on the date range\n- < 6 hours: 5 minutes\n- 6 hours - 1 day: 15 minutes\n- 1-3 days: 30 minutes\n- 3-7 days: 60 minutes (1 hour)\n- 7-90 days: Daily\n- 90+ days: Weekly\n\nColumns returned:\n- **Interval Start**: Timestamp of the start of the interval (datetime: YYYY-MM-DD HH:MM:SS)\n- **Open**: Opening price of the interval\n- **High**: Highest price of the interval\n- **Low**: Lowest price of the interval\n- **Close**: Closing price of the interval\n- **Volume USD**: Volume in USD of the interval\n\nAdditional columns (when includeMarketCap=true):\n- **Open Market Cap**: Opening market cap in USD\n- **Close Market Cap**: Closing market cap in USD\n- **High Market Cap**: Highest market cap in USD\n- **Low Market Cap**: Lowest market cap in USD\n\nExample Usage:\n Get OHLCV for WETH over the past week (auto-resolution):\n ```\n {\n \"chain\": \"ethereum\",\n \"tokenAddress\": \"0xba5ddd1f9d7f570dc94a51479a000e3bce967196\",\n \"date\": {\n \"from\": \"7D_AGO\",\n \"to\": \"NOW\"\n }\n }\n ```\n\n Get OHLCV for WETH over 30 days (will use daily resolution):\n ```\n {\n \"chain\": \"ethereum\",\n \"tokenAddress\": \"0xba5ddd1f9d7f570dc94a51479a000e3bce967196\",\n \"date\": {\n \"from\": \"30D_AGO\",\n \"to\": \"NOW\"\n }\n }\n ```\n Get OHLCV for WETH for last 20 minutes (will use 5 minute resolution):\n ```\n {\n \"chain\": \"ethereum\",\n \"tokenAddress\": \"0xba5ddd1f9d7f570dc94a51479a000e3bce967196\",\n \"date\": {\n \"from\": \"20MIN_AGO\",\n \"to\": \"NOW\"\n }\n }\n ```\n\n Get OHLCV for the BTC Hyperliquid perp over 7 days:\n ```\n {\n \"chain\": \"hyperliquid\",\n \"tokenAddress\": \"BTC\",\n \"date\": {\n \"from\": \"7D_AGO\",\n \"to\": \"NOW\"\n }\n }\n ```",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"chain",
"tokenAddress",
"date"
],
"properties": {
"date": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight."
},
"from": {
"type": "string",
"description": "Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
}
},
"description": "Date range for OHLCV data with 'from' and 'to' fields",
"additionalProperties": false
},
"chain": {
"type": "string"
},
"tokenAddress": {
"type": "string"
},
"includeMarketCap": {
"type": "boolean",
"default": false,
"description": "Include market cap fields (openMcap, closeMcap, highMcap, lowMcap). Default: false for cleaner output"
}
},
"description": "Unified request model for TGM OHLCV endpoint (flattened).\n\nResolution is automatically calculated based on the date range to keep\nresponses at approximately 100 rows, preventing context overflow.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
Align the title with the capability actually described by this tool.
Description99/100
Get a technical-analysis snapshot for a token: SMA(20/50/200), EMA(12/26) and EMA(20/50/200), RSI(14), MACD(12,26,9), Bollinger Bands(20, 2σ), ATR(14), and rolling VWAP(20), computed from the last 1,000 closed candles at an explicit timeframe.
Supports EVM chains and Solana for on-chain tokens, AND Hyperliquid perpetual futures.
For Hyperliquid perps, pass `chain="hyperliquid"` and use the perp symbol as `tokenAddress` (e.g. "BTC", "HYPE" for native perps; "XYZ:ORDI" for XYZ-namespaced perps — prefix is normalized automatically).
**YOU MUST USE THIS** for technical analysis instead of computing indicators from raw `token_ohlcv` candles — it uses far more history (1,000 closed candles) and charting-platform conventions (SMA-seeded EMA, Wilder RSI/ATR, population-σ Bollinger).
Timeframes (explicit, no auto-resolution):
- 5m / 15m / 30m / 1h / 4h: intraday and short-horizon analysis
- 1d (default): swing/position horizon
- 1w: long-term trend
Output: a snapshot header (candles used, date range, last close, 5-candle price change) plus one row per indicator, each with a 5-candle trend delta so you can read direction, not just level:
- **SMA 20/50/200**: values, price vs each, MA slopes
- **EMA 12/26**: values, spread %, widening/narrowing
- **EMA 20/50/200**: values, price vs each
- **RSI(14)**: level, prior candle, 5-candle change
- **MACD(12,26,9)**: line/signal/histogram, rising/falling, candles since signal cross
- **Bollinger(20,2σ)**: bands, %B, bandwidth and its change
- **ATR(14)**: value and % of price (volatility), rising/falling
- **VWAP(20)**: value, price vs VWAP
Indicators without enough closed-candle history render as n/a (e.g. SMA200 on young tokens); the candle count used is always reported. VWAP is n/a on Hyperliquid 5m-1h timeframes (volume is NULL in those views) — use 4h or 1d for Hyperliquid VWAP.
Example Usage:
Daily technical snapshot for WETH:
```
{
"chain": "ethereum",
"tokenAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"timeframe": "1d"
}
```
4-hour snapshot for the BTC Hyperliquid perp:
```
{
"chain": "hyperliquid",
"tokenAddress": "BTC",
"timeframe": "4h"
}
```
The description explains the capability, when to use it, and what to expect.
Inputs25/100
1 of 3 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › chain
Not provided
Missing description. Explain what this value means and how to supply it.
request › tokenAddress
Not provided
Missing description. Explain what this value means and how to supply it.
request › timeframe
Candle timeframe for the indicator computation: 5m, 15m, 30m, 1h, 4h, 1d, or 1w. Default: 1d.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "token_technical_indicators",
"title": "Loading technical indicators",
"description": "Get a technical-analysis snapshot for a token: SMA(20/50/200), EMA(12/26) and EMA(20/50/200), RSI(14), MACD(12,26,9), Bollinger Bands(20, 2σ), ATR(14), and rolling VWAP(20), computed from the last 1,000 closed candles at an explicit timeframe.\n\nSupports EVM chains and Solana for on-chain tokens, AND Hyperliquid perpetual futures.\nFor Hyperliquid perps, pass `chain=\"hyperliquid\"` and use the perp symbol as `tokenAddress` (e.g. \"BTC\", \"HYPE\" for native perps; \"XYZ:ORDI\" for XYZ-namespaced perps — prefix is normalized automatically).\n\n**YOU MUST USE THIS** for technical analysis instead of computing indicators from raw `token_ohlcv` candles — it uses far more history (1,000 closed candles) and charting-platform conventions (SMA-seeded EMA, Wilder RSI/ATR, population-σ Bollinger).\n\nTimeframes (explicit, no auto-resolution):\n- 5m / 15m / 30m / 1h / 4h: intraday and short-horizon analysis\n- 1d (default): swing/position horizon\n- 1w: long-term trend\n\nOutput: a snapshot header (candles used, date range, last close, 5-candle price change) plus one row per indicator, each with a 5-candle trend delta so you can read direction, not just level:\n- **SMA 20/50/200**: values, price vs each, MA slopes\n- **EMA 12/26**: values, spread %, widening/narrowing\n- **EMA 20/50/200**: values, price vs each\n- **RSI(14)**: level, prior candle, 5-candle change\n- **MACD(12,26,9)**: line/signal/histogram, rising/falling, candles since signal cross\n- **Bollinger(20,2σ)**: bands, %B, bandwidth and its change\n- **ATR(14)**: value and % of price (volatility), rising/falling\n- **VWAP(20)**: value, price vs VWAP\n\nIndicators without enough closed-candle history render as n/a (e.g. SMA200 on young tokens); the candle count used is always reported. VWAP is n/a on Hyperliquid 5m-1h timeframes (volume is NULL in those views) — use 4h or 1d for Hyperliquid VWAP.\n\nExample Usage:\n Daily technical snapshot for WETH:\n ```\n {\n \"chain\": \"ethereum\",\n \"tokenAddress\": \"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\n \"timeframe\": \"1d\"\n }\n ```\n\n 4-hour snapshot for the BTC Hyperliquid perp:\n ```\n {\n \"chain\": \"hyperliquid\",\n \"tokenAddress\": \"BTC\",\n \"timeframe\": \"4h\"\n }\n ```",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"chain",
"tokenAddress"
],
"properties": {
"chain": {
"type": "string"
},
"timeframe": {
"enum": [
"5m",
"15m",
"30m",
"1h",
"4h",
"1d",
"1w"
],
"type": "string",
"default": "1d",
"description": "Candle timeframe for the indicator computation: 5m, 15m, 30m, 1h, 4h, 1d, or 1w. Default: 1d."
},
"tokenAddress": {
"type": "string"
}
},
"description": "Request for the token_technical_indicators tool (explicit timeframe,\nalways computed up to now — no date range).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › tokenAddress
Not provided
Missing description. Explain what this value means and how to supply it.
request › mode
Analysis mode: 'onchain_tokens' for on-chain token information, 'perps' for Hyperliquid perpetual futures stats by symbol. If mode is omitted and token_address is a symbol (not a contract address), mode defaults to 'perps'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › timeframe
Timeframe for token metrics (5m, 1h, 6h, 12h, 1d, 7d)
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Get Nansen Score Indicators for a token - quantitative risk and reward signals.
Use this tool when assessing a token's risk/reward profile, evaluating buy/sell decisions,
or when the user needs quantitative data to make trading decisions.
Returns:
Token risk/reward indicators as markdown with interpretation guidance.
Token info:
- **Market Cap**: Current market cap in USD
- **Market Cap Group**: largecap (>$1B), midcap ($100M-$1B), or lowcap (<$100M)
- **Is Stablecoin**: Whether token is a stablecoin (some indicators don't apply to stablecoins)
Fields returned per indicator:
- **Score**: Signal classification (bullish/neutral/bearish for reward; low/medium/high for risk)
- **Signal**: Raw numeric value of the indicator
- **Percentile**: Rank vs same market cap group (0-100%)
- **Last Trigger**: Date when signal was last calculated
Indicator types:
- **Reward Indicators**: price-momentum, funding-rate, chain-fees, chain-tvl, protocol-fees, trading-range
- **Risk Indicators**: btc-reflexivity, liquidity-risk, token-supply-inflation, concentration-risk, cex-flows
Notes:
- Not all indicators available for every token/chain combination
- Percentile compares against same market cap group (largecap >$1B, midcap $100M-$1B, lowcap <$100M)
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
request › chain
Blockchain chain (ethereum, solana, base, bnb, polygon, arbitrum, etc.). On-chain tokens only — Hyperliquid perps NOT supported.
Clear enough to supply this argument.
request › tokenAddress
Token contract address
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Discover and filter a daily list of attractive tokens using Nansen Score Indicators weighted by coefficients (= Performance Score).
Use this tool when you don't know which tokens to buy and need recommendations based on backtested indicators.
For specific token analysis (e.g., "should I buy AAVE?"), use token_quant_scores instead.
**When to use this tool vs token_discovery_screener**:
- Use **this tool** when you want **pre-scored buying recommendations** without specifying criteria. It answers "what should I buy?" by returning tokens that already meet a quantitative buying threshold (Performance Score ≥15) based on alpha indicators like price momentum, chain fees, and protocol fees. Data is updated in batches.
- Use **token_discovery_screener** when you want **live data** or to **explore tokens by specific criteria** like sectors (e.g., "AI memecoins"), token age (e.g., "new launches"), smart money activity, or custom volume/liquidity thresholds. It's a filtering tool with real-time metrics where you define what you're looking for.
Returns tokens pre-filtered by: performance_score >= 15 (buying threshold).
**Example queries**: "what tokens should I buy?", "which tokens look good?", "best tokens to buy today"
**Scoring:**
- **Performance Score** (range -60 to +75): Higher = better alpha opportunity. **Buy threshold: ≥15**
- **Risk Score** (range -60 to +80): Higher = safer token. >0 indicates low to medium risk.
Every time you give the Performance Score to the user, explain the scoring thresholds above. Same for the Risk Score. Every time quote the underlying indicators that contributed the most to the Performance/ Risk score and recall their definition to the user.
Returns:
A list of tokens with the highest Performance Score as markdown.
Core fields: Token Address, Token Symbol, Chain, Performance Score, Risk Score.
Indicator columns are included dynamically based on data availability (columns with all zeros are excluded).
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › marketCapGroup
Filter by market cap group: 'lowcap' (<$100M), 'midcap' ($100M-$1B), 'largecap' (>$1B). Default: all groups
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "nansen_score_top_tokens",
"title": "Ranking top tokens by Nansen Score",
"description": "Discover and filter a daily list of attractive tokens using Nansen Score Indicators weighted by coefficients (= Performance Score).\n\nUse this tool when you don't know which tokens to buy and need recommendations based on backtested indicators.\nFor specific token analysis (e.g., \"should I buy AAVE?\"), use token_quant_scores instead.\n\n**When to use this tool vs token_discovery_screener**:\n- Use **this tool** when you want **pre-scored buying recommendations** without specifying criteria. It answers \"what should I buy?\" by returning tokens that already meet a quantitative buying threshold (Performance Score ≥15) based on alpha indicators like price momentum, chain fees, and protocol fees. Data is updated in batches.\n- Use **token_discovery_screener** when you want **live data** or to **explore tokens by specific criteria** like sectors (e.g., \"AI memecoins\"), token age (e.g., \"new launches\"), smart money activity, or custom volume/liquidity thresholds. It's a filtering tool with real-time metrics where you define what you're looking for.\n\nReturns tokens pre-filtered by: performance_score >= 15 (buying threshold).\n\n**Example queries**: \"what tokens should I buy?\", \"which tokens look good?\", \"best tokens to buy today\"\n\n**Scoring:**\n- **Performance Score** (range -60 to +75): Higher = better alpha opportunity. **Buy threshold: ≥15**\n- **Risk Score** (range -60 to +80): Higher = safer token. >0 indicates low to medium risk.\n\nEvery time you give the Performance Score to the user, explain the scoring thresholds above. Same for the Risk Score. Every time quote the underlying indicators that contributed the most to the Performance/ Risk score and recall their definition to the user.\n\nReturns:\n A list of tokens with the highest Performance Score as markdown.\n\n Core fields: Token Address, Token Symbol, Chain, Performance Score, Risk Score.\n Indicator columns are included dynamically based on data availability (columns with all zeros are excluded).",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"properties": {
"marketCapGroup": {
"anyOf": [
{
"enum": [
"lowcap",
"midcap",
"largecap"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Filter by market cap group: 'lowcap' (<$100M), 'midcap' ($100M-$1B), 'largecap' (>$1B). Default: all groups"
}
},
"description": "Request model for Nansen Score Top Tokens endpoint (flattened).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description96/100
Get Hyperliquid perpetual futures trader leaderboard with performance metrics.
Returns:
Trader performance rankings as markdown.
Columns returned:
- **Address** / **Label**: trader wallet, and its Nansen label if any
- **Total PnL** (USD): realized + unrealized over the date range
- **Realized PnL** (USD): net, from positions closed in the range. Being a net total it shows no per-trade outcome, so no win rate can be derived from it or any other column here
- **Unrealized PnL** (USD): on positions still open, at the current mark price
- **ROI** (%): Total PnL / (traded notional + open notional) — PnL per dollar traded, not return on capital
- **Volume** (USD): traded notional; both fills of a position count
- **Trades**: number of fills
- **Account Value** (USD): only available for the top 500K traders
This is an overview of top traders and their headline stats. For a trader's
open positions, call `address_portfolio` with `mode='hyperliquid'`.
**Sorting**: total_pnl, realized_pnl_usd, unrealized_pnl_usd, roi, volume_usd, total_trades, account_value
**Filtering** (from/to): totalPnl (USD), accountValue (USD), roi (a fractional ratio, not the percent shown — pass 0.1 for "10% or better", not 10)
Example:
```
{
"date": {"from": "7D_AGO", "to": "NOW"},
"accountValue": {"from": 100000, "to": 1000000},
"totalPnl": {"from": 10000},
"order_by": "total_pnl",
"orderByDirection": "DESC"
}
```
Rank by traded volume instead: `"order_by": "volume_usd"`
Notes:
- Hyperliquid perpetual futures only
- Dates use UTC calendar boundaries, not rolling timestamps. Calendar end dates retain the next-day API boundary.
- Null/empty means data is not available — do not read it as zero
The description explains the capability, when to use it, and what to expect.
Inputs68/100
10 of 11 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › date › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › date › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › accountValue › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › accountValue › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › totalPnl › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › totalPnl › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › roi › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › roi › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
request › order_by
Sort field. Pass an exact value above or None for default ('total_pnl').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderByDirection
Sort direction: 'ASC' or 'DESC' (case-insensitive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "hyperliquid_leaderboard",
"title": "Checking Hyperliquid leaderboard",
"description": "Get Hyperliquid perpetual futures trader leaderboard with performance metrics.\n\nReturns:\n Trader performance rankings as markdown.\n\n Columns returned:\n - **Address** / **Label**: trader wallet, and its Nansen label if any\n - **Total PnL** (USD): realized + unrealized over the date range\n - **Realized PnL** (USD): net, from positions closed in the range. Being a net total it shows no per-trade outcome, so no win rate can be derived from it or any other column here\n - **Unrealized PnL** (USD): on positions still open, at the current mark price\n - **ROI** (%): Total PnL / (traded notional + open notional) — PnL per dollar traded, not return on capital\n - **Volume** (USD): traded notional; both fills of a position count\n - **Trades**: number of fills\n - **Account Value** (USD): only available for the top 500K traders\n\nThis is an overview of top traders and their headline stats. For a trader's\nopen positions, call `address_portfolio` with `mode='hyperliquid'`.\n\n**Sorting**: total_pnl, realized_pnl_usd, unrealized_pnl_usd, roi, volume_usd, total_trades, account_value\n\n**Filtering** (from/to): totalPnl (USD), accountValue (USD), roi (a fractional ratio, not the percent shown — pass 0.1 for \"10% or better\", not 10)\n\nExample:\n ```\n {\n \"date\": {\"from\": \"7D_AGO\", \"to\": \"NOW\"},\n \"accountValue\": {\"from\": 100000, \"to\": 1000000},\n \"totalPnl\": {\"from\": 10000},\n \"order_by\": \"total_pnl\",\n \"orderByDirection\": \"DESC\"\n }\n ```\n Rank by traded volume instead: `\"order_by\": \"volume_usd\"`\n\nNotes:\n - Hyperliquid perpetual futures only\n - Dates use UTC calendar boundaries, not rolling timestamps. Calendar end dates retain the next-day API boundary.\n - Null/empty means data is not available — do not read it as zero",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"date"
],
"properties": {
"roi": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value (inclusive), optional"
},
"from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value (inclusive), optional"
}
},
"description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Filter by ROI (from/to)"
},
"date": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight."
},
"from": {
"type": "string",
"description": "Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
}
},
"description": "Date range",
"additionalProperties": false
},
"page": {
"type": "integer",
"default": 1
},
"order_by": {
"anyOf": [
{
"enum": [
"total_pnl",
"realized_pnl_usd",
"unrealized_pnl_usd",
"roi",
"volume_usd",
"total_trades",
"account_value"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort field. Pass an exact value above or None for default ('total_pnl')."
},
"totalPnl": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value (inclusive), optional"
},
"from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value (inclusive), optional"
}
},
"description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Filter by total PnL (from/to)"
},
"accountValue": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value (inclusive), optional"
},
"from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value (inclusive), optional"
}
},
"description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Filter by account value (from/to)"
},
"orderByDirection": {
"enum": [
"ASC",
"DESC",
"asc",
"desc"
],
"type": "string",
"default": "DESC",
"description": "Sort direction: 'ASC' or 'DESC' (case-insensitive)."
}
},
"description": "Request for Hyperliquid perp leaderboard (flattened).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Get Jupiter DCA (dollar-cost-averaging) orders opened against a Solana token, with deposit size, amount spent so far, amount accumulated and order status.
Use this to see scheduled buying or selling pressure that has not hit the market yet; use token_dex_trades for trades already executed. Solana tokens only.
The description explains the capability, when to use it, and what to expect.
Inputs61/100
6 of 7 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › tokenAddress
Token address on Solana
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
request › status
Filter by DCA order status
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › traderAddress
Filter by trader address
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › depositUsdValue › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › depositUsdValue › anyOf › 0 › to
Maximum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeSmartMoneyLabels
Restrict to traders holding these smart money labels
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description72/100
Get historical native coin & token balances of address.
For a trader, send trader_id instead of address or entity_id: the daily
USD balances of all wallets of the trader.
# Query by trader
{"trader_id": "5482f9aeb02f67b7", "lookbackDays": 30}
Describe the returned information so the agent knows whether it will answer the request.
Inputs50/100
5 of 6 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › trader_id
Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. With trader_id, suspiciousFilter is not used, the default lookbackDays is 30, there is one point per day, and the rows are the 5 largest tokens, the other tokens together and the total portfolio value.
Clear enough to supply this argument.
request › address
Single wallet address to analyze. REQUIRED if entity_id and trader_id are not provided. Cannot be used together with entity_id or trader_id.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › entity_id
Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). REQUIRED if address and trader_id are not provided. Cannot be used together with address or trader_id.
Resolve the mismatch between this description and its schema constraints.
request › chain
Not provided
Missing description. Explain what this value means and how to supply it.
request › suspiciousFilter
Whether to exclude suspicious tokens
Explain the meaning of this value, not just its name.
request › lookbackDays
Days to look back for historical balances. Use 1, 7, 30, 90, 120, 365, or 730. Use ALL_TIME for full history.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "address_historical_balances",
"title": "Checking balance history",
"description": "Get historical native coin & token balances of address.\n\nFor a trader, send trader_id instead of address or entity_id: the daily\nUSD balances of all wallets of the trader.\n\n# Query by trader\n{\"trader_id\": \"5482f9aeb02f67b7\", \"lookbackDays\": 30}",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"properties": {
"chain": {
"type": "string",
"default": "all"
},
"address": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single wallet address to analyze. REQUIRED if entity_id and trader_id are not provided. Cannot be used together with entity_id or trader_id."
},
"entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). REQUIRED if address and trader_id are not provided. Cannot be used together with address or trader_id."
},
"trader_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. With trader_id, suspiciousFilter is not used, the default lookbackDays is 30, there is one point per day, and the rows are the 5 largest tokens, the other tokens together and the total portfolio value."
},
"lookbackDays": {
"anyOf": [
{
"enum": [
1,
7,
30,
90,
120,
365,
730
],
"type": "integer"
},
{
"const": "ALL_TIME"
}
],
"default": 1,
"description": "Days to look back for historical balances. Use 1, 7, 30, 90, 120, 365, or 730. Use ALL_TIME for full history."
},
"suspiciousFilter": {
"enum": [
"on",
"off"
],
"type": "string",
"default": "on",
"description": "Whether to exclude suspicious tokens"
}
},
"description": "Complete request for address historical balances (flattened).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description87/100
Get information about related addresses of an input address.
Note: This only includes the the "special" connections 'First Funder', 'Signer', 'Previous Signer', 'Multisig Signer of', 'Previous Multisig Signer of', 'Deployed via', 'Deployed by', 'Deployed Contract', 'Created Contract', 'Created by'.
To get related wallets, also check address counterparties.
First funder exchange withdrawal address does usually NOT belong to the same entity as the address, only deposit addresses. Only information is that it has been funded by the exchange.
The description explains the capability, when to use it, and what to expect.
Inputs50/100
1 of 2 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › address
Wallet address to analyze for related addresses
Clear enough to supply this argument.
request › chain
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
Get 25 (per page) addresses or entities with the most common interactions with input addresses
Default sort is net value transferred between them.
Also returns the top 3 tokens transferred by count for each counterparty
Note: To get related wallets:
- Focus on direct value transfers to get most likely addresses.
- Include CEX deposit addresses (not withdrawal addresses!) as well.
- Also go one level deeper:
- Find addresses that interacted with the most likely addresses.
- Find addresses that deposited to the same CEX deposit (NOT withdrawal!) addresses.
- Address structure / string is not important, but the relationship is!
Sorting Options (all fields support "ASC"/"DESC"):
Available for sorting: total_volume_usd, volume_in_usd, volume_out_usd, interaction_count
Examples:
# Query by single address
{
"address": "0x123...",
"sourceInput": "Combined",
"groupBy": "wallet",
"chain": "ethereum",
"timeRange": {"from": "30D_AGO", "to": "NOW"},
"order_by": "total_volume_usd",
"order_by_direction": "desc"
}
# Query by entity
{
"entity_id": "Binance",
"sourceInput": "Combined",
"groupBy": "entity",
"chain": "all",
"timeRange": {"from": "7D_AGO", "to": "NOW"}
}
For a trader, send trader_id instead of address or entity_id: the
counterparties of all wallets of the trader, at most 90 days.
# Query by trader
{
"trader_id": "5482f9aeb02f67b7",
"chain": "solana",
"timeRange": {"from": "30D_AGO", "to": "NOW"}
}
The description explains the capability, when to use it, and what to expect.
Inputs66/100
9 of 11 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › trader_id
Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. With trader_id, sourceInput and groupBy are not used, the window is at most 90 days. If the user asks for a longer period, use the longest window in one call. Do not split it, and do not replace it with calls per wallet address, because they cover only some wallets of the trader. Tell the user the 90-day limit and the dates of the window you used. The rows have no last interaction date and no tokens.
Clear enough to supply this argument.
request › address
Single wallet address to analyze. REQUIRED if entity_id and trader_id are not provided. Cannot be used together with entity_id or trader_id.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › entity_id
Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). REQUIRED if address and trader_id are not provided. Cannot be used together with address or trader_id.
Clear enough to supply this argument.
request › chain
Not provided
Missing description. Explain what this value means and how to supply it.
request › sourceInput
Source input type for counterparties analysis
Explain the meaning of this value, not just its name.
request › groupBy
Grouping method for counterparties analysis
Explain the meaning of this value, not just its name.
request › timeRange › anyOf › 0 › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Clear enough to supply this argument.
request › timeRange › anyOf › 0 › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Clear enough to supply this argument.
request › orderBy
Sort field. Pass an exact value above or None for default ('total_volume_usd').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › order_by_direction
Not provided
Missing description. Explain what this value means and how to supply it.
request › page
Page number, starting at 1
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "address_counterparties",
"title": "Analyzing wallet connections",
"description": "Get 25 (per page) addresses or entities with the most common interactions with input addresses\nDefault sort is net value transferred between them.\nAlso returns the top 3 tokens transferred by count for each counterparty\n\nNote: To get related wallets:\n- Focus on direct value transfers to get most likely addresses.\n- Include CEX deposit addresses (not withdrawal addresses!) as well.\n- Also go one level deeper:\n - Find addresses that interacted with the most likely addresses.\n - Find addresses that deposited to the same CEX deposit (NOT withdrawal!) addresses.\n- Address structure / string is not important, but the relationship is!\n\nSorting Options (all fields support \"ASC\"/\"DESC\"):\n Available for sorting: total_volume_usd, volume_in_usd, volume_out_usd, interaction_count\n\nExamples:\n# Query by single address\n{\n \"address\": \"0x123...\",\n \"sourceInput\": \"Combined\",\n \"groupBy\": \"wallet\",\n \"chain\": \"ethereum\",\n \"timeRange\": {\"from\": \"30D_AGO\", \"to\": \"NOW\"},\n \"order_by\": \"total_volume_usd\",\n \"order_by_direction\": \"desc\"\n}\n\n# Query by entity\n{\n \"entity_id\": \"Binance\",\n \"sourceInput\": \"Combined\",\n \"groupBy\": \"entity\",\n \"chain\": \"all\",\n \"timeRange\": {\"from\": \"7D_AGO\", \"to\": \"NOW\"}\n}\n\nFor a trader, send trader_id instead of address or entity_id: the\ncounterparties of all wallets of the trader, at most 90 days.\n\n# Query by trader\n{\n \"trader_id\": \"5482f9aeb02f67b7\",\n \"chain\": \"solana\",\n \"timeRange\": {\"from\": \"30D_AGO\", \"to\": \"NOW\"}\n}",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number, starting at 1"
},
"chain": {
"type": "string",
"default": "all"
},
"address": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single wallet address to analyze. REQUIRED if entity_id and trader_id are not provided. Cannot be used together with entity_id or trader_id."
},
"groupBy": {
"enum": [
"wallet",
"entity"
],
"type": "string",
"default": "wallet",
"description": "Grouping method for counterparties analysis"
},
"orderBy": {
"anyOf": [
{
"enum": [
"interaction_count",
"total_volume_usd",
"volume_in_usd",
"volume_out_usd"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort field. Pass an exact value above or None for default ('total_volume_usd')."
},
"entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). REQUIRED if address and trader_id are not provided. Cannot be used together with address or trader_id."
},
"timeRange": {
"anyOf": [
{
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight."
},
"from": {
"type": "string",
"description": "Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
}
},
"description": "Date range via tokens or dates.\nTokens: NOW, ALL_TIME, XMIN_AGO, XD_AGO, XH_AGO, XY_AGO; THIS_YEAR_START, THIS_QUARTER_START, THIS_MONTH_START, THIS_WEEK_START, TODAY_START; LAST_WEEK_START/END, LAST_MONTH_START/END, LAST_QUARTER_START/END, LAST_YEAR_START/END.\nDurations are exact rolling UTC timestamps at both ends: 1D_AGO equals 24H_AGO; 1Y_AGO equals 365 days. Bare duration aliases and case variants are supported.\nExplicit dates and calendar tokens keep calendar boundaries and inclusive final dates. TODAY_START is current-day midnight. Date-only endpoints keep their calendar contracts.\nALL_TIME is full history. It resolves to 2009-01-03. Use ALL_TIME instead of a very large day count.\nWeek starts Monday. Quarters are calendar. Dates: YYYY-MM-DD or ___-MM-DD (year omitted).\nPlease check detailed system instructions for more information.",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Date range for counterparties analysis. Omit for the last 30 days. Maximum window is 365 days. Longer ranges are clamped to the most recent year to prevent timeouts in fast/expert mode. The response reports the effective range. Prefer relative tokens such as 7D_AGO, 30D_AGO, 90D_AGO, or 1Y_AGO."
},
"trader_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. With trader_id, sourceInput and groupBy are not used, the window is at most 90 days. If the user asks for a longer period, use the longest window in one call. Do not split it, and do not replace it with calls per wallet address, because they cover only some wallets of the trader. Tell the user the 90-day limit and the dates of the window you used. The rows have no last interaction date and no tokens."
},
"sourceInput": {
"enum": [
"Combined",
"Tokens",
"ETH"
],
"type": "string",
"default": "Combined",
"description": "Source input type for counterparties analysis"
},
"order_by_direction": {
"enum": [
"ASC",
"DESC",
"asc",
"desc"
],
"type": "string",
"default": "DESC"
}
},
"description": "Complete request for address counterparties (flattened).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Get the top counterparties of up to 10 wallet addresses in one call.
Every wallet gets its own counterparty list. The lists are NOT added
together: the answer has one table for each wallet.
Use this tool to compare wallets — counterparties that two wallets share,
a group of wallets that sends to the same CEX deposit address, or one fund
with many wallets. For one wallet, or for an entity name, use
address_counterparties.
Limits:
- Maximum 10 distinct wallet addresses for each call. Repeated addresses
are removed.
- Maximum 90 days for the date range. A wider range is rejected — make
more than one call.
- One chain family for each call: every address must be EVM, or every
address must be Solana, and so on. Do not mix families.
Name a `chain` (for example ethereum) to read that chain only. Leave
`chain` out to read every chain of the addresses' family at one time —
then a counterparty met on more than one chain gets one row for each
chain, so do not add those rows together.
Sorting Options (all fields support "ASC"/"DESC"):
Available for sorting: total_volume_usd, volume_in_usd, volume_out_usd,
interaction_count. The sort is applied inside each wallet's block.
Example (every key below is the name the request accepts, and the
addresses are real — copy this shape as it stands):
{
"walletAddresses": [
"0x28c6c06298d514db089934071355e5743bf21d60",
"0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
],
"chain": "ethereum",
"timeRange": {"from": "30D_AGO", "to": "NOW"},
"sourceInput": "Combined",
"orderBy": "total_volume_usd",
"orderByDirection": "DESC",
"perPage": 100
}
The description explains the capability, when to use it, and what to expect.
Inputs71/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › walletAddresses
Wallet addresses to query, maximum 10 distinct addresses. Each wallet gets its own counterparty list — the results are NOT added together. Repeated addresses are removed. Every address must be on the same chain family: all EVM, or all Solana, or all Bitcoin. Do not mix families in one call.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › chain
Chain to read. Name one chain (for example ethereum or solana) to read that chain only. Leave this out to read every chain of the addresses' family at one time — with 'all', a counterparty met on more than one chain gets one row for each chain, so do not add the rows together. Supported chains: all, arbitrum, avalanche, base, bitcoin, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, robinhood, sei, solana, sonic, sui, ton, tron.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › sourceInput
Source input type for counterparties analysis
Explain the meaning of this value, not just its name.
request › timeRange › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Clear enough to supply this argument.
request › timeRange › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Drop counterparties that carry one of these labels
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field applied inside each wallet's block. Pass an exact value above or None for default ('total_volume_usd').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderByDirection
Sort direction: ASC or DESC
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number, starting at 1
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › perPage
Rows per page across all wallets in the batch, from 1 to 1000. The rows of one wallet stay together, so keep this high enough to cover every wallet you asked for.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "address_counterparties_batch",
"title": "Comparing wallet connections",
"description": "Get the top counterparties of up to 10 wallet addresses in one call.\n\nEvery wallet gets its own counterparty list. The lists are NOT added\ntogether: the answer has one table for each wallet.\n\nUse this tool to compare wallets — counterparties that two wallets share,\na group of wallets that sends to the same CEX deposit address, or one fund\nwith many wallets. For one wallet, or for an entity name, use\naddress_counterparties.\n\nLimits:\n- Maximum 10 distinct wallet addresses for each call. Repeated addresses\n are removed.\n- Maximum 90 days for the date range. A wider range is rejected — make\n more than one call.\n- One chain family for each call: every address must be EVM, or every\n address must be Solana, and so on. Do not mix families.\n\nName a `chain` (for example ethereum) to read that chain only. Leave\n`chain` out to read every chain of the addresses' family at one time —\nthen a counterparty met on more than one chain gets one row for each\nchain, so do not add those rows together.\n\nSorting Options (all fields support \"ASC\"/\"DESC\"):\n Available for sorting: total_volume_usd, volume_in_usd, volume_out_usd,\n interaction_count. The sort is applied inside each wallet's block.\n\nExample (every key below is the name the request accepts, and the\naddresses are real — copy this shape as it stands):\n{\n \"walletAddresses\": [\n \"0x28c6c06298d514db089934071355e5743bf21d60\",\n \"0xd8da6bf26964af9d7eed9e03e53415d37aa96045\"\n ],\n \"chain\": \"ethereum\",\n \"timeRange\": {\"from\": \"30D_AGO\", \"to\": \"NOW\"},\n \"sourceInput\": \"Combined\",\n \"orderBy\": \"total_volume_usd\",\n \"orderByDirection\": \"DESC\",\n \"perPage\": 100\n}",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"walletAddresses",
"timeRange"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number, starting at 1"
},
"chain": {
"type": "string",
"default": "all",
"description": "Chain to read. Name one chain (for example ethereum or solana) to read that chain only. Leave this out to read every chain of the addresses' family at one time — with 'all', a counterparty met on more than one chain gets one row for each chain, so do not add the rows together. Supported chains: all, arbitrum, avalanche, base, bitcoin, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, robinhood, sei, solana, sonic, sui, ton, tron."
},
"filters": {
"anyOf": [
{
"type": "object",
"properties": {
"volumeInUsd": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value (inclusive), optional"
},
"from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value (inclusive), optional"
}
},
"description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Keep counterparties whose incoming USD volume is in this range"
},
"volumeOutUsd": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value (inclusive), optional"
},
"from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value (inclusive), optional"
}
},
"description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Keep counterparties whose outgoing USD volume is in this range"
},
"totalVolumeUsd": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value (inclusive), optional"
},
"from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value (inclusive), optional"
}
},
"description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Keep counterparties whose total USD volume is in this range"
},
"interactionCount": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value (inclusive), optional"
},
"from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value (inclusive), optional"
}
},
"description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Keep counterparties whose interaction count is in this range"
},
"excludeSmartMoneyLabels": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"Smart Trader",
"Smart HL Perps Trader",
"Fund",
"Public Figure",
"Exchange",
"Whale",
"First Mover LP",
"First Mover Staking",
"Profitable LP",
"Early MAGIC Miner",
"BananaGun Bot User",
"Top BananaGun Bot User",
"Maestro Bot User",
"Top Maestro Bot User"
],
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Drop counterparties that carry one of these labels"
},
"includeSmartMoneyLabels": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"Smart Trader",
"Smart HL Perps Trader",
"Fund",
"Public Figure",
"Exchange",
"Whale",
"First Mover LP",
"First Mover Staking",
"Profitable LP",
"Early MAGIC Miner",
"BananaGun Bot User",
"Top BananaGun Bot User",
"Maestro Bot User",
"Top Maestro Bot User"
],
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Keep only counterparties that carry one of these labels"
}
},
"description": "Row filters for batch counterparties. Each filter drops counterparty rows.",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Optional filters applied to each counterparty row"
},
"orderBy": {
"anyOf": [
{
"enum": [
"interaction_count",
"total_volume_usd",
"volume_in_usd",
"volume_out_usd"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort field applied inside each wallet's block. Pass an exact value above or None for default ('total_volume_usd')."
},
"perPage": {
"type": "integer",
"default": 100,
"maximum": 1000,
"minimum": 1,
"description": "Rows per page across all wallets in the batch, from 1 to 1000. The rows of one wallet stay together, so keep this high enough to cover every wallet you asked for."
},
"timeRange": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight."
},
"from": {
"type": "string",
"description": "Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
}
},
"description": "Date range for counterparties analysis. Max window: 90 days — a longer range is rejected, so split it into several calls. Prefer relative tokens (7D_AGO, 30D_AGO, 90D_AGO).",
"additionalProperties": false
},
"sourceInput": {
"enum": [
"Combined",
"Tokens",
"ETH"
],
"type": "string",
"default": "Combined",
"description": "Source input type for counterparties analysis"
},
"walletAddresses": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Wallet addresses to query, maximum 10 distinct addresses. Each wallet gets its own counterparty list — the results are NOT added together. Repeated addresses are removed. Every address must be on the same chain family: all EVM, or all Solana, or all Bitcoin. Do not mix families in one call."
},
"orderByDirection": {
"enum": [
"ASC",
"DESC",
"asc",
"desc"
],
"type": "string",
"default": "DESC",
"description": "Sort direction: ASC or DESC"
}
},
"description": "Complete request for batch address counterparties (flattened).\n\nWallet addresses only. Use AddressCounterpartiesRequest for one wallet or\nfor an entity name.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
Get list of 20 MOST RECENT transactions made by an address or an entity (per page).
Only the latest transactions according to the date range are returned.
Provide exactly one of `address`, `entity_id` or `trader_id`. An entity
lookup returns transactions across all wallets of that entity and covers at
most 7 days. A `trader_id` returns the transfers of all wallets of the
trader, at most 366 days.
A page shows at most 20 transactions. For every total, min, max, mean,
count or list of counterparties or tokens ("how much did it send or
receive", "total volume", "who did it send to", "which tokens"), use
`columns` with `aggregations`, also when the transactions fit on one
page. The tool then computes the result from the raw values of all
matching transactions. By default (`min_volume_usd` 1) the tool hides
dust, spam and transactions whose tokens have no price. Send
`"min_volume_usd": null` only when the user asks for transactions under
$1 or for unpriced tokens (airdrops, new tokens, NFTs).
Examples:
# Latest transactions
{"address": "0x1234567890123456789012345678901234567890", "chain": "all"}
# USD volume, and tokens sent and received, in 7 days
{
"address": "CDkCdBbvQfQudgBKunbbqiVYnERKANMfMJqxnVbScskB",
"chain": "solana",
"dateRange": {"from": "7D_AGO", "to": "NOW"},
"columns": ["volume_usd", "token_amount"],
"aggregations": ["sum"]
}
The description explains the capability, when to use it, and what to expect.
Inputs84/100
10 of 11 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › trader_id
Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. With trader_id, chain is all chains unless you set it, the window is at most 366 days. If the user asks for a longer period, tell the user the 366-day limit and the dates of the window you used. Columns and aggregations are not used.
Clear enough to supply this argument.
request › address
Single wallet address to analyze. REQUIRED if entity_id and trader_id are not provided. Cannot be used together with entity_id or trader_id.
Clear enough to supply this argument.
request › entity_id
Entity name to analyze (e.g., 'Vitalik Buterin'). Returns transactions across the entity's wallets. REQUIRED if address and trader_id are not provided. Cannot be used together with address or trader_id. Entity lookups cover at most 7 days per call. An entity's wallets span many chains: set chain to 'all' unless the user names a chain. Exchanges, chains, staking/validators and DeFi protocols are not supported; query one of their wallets with address instead.
Clear enough to supply this argument.
request › chain
Not provided
Missing description. Explain what this value means and how to supply it.
request › hideSpamToken
Remove suspicious tokens from transaction list
Explain the meaning of this value, not just its name.
request › dateRange › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Clear enough to supply this argument.
request › dateRange › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Clear enough to supply this argument.
request › min_volume_usd
Keep transactions with volume_usd >= this value (inclusive). Default 1: hides dust, spam and transactions whose tokens have no price (they have no volume). Leave it out for normal questions. Send null only when the user asks for transactions under $1 or for unpriced tokens (airdrops, new tokens, NFTs).
Clear enough to supply this argument.
request › columns
Columns to show or summarize, one row per token leg (a sent or received token of a transaction). Alone, `columns` gives a compact table of the 20 transactions of one page with only these columns. For a total, a count or a list of counterparties or tokens, also set `aggregations`.
Clear enough to supply this argument.
request › aggregations
Compute the `columns` over ALL matching transactions. Use it for every total, min, max, mean, count or list of counterparties or tokens (how much sent or received, total volume, who it sent to, which tokens), also when the transactions fit on one page: sum/min/max/mean/count for volume_usd (USD, once per transaction) and token_amount (per direction and token); unique for counterparty_address and token_address; count for any column (the number of transactions). Example: "columns": ["volume_usd", "token_amount"], "aggregations": ["sum"].
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number, starting at 1
Clear enough to supply this argument.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "address_transactions",
"title": "Fetching transaction history",
"description": "Get list of 20 MOST RECENT transactions made by an address or an entity (per page).\nOnly the latest transactions according to the date range are returned.\nProvide exactly one of `address`, `entity_id` or `trader_id`. An entity\nlookup returns transactions across all wallets of that entity and covers at\nmost 7 days. A `trader_id` returns the transfers of all wallets of the\ntrader, at most 366 days.\n\nA page shows at most 20 transactions. For every total, min, max, mean,\ncount or list of counterparties or tokens (\"how much did it send or\nreceive\", \"total volume\", \"who did it send to\", \"which tokens\"), use\n`columns` with `aggregations`, also when the transactions fit on one\npage. The tool then computes the result from the raw values of all\nmatching transactions. By default (`min_volume_usd` 1) the tool hides\ndust, spam and transactions whose tokens have no price. Send\n`\"min_volume_usd\": null` only when the user asks for transactions under\n$1 or for unpriced tokens (airdrops, new tokens, NFTs).\n\nExamples:\n # Latest transactions\n {\"address\": \"0x1234567890123456789012345678901234567890\", \"chain\": \"all\"}\n\n # USD volume, and tokens sent and received, in 7 days\n {\n \"address\": \"CDkCdBbvQfQudgBKunbbqiVYnERKANMfMJqxnVbScskB\",\n \"chain\": \"solana\",\n \"dateRange\": {\"from\": \"7D_AGO\", \"to\": \"NOW\"},\n \"columns\": [\"volume_usd\", \"token_amount\"],\n \"aggregations\": [\"sum\"]\n }",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number, starting at 1"
},
"chain": {
"type": "string",
"default": "evm"
},
"address": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single wallet address to analyze. REQUIRED if entity_id and trader_id are not provided. Cannot be used together with entity_id or trader_id."
},
"columns": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"time",
"tx_hash",
"chain",
"method",
"volume_usd",
"direction",
"token_symbol",
"token_address",
"token_amount",
"counterparty_address",
"counterparty_label"
],
"type": "string"
},
"minItems": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Columns to show or summarize, one row per token leg (a sent or received token of a transaction). Alone, `columns` gives a compact table of the 20 transactions of one page with only these columns. For a total, a count or a list of counterparties or tokens, also set `aggregations`."
},
"dateRange": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight."
},
"from": {
"type": "string",
"description": "Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
}
},
"description": "Date range for transactions (defaults to last 30 days for an address, last 7 days for an entity; entity ranges longer than 7 days are clamped)",
"additionalProperties": false
},
"entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Entity name to analyze (e.g., 'Vitalik Buterin'). Returns transactions across the entity's wallets. REQUIRED if address and trader_id are not provided. Cannot be used together with address or trader_id. Entity lookups cover at most 7 days per call. An entity's wallets span many chains: set chain to 'all' unless the user names a chain. Exchanges, chains, staking/validators and DeFi protocols are not supported; query one of their wallets with address instead."
},
"trader_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. With trader_id, chain is all chains unless you set it, the window is at most 366 days. If the user asks for a longer period, tell the user the 366-day limit and the dates of the window you used. Columns and aggregations are not used."
},
"aggregations": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"sum",
"min",
"max",
"mean",
"count",
"unique"
],
"type": "string"
},
"minItems": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Compute the `columns` over ALL matching transactions. Use it for every total, min, max, mean, count or list of counterparties or tokens (how much sent or received, total volume, who it sent to, which tokens), also when the transactions fit on one page: sum/min/max/mean/count for volume_usd (USD, once per transaction) and token_amount (per direction and token); unique for counterparty_address and token_address; count for any column (the number of transactions). Example: \"columns\": [\"volume_usd\", \"token_amount\"], \"aggregations\": [\"sum\"]."
},
"hideSpamToken": {
"type": "boolean",
"default": true,
"description": "Remove suspicious tokens from transaction list"
},
"min_volume_usd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": 1,
"description": "Keep transactions with volume_usd >= this value (inclusive). Default 1: hides dust, spam and transactions whose tokens have no price (they have no volume). Leave it out for normal questions. Send null only when the user asks for transactions under $1 or for unpriced tokens (airdrops, new tokens, NFTs)."
}
},
"description": "Complete request for address transactions (flattened).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Get a wallet's individual trades on a single chain — DEX swaps (spot) or
Hyperliquid perpetual trades, newest first. Wallet-centric companion to
`token_dex_trades` (which is token-centric). Use it when the question
names one wallet, for example "when did this wallet open, add to,
reduce or close its BTC long on Hyperliquid".
Chain: one per call ('all'/'evm' unsupported). EVM wallets MUST pass `chain`
explicitly (e.g. ethereum, base, arbitrum); non-EVM (e.g. Solana) is
auto-detected. Use 'hyperliquid' for Hyperliquid perpetual trades
(requires an EVM address). Call once per chain to span multiple networks.
A `trader_id` instead of `address` returns the spot swaps of all wallets of a
trader, or the Hyperliquid perp position segments with chain `hyperliquid`.
Spot columns: Time, Bought / Bought Amount, Sold / Sold Amount, Value USD, Tx Hash.
Perp columns: Time, Token, Side, Action, Size, Price, Value USD, Fee USD,
Closed PnL, Tx Hash.
Sort (`order_by`, asc/desc): timestamp, value. Filter by `valueUsd`,
`tokenAddressBought`, or `tokenAddressSold`. On spot chains the token
fields take contract addresses. On Hyperliquid they take perp symbols and
select Long or Short trades respectively; only one token field is allowed.
A page shows at most 25 trades. For every total, min, max, mean, count or
list of tokens ("how much did it buy or sell", "total volume", "total
PnL", "average trade size", "which tokens"), use `columns` with
`aggregations`, also when the trades fit on one page. The tool then
computes the result from the raw values of all matching trades. Token
amounts are summed per token.
Examples:
# Latest trades
{
"address": "0x1f2f10d1c40777ae1da742455c65828ff36df387",
"chain": "ethereum",
"dateRange": {"from": "7D_AGO", "to": "NOW"}
}
# How much of each token the wallet bought on one day, all pages
{
"address": "0x1f2f10d1c40777ae1da742455c65828ff36df387",
"chain": "ethereum",
"dateRange": {"from": "2026-10-02", "to": "2026-10-02"},
"columns": ["bought_amount"],
"aggregations": ["sum"]
}
# Total closed PnL and fees of Hyperliquid perp trades in 7 days
{
"address": "0x90dbb196cacf24bd212b377a0dd62eaad5e8151b",
"chain": "hyperliquid",
"dateRange": {"from": "7D_AGO", "to": "NOW"},
"columns": ["closed_pnl", "fee_usd"],
"aggregations": ["sum"]
}
The description explains the capability, when to use it, and what to expect.
Inputs82/100
13 of 14 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › trader_id
Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. With trader_id, chain is all chains unless you set it; 'hyperliquid' reads perp positions. valueUsd, token filters, columns, aggregations and orderBy are not used.
Clear enough to supply this argument.
request › address
The wallet address whose DEX trades to fetch. REQUIRED if trader_id is not provided. Cannot be used together with trader_id.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › chain
Single chain to query (e.g. ethereum, base, arbitrum, solana). This endpoint queries ONE chain at a time and does NOT accept 'all' or 'evm'. For EVM wallets a concrete chain is REQUIRED (they trade across many chains); non-EVM addresses are auto-detected from the address. Use 'hyperliquid' for Hyperliquid perpetual trades (requires an EVM address).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Clear enough to supply this argument.
request › dateRange › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Clear enough to supply this argument.
request › valueUsd › anyOf › 0 › from
Minimum value (inclusive), optional
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › valueUsd › anyOf › 0 › to
Maximum value (inclusive), optional
Clear enough to supply this argument.
request › tokenAddressBought
Token bought filter. On spot chains, use the token contract address. On Hyperliquid, use a perp symbol (e.g. BTC, HYPE, xyz:NVDA); returns Long-side trades only. For all trades of this coin, call again with tokenAddressSold (Short side).
Clear enough to supply this argument.
request › tokenAddressSold
Token sold filter. On spot chains, use the token contract address. On Hyperliquid, use a perp symbol (e.g. BTC, HYPE, xyz:NVDA); returns Short-side trades only. For all trades of this coin, call again with tokenAddressBought (Long side).
Clear enough to supply this argument.
request › columns
Columns to show or summarize. Spot: time, bought_symbol, bought_amount, sold_symbol, sold_amount, value_usd, tx_hash, bought_token, sold_token. Hyperliquid: time, token, side, action, size, price, value_usd, fee_usd, closed_pnl, tx_hash. Alone, `columns` gives one page of at most 25 trades with only these columns. For a total, an average, a count or a list of tokens, also set `aggregations`.
Clear enough to supply this argument.
request › aggregations
Compute the `columns` over ALL matching trades. Use it for every total, min, max, mean, count or list of tokens (how much bought or sold, total volume, total PnL, total fees, average trade size, which tokens), also when the trades fit on one page: sum/min/max/mean/count for bought_amount and sold_amount (per token), value_usd, and on Hyperliquid size (per coin), fee_usd and closed_pnl (0 on opening fills); unique for bought_token and sold_token; count for any column (the number of trades). Example: "columns": ["value_usd"], "aggregations": ["sum"].
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. Pass an exact value above or None for default ('timestamp').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › order_by_direction
Not provided
Missing description. Explain what this value means and how to supply it.
request › page
Page number, starting at 1
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "address_dex_trades",
"title": "Checking wallet DEX trades",
"description": "Get a wallet's individual trades on a single chain — DEX swaps (spot) or\nHyperliquid perpetual trades, newest first. Wallet-centric companion to\n`token_dex_trades` (which is token-centric). Use it when the question\nnames one wallet, for example \"when did this wallet open, add to,\nreduce or close its BTC long on Hyperliquid\".\n\nChain: one per call ('all'/'evm' unsupported). EVM wallets MUST pass `chain`\nexplicitly (e.g. ethereum, base, arbitrum); non-EVM (e.g. Solana) is\nauto-detected. Use 'hyperliquid' for Hyperliquid perpetual trades\n(requires an EVM address). Call once per chain to span multiple networks.\n\nA `trader_id` instead of `address` returns the spot swaps of all wallets of a\ntrader, or the Hyperliquid perp position segments with chain `hyperliquid`.\n\nSpot columns: Time, Bought / Bought Amount, Sold / Sold Amount, Value USD, Tx Hash.\nPerp columns: Time, Token, Side, Action, Size, Price, Value USD, Fee USD,\nClosed PnL, Tx Hash.\nSort (`order_by`, asc/desc): timestamp, value. Filter by `valueUsd`,\n`tokenAddressBought`, or `tokenAddressSold`. On spot chains the token\nfields take contract addresses. On Hyperliquid they take perp symbols and\nselect Long or Short trades respectively; only one token field is allowed.\n\nA page shows at most 25 trades. For every total, min, max, mean, count or\nlist of tokens (\"how much did it buy or sell\", \"total volume\", \"total\nPnL\", \"average trade size\", \"which tokens\"), use `columns` with\n`aggregations`, also when the trades fit on one page. The tool then\ncomputes the result from the raw values of all matching trades. Token\namounts are summed per token.\n\nExamples:\n # Latest trades\n {\n \"address\": \"0x1f2f10d1c40777ae1da742455c65828ff36df387\",\n \"chain\": \"ethereum\",\n \"dateRange\": {\"from\": \"7D_AGO\", \"to\": \"NOW\"}\n }\n\n # How much of each token the wallet bought on one day, all pages\n {\n \"address\": \"0x1f2f10d1c40777ae1da742455c65828ff36df387\",\n \"chain\": \"ethereum\",\n \"dateRange\": {\"from\": \"2026-10-02\", \"to\": \"2026-10-02\"},\n \"columns\": [\"bought_amount\"],\n \"aggregations\": [\"sum\"]\n }\n\n # Total closed PnL and fees of Hyperliquid perp trades in 7 days\n {\n \"address\": \"0x90dbb196cacf24bd212b377a0dd62eaad5e8151b\",\n \"chain\": \"hyperliquid\",\n \"dateRange\": {\"from\": \"7D_AGO\", \"to\": \"NOW\"},\n \"columns\": [\"closed_pnl\", \"fee_usd\"],\n \"aggregations\": [\"sum\"]\n }",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number, starting at 1"
},
"chain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single chain to query (e.g. ethereum, base, arbitrum, solana). This endpoint queries ONE chain at a time and does NOT accept 'all' or 'evm'. For EVM wallets a concrete chain is REQUIRED (they trade across many chains); non-EVM addresses are auto-detected from the address. Use 'hyperliquid' for Hyperliquid perpetual trades (requires an EVM address)."
},
"address": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The wallet address whose DEX trades to fetch. REQUIRED if trader_id is not provided. Cannot be used together with trader_id."
},
"columns": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"time",
"bought_symbol",
"bought_amount",
"sold_symbol",
"sold_amount",
"value_usd",
"tx_hash",
"bought_token",
"sold_token",
"token",
"side",
"action",
"size",
"price",
"fee_usd",
"closed_pnl"
],
"type": "string"
},
"minItems": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Columns to show or summarize. Spot: time, bought_symbol, bought_amount, sold_symbol, sold_amount, value_usd, tx_hash, bought_token, sold_token. Hyperliquid: time, token, side, action, size, price, value_usd, fee_usd, closed_pnl, tx_hash. Alone, `columns` gives one page of at most 25 trades with only these columns. For a total, an average, a count or a list of tokens, also set `aggregations`."
},
"orderBy": {
"anyOf": [
{
"enum": [
"timestamp",
"value"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort field. Pass an exact value above or None for default ('timestamp')."
},
"valueUsd": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value (inclusive), optional"
},
"from": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value (inclusive), optional"
}
},
"description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Filter trades by USD value (open-ended min/max allowed)"
},
"dateRange": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight."
},
"from": {
"type": "string",
"description": "Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
}
},
"description": "Date range for the trades (defaults to last 7 days). Use ALL_TIME for full history (start 2009-01-03).",
"additionalProperties": false
},
"trader_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. With trader_id, chain is all chains unless you set it; 'hyperliquid' reads perp positions. valueUsd, token filters, columns, aggregations and orderBy are not used."
},
"aggregations": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"sum",
"min",
"max",
"mean",
"count",
"unique"
],
"type": "string"
},
"minItems": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Compute the `columns` over ALL matching trades. Use it for every total, min, max, mean, count or list of tokens (how much bought or sold, total volume, total PnL, total fees, average trade size, which tokens), also when the trades fit on one page: sum/min/max/mean/count for bought_amount and sold_amount (per token), value_usd, and on Hyperliquid size (per coin), fee_usd and closed_pnl (0 on opening fills); unique for bought_token and sold_token; count for any column (the number of trades). Example: \"columns\": [\"value_usd\"], \"aggregations\": [\"sum\"]."
},
"tokenAddressSold": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Token sold filter. On spot chains, use the token contract address. On Hyperliquid, use a perp symbol (e.g. BTC, HYPE, xyz:NVDA); returns Short-side trades only. For all trades of this coin, call again with tokenAddressBought (Long side)."
},
"order_by_direction": {
"enum": [
"ASC",
"DESC",
"asc",
"desc"
],
"type": "string",
"default": "DESC"
},
"tokenAddressBought": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Token bought filter. On spot chains, use the token contract address. On Hyperliquid, use a perp symbol (e.g. BTC, HYPE, xyz:NVDA); returns Long-side trades only. For all trades of this coin, call again with tokenAddressSold (Short side)."
}
},
"description": "Complete request for an address' DEX trades (flattened).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
Expand internal abbreviations and remove technical prefixes from the display title.
Description75/100
Get PnL stats for a specific token traded by the input address during a specific date range.
Use this tool for analysing the performance of the wallet for the specific token over a time period.
Provide exactly one of `walletAddress` or `trader_id`. For a trader, send
`trader_id`: the result adds up all wallets of the trader and lists the
newest buys and sells of the token.
Chain: pass 'hyperliquid' for a perp coin — there `tokenAddress` is the perp
SYMBOL (e.g. 'BTC', 'HYPE', 'xyz:CL'), not a contract address. Every other
chain expects a token contract address.
Describe the returned information so the agent knows whether it will answer the request.
Inputs74/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › trader_id
Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. The result adds up all wallets of the trader on the chain over their full history, with realized and unrealized PnL together (showRealized is not used), and lists the 20 newest buys and sells in dateRange. Set chain to the chain of the token (an EVM token can be on several chains). On chain='hyperliquid' it shows one row for each wallet and a sum.
Clear enough to supply this argument.
request › walletAddress
The wallet address to analyze. REQUIRED if trader_id is not provided. Cannot be used together with trader_id.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › tokenAddress
Token address to generate PnL stats for
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
request › dateRange › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Clear enough to supply this argument.
request › dateRange › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Clear enough to supply this argument.
request › showRealized
Set to true for realized PnL (completed/closed trades), false for current position analysis (unrealized PnL + active holdings). Ignored on chain='hyperliquid', which always reports both.
Clear enough to supply this argument.
request › chain
Blockchain to query. Use 'hyperliquid' for a Hyperliquid perp coin — then tokenAddress is the perp SYMBOL (e.g. 'BTC', 'HYPE', 'xyz:CL'), not a contract address, and the wallet must be an EVM address. Every other chain expects a token contract address.
Clear enough to supply this argument.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "wallet_pnl_for_token",
"title": "Calculating token performance",
"description": "Get PnL stats for a specific token traded by the input address during a specific date range.\nUse this tool for analysing the performance of the wallet for the specific token over a time period.\nProvide exactly one of `walletAddress` or `trader_id`. For a trader, send\n`trader_id`: the result adds up all wallets of the trader and lists the\nnewest buys and sells of the token.\n\nChain: pass 'hyperliquid' for a perp coin — there `tokenAddress` is the perp\nSYMBOL (e.g. 'BTC', 'HYPE', 'xyz:CL'), not a contract address. Every other\nchain expects a token contract address.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"tokenAddress",
"dateRange",
"showRealized"
],
"properties": {
"chain": {
"type": "string",
"default": "evm",
"description": "Blockchain to query. Use 'hyperliquid' for a Hyperliquid perp coin — then tokenAddress is the perp SYMBOL (e.g. 'BTC', 'HYPE', 'xyz:CL'), not a contract address, and the wallet must be an EVM address. Every other chain expects a token contract address."
},
"dateRange": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight."
},
"from": {
"type": "string",
"description": "Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
}
},
"description": "Date range for PnL analysis",
"additionalProperties": false
},
"trader_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. The result adds up all wallets of the trader on the chain over their full history, with realized and unrealized PnL together (showRealized is not used), and lists the 20 newest buys and sells in dateRange. Set chain to the chain of the token (an EVM token can be on several chains). On chain='hyperliquid' it shows one row for each wallet and a sum."
},
"showRealized": {
"type": "boolean",
"description": "Set to true for realized PnL (completed/closed trades), false for current position analysis (unrealized PnL + active holdings). Ignored on chain='hyperliquid', which always reports both."
},
"tokenAddress": {
"type": "string",
"description": "Token address to generate PnL stats for"
},
"walletAddress": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The wallet address to analyze. REQUIRED if trader_id is not provided. Cannot be used together with trader_id."
}
},
"description": "Complete request for wallet PnL for token (flattened).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
Name the specific action and subject instead of using a generic label such as ‘manage’ or ‘tool’.
Description87/100
Get aggregate stats of overall realized PnL for the input address.
For Hyperliquid perp traders (chain='hyperliquid'), includes realized PnL
from fills plus a current unrealized snapshot of open positions.
For chain='all'/'evm' on an EVM address, reports spot/on-chain and
Hyperliquid perp results as separate sections (never summed).
For a single named chain, this tool covers realized PnL only.
Use this tool for analysing the performance of the wallet over a time period.
For a trader, send trader_id instead of walletAddress: the spot PnL of all
wallets of the trader and a separate Hyperliquid perp section.
# Query by trader
{"trader_id": "5482f9aeb02f67b7", "dateRange": {"from": "30D_AGO", "to": "NOW"}}
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › trader_id
Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. With trader_id, chain is not used (the PnL covers all wallets of the trader), and the Hyperliquid perp PnL has the fixed windows 7D and 30D, not dateRange.
Clear enough to supply this argument.
request › walletAddress
The wallet address to analyze. REQUIRED if trader_id is not provided. Cannot be used together with trader_id.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Clear enough to supply this argument.
request › dateRange › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Clear enough to supply this argument.
request › chain
Blockchain to query. Use 'hyperliquid' for Hyperliquid perp traders only (realized PnL from fills + current unrealized snapshot). 'evm'/'all' on an EVM address reports spot/on-chain and Hyperliquid perp results in separate sections. Or pass a specific chain name for that chain's spot PnL alone.
Clear enough to supply this argument.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "wallet_pnl_summary",
"title": "Analyzing wallet performance",
"description": "Get aggregate stats of overall realized PnL for the input address.\nFor Hyperliquid perp traders (chain='hyperliquid'), includes realized PnL\nfrom fills plus a current unrealized snapshot of open positions.\nFor chain='all'/'evm' on an EVM address, reports spot/on-chain and\nHyperliquid perp results as separate sections (never summed).\nFor a single named chain, this tool covers realized PnL only.\nUse this tool for analysing the performance of the wallet over a time period.\n\nFor a trader, send trader_id instead of walletAddress: the spot PnL of all\nwallets of the trader and a separate Hyperliquid perp section.\n\n# Query by trader\n{\"trader_id\": \"5482f9aeb02f67b7\", \"dateRange\": {\"from\": \"30D_AGO\", \"to\": \"NOW\"}}",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"dateRange"
],
"properties": {
"chain": {
"type": "string",
"default": "evm",
"description": "Blockchain to query. Use 'hyperliquid' for Hyperliquid perp traders only (realized PnL from fills + current unrealized snapshot). 'evm'/'all' on an EVM address reports spot/on-chain and Hyperliquid perp results in separate sections. Or pass a specific chain name for that chain's spot PnL alone."
},
"dateRange": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight."
},
"from": {
"type": "string",
"description": "Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
}
},
"description": "Date range for PnL summary analysis",
"additionalProperties": false
},
"trader_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. With trader_id, chain is not used (the PnL covers all wallets of the trader), and the Hyperliquid perp PnL has the fixed windows 7D and 30D, not dateRange."
},
"walletAddress": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The wallet address to analyze. REQUIRED if trader_id is not provided. Cannot be used together with trader_id."
}
},
"description": "Complete request for wallet PnL summary (flattened).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Get the first address that ever funded an EVM wallet, with the funding transaction hash, chain and timestamp.
Use this to attribute an unlabelled wallet to a known entity — the first funder is often a CEX withdrawal or a wallet the same owner already controls. The funder is resolved across all chains, so no chain argument is needed.
The description explains the capability, when to use it, and what to expect.
Inputs86/100
Input documentation gives an agent enough context to populate the arguments.
request › address
EVM address to look up the first funder for
Clear enough to supply this argument.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "address_first_funder",
"title": "Finding the first funder",
"description": "Get the first address that ever funded an EVM wallet, with the funding transaction hash, chain and timestamp.\nUse this to attribute an unlabelled wallet to a known entity — the first funder is often a CEX withdrawal or a wallet the same owner already controls. The funder is resolved across all chains, so no chain argument is needed.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"address"
],
"properties": {
"address": {
"type": "string",
"description": "EVM address to look up the first funder for"
}
},
"description": "Request for the first address that funded a wallet (flattened).",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description89/100
Get comprehensive portfolio overview for a wallet address or entity.
Hyperliquid perpetual positions include liquidation prices to support risk analysis workflows.
For wallet addresses, supports different modes:
- 'fast-mode-default': Wallet balances + Hyperliquid positions (skip defi, for fast mode only)
- 'all': Wallet balances + DeFi positions + Hyperliquid positions
- 'wallet_balances': Only token balances (tokens and native coins across all chains)
- 'defi': Only DeFi positions (lending, staking, LP tokens, etc., excluding Hyperliquid)
- 'hyperliquid': Only Hyperliquid data — perp positions (with liquidation prices and margin summary) plus HL spot wallet balances
For entities (e.g., "Binance", "Paradigm Fund"), only on-chain token balances
are returned, aggregated across all addresses associated with the entity.
For a trader, send trader_id: the token balances and open Hyperliquid
perp positions of all wallets of the trader.
This tool provides flexible portfolio analysis in a single request,
allowing users to focus on specific aspects of their holdings.
The output is pre-formatted markdown that should be presented exactly as returned,
preserving all tables, sections, and formatting without reinterpretation.
Example Usage:
Get full comprehensive portfolio for a wallet:
```
{
"walletAddress": "0x28c6c06298d514db089934071355e5743bf21d60",
"mode": "all"
}
```
Get only DeFi positions:
```
{
"walletAddress": "0x28c6c06298d514db089934071355e5743bf21d60",
"mode": "defi"
}
```
Get only Hyperliquid positions:
```
{
"walletAddress": "0x28c6c06298d514db089934071355e5743bf21d60",
"mode": "hyperliquid"
}
```
Get token balances for an entity:
```
{
"entity_id": "Binance"
}
```
Get the portfolio of a trader:
```
{
"trader_id": "5482f9aeb02f67b7"
}
```
The description explains the capability, when to use it, and what to expect.
Inputs60/100
4 of 5 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
request › trader_id
Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. With trader_id, there are no DeFi positions (mode defi is an error, all is fast-mode-default), the perp table has one row per wallet and coin, and there is no Hyperliquid account summary or Hyperliquid spot balance.
Clear enough to supply this argument.
request › walletAddress
Wallet address to analyze comprehensive portfolio for. REQUIRED if entity_id and trader_id are not provided. Cannot be used together with entity_id or trader_id.
Clear enough to supply this argument.
request › entity_id
Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). For entities, only token balances are returned. REQUIRED if wallet_address and trader_id are not provided. Cannot be used together with wallet_address or trader_id.
Resolve the mismatch between this description and its schema constraints.
request › chain
Not provided
Missing description. Explain what this value means and how to supply it.
{
"name": "address_portfolio",
"title": "Loading portfolio data",
"description": "Get comprehensive portfolio overview for a wallet address or entity.\n\nHyperliquid perpetual positions include liquidation prices to support risk analysis workflows.\n\nFor wallet addresses, supports different modes:\n- 'fast-mode-default': Wallet balances + Hyperliquid positions (skip defi, for fast mode only)\n- 'all': Wallet balances + DeFi positions + Hyperliquid positions\n- 'wallet_balances': Only token balances (tokens and native coins across all chains)\n- 'defi': Only DeFi positions (lending, staking, LP tokens, etc., excluding Hyperliquid)\n- 'hyperliquid': Only Hyperliquid data — perp positions (with liquidation prices and margin summary) plus HL spot wallet balances\n\nFor entities (e.g., \"Binance\", \"Paradigm Fund\"), only on-chain token balances\nare returned, aggregated across all addresses associated with the entity.\n\nFor a trader, send trader_id: the token balances and open Hyperliquid\nperp positions of all wallets of the trader.\n\nThis tool provides flexible portfolio analysis in a single request,\nallowing users to focus on specific aspects of their holdings.\n\nThe output is pre-formatted markdown that should be presented exactly as returned,\npreserving all tables, sections, and formatting without reinterpretation.\n\nExample Usage:\n Get full comprehensive portfolio for a wallet:\n ```\n {\n \"walletAddress\": \"0x28c6c06298d514db089934071355e5743bf21d60\",\n \"mode\": \"all\"\n }\n ```\n\n Get only DeFi positions:\n ```\n {\n \"walletAddress\": \"0x28c6c06298d514db089934071355e5743bf21d60\",\n \"mode\": \"defi\"\n }\n ```\n\n Get only Hyperliquid positions:\n ```\n {\n \"walletAddress\": \"0x28c6c06298d514db089934071355e5743bf21d60\",\n \"mode\": \"hyperliquid\"\n }\n ```\n\n Get token balances for an entity:\n ```\n {\n \"entity_id\": \"Binance\"\n }\n ```\n\n Get the portfolio of a trader:\n ```\n {\n \"trader_id\": \"5482f9aeb02f67b7\"\n }\n ```",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"default": "fast-mode-default",
"description": "Portfolio mode: 'fast-mode-default' (default - wallet_balances + hyperliquid), 'all' (wallet_balances + defi + hyperliquid), 'wallet_balances' (only token balances), 'defi' (only DeFi positions), 'hyperliquid' (only Hyperliquid positions)"
},
"chain": {
"type": "string",
"default": "all"
},
"entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). For entities, only token balances are returned. REQUIRED if wallet_address and trader_id are not provided. Cannot be used together with wallet_address or trader_id."
},
"trader_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Trader ID from the Traders results of general_search. Covers all wallets of the trader. Use it instead of address or entity_id. With trader_id, there are no DeFi positions (mode defi is an error, all is fast-mode-default), the perp table has one row per wallet and coin, and there is no Hyperliquid account summary or Hyperliquid spot balance."
},
"walletAddress": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Wallet address to analyze comprehensive portfolio for. REQUIRED if entity_id and trader_id are not provided. Cannot be used together with entity_id or trader_id."
}
},
"description": "Complete request for Address Portfolio endpoint (flattened).\n\nIMPORTANT: Exactly one of 'wallet_address', 'entity_id' or 'trader_id' must be provided.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description79/100
General search tool. This is your FIRST entry point to look up for possible tokens, entities, and addresses related to a query.
Do NOT use this tool for prediction markets. For Polymarket names, topics,
event slugs, or URLs, use `prediction_market_lookup` instead.
Nansen MCP does not support NFTs, however check using this tool if the query relates to a token. Regular tokens and NFTs can have the same name.
This tool allows you to:
- Check if a (fungible) token exists by name, symbol, or contract address
- Search information about a token
- Trading volume
- Contract address and chain information
- Market cap and supply data when available
- Search information about an entity
- Find the address behind a Nansen label (public figure, fund, exchange wallet)
- Resolve a domain (.eth, .sol) to its address
- Look up premium address labels only on the Nansen research agent
The description explains the capability, when to use it, and what to expect.
Inputs81/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
The search term - token symbol, name, or address. In stock mode,
pass only the company name or exchange ticker. Do not add words
such as "stock", "ticker", or a chain name.
Clear enough to supply this argument.
result_type
Type filter - "token", "entity", "wallet", "eoa", "stock", or "any" ("all" is the same as "any")
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
max_results
Maximum number of results (default: 25, max: 25)
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
chain
Optional chain filter to narrow down token results to specific blockchain. If not further specified, leave it as None. If a chain is specified, ALWAYS use this parameter instead of adding chain name to the query string.
Valid values: "ethereum", "solana", "base", "bnb", "polygon", "arbitrum",
"avalanche", "optimism", etc.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "general_search",
"title": "Searching tokens, companies, and addresses",
"description": "General search tool. This is your FIRST entry point to look up for possible tokens, entities, and addresses related to a query.\n\nDo NOT use this tool for prediction markets. For Polymarket names, topics,\nevent slugs, or URLs, use `prediction_market_lookup` instead.\n\nNansen MCP does not support NFTs, however check using this tool if the query relates to a token. Regular tokens and NFTs can have the same name.\n\nThis tool allows you to:\n- Check if a (fungible) token exists by name, symbol, or contract address\n- Search information about a token\n - Trading volume\n - Contract address and chain information\n - Market cap and supply data when available\n- Search information about an entity\n- Find the address behind a Nansen label (public figure, fund, exchange wallet)\n- Resolve a domain (.eth, .sol) to its address\n- Look up premium address labels only on the Nansen research agent",
"inputSchema": {
"type": "object",
"required": [
"query"
],
"properties": {
"chain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional chain filter to narrow down token results to specific blockchain. If not further specified, leave it as None. If a chain is specified, ALWAYS use this parameter instead of adding chain name to the query string.\n Valid values: \"ethereum\", \"solana\", \"base\", \"bnb\", \"polygon\", \"arbitrum\",\n \"avalanche\", \"optimism\", etc."
},
"query": {
"type": "string",
"description": "The search term - token symbol, name, or address. In stock mode,\n pass only the company name or exchange ticker. Do not add words\n such as \"stock\", \"ticker\", or a chain name."
},
"max_results": {
"type": "integer",
"default": 25,
"description": "Maximum number of results (default: 25, max: 25)"
},
"result_type": {
"enum": [
"token",
"entity",
"wallet",
"eoa",
"stock",
"any",
"all"
],
"type": "string",
"default": "any",
"description": "Type filter - \"token\", \"entity\", \"wallet\", \"eoa\", \"stock\", or \"any\" (\"all\" is the same as \"any\")"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Search Nansen's entity names by a partial name and get back the exact entity names that match.
Use this when a tool needs an exact entity name and the user gave an approximate one (e.g. "binance" -> "Binance 14"). Matching is case-insensitive and matches anywhere in the name. For tokens or addresses use `general_search` instead.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search_query
Partial entity name, at least 2 characters
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
max_results
Maximum number of entity names to return (default 25)
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "entity_name_search",
"title": "Searching entity names",
"description": "Search Nansen's entity names by a partial name and get back the exact entity names that match.\nUse this when a tool needs an exact entity name and the user gave an approximate one (e.g. \"binance\" -> \"Binance 14\"). Matching is case-insensitive and matches anywhere in the name. For tokens or addresses use `general_search` instead.",
"inputSchema": {
"type": "object",
"required": [
"search_query"
],
"properties": {
"max_results": {
"type": "integer",
"default": 25,
"description": "Maximum number of entity names to return (default 25)"
},
"search_query": {
"type": "string",
"description": "Partial entity name, at least 2 characters"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description64/100
Get transaction details and token transfers for a transaction hash.
No contract function is shown. For it, use the Method column of
`address_transactions` for the From address.
Describe the returned information so the agent knows whether it will answer the request.
Inputs0/100
0 of 2 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
transaction_hash
Not provided
Missing description. Explain what this value means and how to supply it.
chain
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Search Polymarket for events and markets by name, topic, URL, or slug.
**PM building blocks:**
- An **event** is a grouped prediction topic containing many child markets.
- A **market** is one tradable outcome with its own `marketId`.
- Example: `2026 NCAA Tournament Winner` is an event; `Will Duke win the
2026 NCAA Tournament?` is a market. Detail tools require `marketId`,
not `eventId`.
**When to use:**
- First tool when the user asks about a specific PM topic, event, slug, or
Polymarket URL but does not provide `marketId`.
- Optionally provide `queryVariant` as a cleaner short keyword version.
- Set `includeEventMarkets` to true to also return child markets for the
best-matching event.
- Do NOT use `general_search` for prediction markets.
- Results include current outcome prices, last trade price, and bid/ask
inline — for a quick probability check you may not need
`prediction_market_ohlcv`. For price *history* or dated moves, still
use `prediction_market_ohlcv`.
**Query tips:**
- Uses Polymarket's search API — natural language queries work well.
- Prefer short 1–3 keyword queries for best results.
- Avoid broad multi-topic queries like `bitcoin ethereum politics`.
**Output rules:**
- If lookup returns no suitable market or a mismatched timeframe, say so
explicitly — do not silently substitute a nearby market.
The description explains the capability, when to use it, and what to expect.
Inputs89/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number for paginated results.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › query
Prediction market name, topic, Polymarket URL, or URL slug to resolve to candidate market IDs.
Clear enough to supply this argument.
request › queryVariant
Optional second short query variant to search alongside query, such as a cleaner keyword version of a slug.
Clear enough to supply this argument.
request › status
Optional lifecycle filter for markets/events. Defaults to 'active'. Use 'all' to include closed markets.
Clear enough to supply this argument.
request › maxCandidates
Maximum number of market and event candidates to return.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › includeEventMarkets
When true, also include child markets for the best-matching event. Useful for event-level questions where market detail tools need the full market slate.
Clear enough to supply this argument.
request › maxEventMarkets
Maximum number of child markets to show when includeEventMarkets is true. The output always states how many of the event's total markets are shown.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "prediction_market_lookup",
"title": "Looking up prediction market",
"description": "Search Polymarket for events and markets by name, topic, URL, or slug.\n\n**PM building blocks:**\n- An **event** is a grouped prediction topic containing many child markets.\n- A **market** is one tradable outcome with its own `marketId`.\n- Example: `2026 NCAA Tournament Winner` is an event; `Will Duke win the\n 2026 NCAA Tournament?` is a market. Detail tools require `marketId`,\n not `eventId`.\n\n**When to use:**\n- First tool when the user asks about a specific PM topic, event, slug, or\n Polymarket URL but does not provide `marketId`.\n- Optionally provide `queryVariant` as a cleaner short keyword version.\n- Set `includeEventMarkets` to true to also return child markets for the\n best-matching event.\n- Do NOT use `general_search` for prediction markets.\n- Results include current outcome prices, last trade price, and bid/ask\n inline — for a quick probability check you may not need\n `prediction_market_ohlcv`. For price *history* or dated moves, still\n use `prediction_market_ohlcv`.\n\n**Query tips:**\n- Uses Polymarket's search API — natural language queries work well.\n- Prefer short 1–3 keyword queries for best results.\n- Avoid broad multi-topic queries like `bitcoin ethereum politics`.\n\n**Output rules:**\n- If lookup returns no suitable market or a mismatched timeframe, say so\n explicitly — do not silently substitute a nearby market.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"query"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for paginated results."
},
"query": {
"type": "string",
"minLength": 1,
"description": "Prediction market name, topic, Polymarket URL, or URL slug to resolve to candidate market IDs."
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "active",
"description": "Optional lifecycle filter for markets/events. Defaults to 'active'. Use 'all' to include closed markets."
},
"queryVariant": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional second short query variant to search alongside query, such as a cleaner keyword version of a slug."
},
"maxCandidates": {
"type": "integer",
"default": 5,
"maximum": 10,
"minimum": 1,
"description": "Maximum number of market and event candidates to return."
},
"maxEventMarkets": {
"type": "integer",
"default": 12,
"maximum": 50,
"minimum": 1,
"description": "Maximum number of child markets to show when includeEventMarkets is true. The output always states how many of the event's total markets are shown."
},
"includeEventMarkets": {
"type": "boolean",
"default": true,
"description": "When true, also include child markets for the best-matching event. Useful for event-level questions where market detail tools need the full market slate."
}
},
"description": "Request for resolving prediction market names, events, slugs, or URLs.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
Browse and sort Polymarket markets, events, or categories.
**When to use:**
- Broad discovery, screening, and ranked browsing across many markets.
- Do NOT use this to resolve one named market/event/slug/URL — use
`prediction_market_lookup` instead.
**Query tips:**
- Literal-style matching on text and slugs, not fuzzy web search.
- Prefer one short topic or slug fragment (e.g. `fed cuts`, `zelensky`,
`ncaa tournament`).
- Do not bundle unrelated topics (e.g. `bitcoin ethereum politics
weather`). If a broad question spans several topics, run separate
screener queries for each.
- If a query returns no rows, do not invent a nearest match — try a
narrower topic or say no data was returned.
**Output rules:**
- Superlatives (highest, leading, biggest, top, trending) must match the
shown metric exactly.
- Do not infer end dates, rankings, or category leadership from titles
alone.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number for paginated results.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › mode
Discovery mode. Use 'markets' to screen individual markets, 'events' to screen grouped events, and 'categories' for category level aggregated stats.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. Pass an exact value above or None for default ('volume_24hr').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › query
Optional text query for filtering markets/events by keyword.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › status
Optional lifecycle filter for markets/events. Common values: 'active', 'open', 'closed', or 'all'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Historical odds/volume candles for a Polymarket market.
**When to use:**
- Current odds / implied probability, price history, and recent
probability changes on a specific market.
**Key fields:**
- `Close` is the share price for the displayed outcome side.
- In binary markets, Yes and No shares are complementary and sum to
about $1.
**Pitfalls:**
- Each response is for one exact `marketId` — do not mix dates or prices
across different markets.
- If no candles are returned for the requested window, say so directly —
do not estimate.
**Prerequisites:** If `marketId` is unknown, call
`prediction_market_lookup` first.
The description explains the capability, when to use it, and what to expect.
Inputs79/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number for paginated results.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › marketId
Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › anyOf › 0 › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › anyOf › 0 › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Clear enough to supply this argument.
request › orderBy
Sort field. Pass an exact value above or None for default ('period_start').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderByDirection
Sort direction: 'ASC' or 'DESC' (case-insensitive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "prediction_market_ohlcv",
"title": "Loading prediction market prices",
"description": "Historical odds/volume candles for a Polymarket market.\n\n**When to use:**\n- Current odds / implied probability, price history, and recent\n probability changes on a specific market.\n\n**Key fields:**\n- `Close` is the share price for the displayed outcome side.\n- In binary markets, Yes and No shares are complementary and sum to\n about $1.\n\n**Pitfalls:**\n- Each response is for one exact `marketId` — do not mix dates or prices\n across different markets.\n- If no candles are returned for the requested window, say so directly —\n do not estimate.\n\n**Prerequisites:** If `marketId` is unknown, call\n`prediction_market_lookup` first.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"marketId"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for paginated results."
},
"orderBy": {
"anyOf": [
{
"enum": [
"period_start",
"volume_usd",
"trade_count"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort field. Pass an exact value above or None for default ('period_start')."
},
"marketId": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool."
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight."
},
"from": {
"type": "string",
"description": "Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
}
},
"description": "Date range via tokens or dates.\nTokens: NOW, ALL_TIME, XMIN_AGO, XD_AGO, XH_AGO, XY_AGO; THIS_YEAR_START, THIS_QUARTER_START, THIS_MONTH_START, THIS_WEEK_START, TODAY_START; LAST_WEEK_START/END, LAST_MONTH_START/END, LAST_QUARTER_START/END, LAST_YEAR_START/END.\nDurations are exact rolling UTC timestamps at both ends: 1D_AGO equals 24H_AGO; 1Y_AGO equals 365 days. Bare duration aliases and case variants are supported.\nExplicit dates and calendar tokens keep calendar boundaries and inclusive final dates. TODAY_START is current-day midnight. Date-only endpoints keep their calendar contracts.\nALL_TIME is full history. It resolves to 2009-01-03. Use ALL_TIME instead of a very large day count.\nWeek starts Monday. Quarters are calendar. Dates: YYYY-MM-DD or ___-MM-DD (year omitted).\nPlease check detailed system instructions for more information.",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Optional date range for OHLCV. Defaults to the last 30 days when omitted."
},
"orderByDirection": {
"enum": [
"ASC",
"DESC",
"asc",
"desc"
],
"type": "string",
"default": "DESC",
"description": "Sort direction: 'ASC' or 'DESC' (case-insensitive)."
}
},
"description": "Request for historical prediction market OHLCV.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description86/100
Live orderbook for a Polymarket market.
**When to use:**
- Bid/ask depth, liquidity, and yes-share / no-share order structure.
**Key fields:**
- `Order Size` is share quantity, not USD. Do not describe share size as
dollar depth unless you calculate `shares × price`.
**Yes/No price relationship:**
- Yes and No are complementary (Yes + No ≈ $1). A No bid at price $X
means willingness to buy No when Yes is near $(1−X).
- A cluster of No bids at low prices (e.g. $0.20) is resistance for Yes
rallying to ~$0.80, NOT a support floor for the current Yes price.
- When comparing OHLCV odds against orderbook depth, convert No-side
prices to Yes-equivalent (1 − No price) before drawing divergence
conclusions.
**Pitfalls:**
- Do not treat raw no-share prices as bearish yes-share odds — prefer
`prediction_market_ohlcv` for current odds / implied probability.
**Prerequisites:** If `marketId` is unknown, call
`prediction_market_lookup` first.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number for paginated results.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › marketId
Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "prediction_market_orderbook",
"title": "Checking prediction market orderbook",
"description": "Live orderbook for a Polymarket market.\n\n**When to use:**\n- Bid/ask depth, liquidity, and yes-share / no-share order structure.\n\n**Key fields:**\n- `Order Size` is share quantity, not USD. Do not describe share size as\n dollar depth unless you calculate `shares × price`.\n\n**Yes/No price relationship:**\n- Yes and No are complementary (Yes + No ≈ $1). A No bid at price $X\n means willingness to buy No when Yes is near $(1−X).\n- A cluster of No bids at low prices (e.g. $0.20) is resistance for Yes\n rallying to ~$0.80, NOT a support floor for the current Yes price.\n- When comparing OHLCV odds against orderbook depth, convert No-side\n prices to Yes-equivalent (1 − No price) before drawing divergence\n conclusions.\n\n**Pitfalls:**\n- Do not treat raw no-share prices as bearish yes-share odds — prefer\n `prediction_market_ohlcv` for current odds / implied probability.\n\n**Prerequisites:** If `marketId` is unknown, call\n`prediction_market_lookup` first.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"marketId"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for paginated results."
},
"marketId": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool."
}
},
"description": "Request for a live prediction market orderbook.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Largest current holders for a Polymarket market.
**Key fields:**
- Positions are share balances, not USD notional.
- `Position Value USD` is current marked value, not payout at resolution.
- `Side Held` is the share side currently held.
**Pitfalls:**
- The visible holder table is the source of truth for holder-side
concentration — do not infer risk, max loss, or potential profit unless
the tool output explicitly provides it.
- Output summary is based only on shown rows, not the entire holder table.
- Large visible positions or labels do not by themselves identify smart
money unless Nansen smart-money-labelled data supports it.
**Prerequisites:** If `marketId` is unknown, call
`prediction_market_lookup` first.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number for paginated results.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › marketId
Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderBy
Sort field. Pass an exact value above or None for default ('position_size').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › orderByDirection
Sort direction: 'ASC' or 'DESC' (case-insensitive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
Recent trades for a Polymarket market.
**When to use:**
- Source of truth for recent fills and latest trade-tape pricing.
- Do not overwrite recent trade prices with older OHLCV candles.
**Key fields:**
- `Share Size` is quantity; `Value USD` is dollar value.
- Each row is one visible trade leg — `Value USD` applies to that row,
not the whole transaction hash.
**Pitfalls:**
- Large visible trades do not by themselves identify smart money or
institutions.
**Prerequisites:** If `marketId` is unknown, call
`prediction_market_lookup` first.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number for paginated results.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › marketId
Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › anyOf › 0 › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › anyOf › 0 › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "prediction_market_trades",
"title": "Checking prediction market trades",
"description": "Recent trades for a Polymarket market.\n\n**When to use:**\n- Source of truth for recent fills and latest trade-tape pricing.\n- Do not overwrite recent trade prices with older OHLCV candles.\n\n**Key fields:**\n- `Share Size` is quantity; `Value USD` is dollar value.\n- Each row is one visible trade leg — `Value USD` applies to that row,\n not the whole transaction hash.\n\n**Pitfalls:**\n- Large visible trades do not by themselves identify smart money or\n institutions.\n\n**Prerequisites:** If `marketId` is unknown, call\n`prediction_market_lookup` first.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"marketId"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for paginated results."
},
"marketId": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool."
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight."
},
"from": {
"type": "string",
"description": "Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
}
},
"description": "Date range via tokens or dates.\nTokens: NOW, ALL_TIME, XMIN_AGO, XD_AGO, XH_AGO, XY_AGO; THIS_YEAR_START, THIS_QUARTER_START, THIS_MONTH_START, THIS_WEEK_START, TODAY_START; LAST_WEEK_START/END, LAST_MONTH_START/END, LAST_QUARTER_START/END, LAST_YEAR_START/END.\nDurations are exact rolling UTC timestamps at both ends: 1D_AGO equals 24H_AGO; 1Y_AGO equals 365 days. Bare duration aliases and case variants are supported.\nExplicit dates and calendar tokens keep calendar boundaries and inclusive final dates. TODAY_START is current-day midnight. Date-only endpoints keep their calendar contracts.\nALL_TIME is full history. It resolves to 2009-01-03. Use ALL_TIME instead of a very large day count.\nWeek starts Monday. Quarters are calendar. Dates: YYYY-MM-DD or ___-MM-DD (year omitted).\nPlease check detailed system instructions for more information.",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Optional date range for market trades. Defaults to the last 7 days."
}
},
"description": "Request for recent market trades.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
PnL leaderboard for a Polymarket market.
**When to use:**
- Only for profitability claims.
**Key fields:**
- `Total PnL USD` = redemption + unrealized value + sell proceeds − buy
cost, for this market only.
- `Net Buy Cost USD` is what the wallet paid for shares.
- `Net Sell Proceeds USD` is what it received for shares sold before
resolution.
- `Redemption Value USD` is the payout collected after the market settled.
- `Unrealized Value USD` is the marked value of shares still held.
- `Side Held` reflects current side exposure where the API provides it.
**Pitfalls:**
- The API gives no ROI, volume, or trade count here. Do not state them.
- If PnL fields are blank, say profitability is unavailable — do not
substitute top holders or position size.
**Prerequisites:** If `marketId` is unknown, call
`prediction_market_lookup` first.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number for paginated results.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › marketId
Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "prediction_market_pnl_leaderboard",
"title": "Checking prediction market PnL leaders",
"description": "PnL leaderboard for a Polymarket market.\n\n**When to use:**\n- Only for profitability claims.\n\n**Key fields:**\n- `Total PnL USD` = redemption + unrealized value + sell proceeds − buy\n cost, for this market only.\n- `Net Buy Cost USD` is what the wallet paid for shares.\n- `Net Sell Proceeds USD` is what it received for shares sold before\n resolution.\n- `Redemption Value USD` is the payout collected after the market settled.\n- `Unrealized Value USD` is the marked value of shares still held.\n- `Side Held` reflects current side exposure where the API provides it.\n\n**Pitfalls:**\n- The API gives no ROI, volume, or trade count here. Do not state them.\n- If PnL fields are blank, say profitability is unavailable — do not\n substitute top holders or position size.\n\n**Prerequisites:** If `marketId` is unknown, call\n`prediction_market_lookup` first.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"marketId"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for paginated results."
},
"marketId": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool."
}
},
"description": "Request for market-level PnL leaderboard.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
Align the title with the capability actually described by this tool.
Description83/100
Detailed position breakdown for a Polymarket market.
**Key fields:**
- `Position Size (Shares)` is the share quantity still held.
- `Buy Cost USD` and `Sell Proceeds USD` are the cash paid and received
for this outcome token.
- `Unrealized Value USD` is the marked value of shares still held;
`Redemption Value USD` is the payout collected after settlement.
- `Position PnL USD` applies to the displayed row only — not the
wallet's total PM activity.
**Pitfalls:**
- Each row is one outcome token of one wallet. A wallet holding both
sides appears twice.
**Prerequisites:** If `marketId` is unknown, call
`prediction_market_lookup` first.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number for paginated results.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › marketId
Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "prediction_market_position_detail",
"title": "Loading prediction market position",
"description": "Detailed position breakdown for a Polymarket market.\n\n**Key fields:**\n- `Position Size (Shares)` is the share quantity still held.\n- `Buy Cost USD` and `Sell Proceeds USD` are the cash paid and received\n for this outcome token.\n- `Unrealized Value USD` is the marked value of shares still held;\n `Redemption Value USD` is the payout collected after settlement.\n- `Position PnL USD` applies to the displayed row only — not the\n wallet's total PM activity.\n\n**Pitfalls:**\n- Each row is one outcome token of one wallet. A wallet holding both\n sides appears twice.\n\n**Prerequisites:** If `marketId` is unknown, call\n`prediction_market_lookup` first.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"marketId"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for paginated results."
},
"marketId": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool."
}
},
"description": "Request for detailed market positions.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description81/100
Prediction market trade history for a Polygon wallet.
**Key fields:**
- `Share Size` is quantity traded in the displayed outcome side.
- `Value USD` applies to that row only, not the whole transaction.
**Pitfalls:**
- Use this for wallet trade activity, not profitability.
The description explains the capability, when to use it, and what to expect.
Inputs81/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number for paginated results.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › address
Polygon wallet address to analyze.
Clear enough to supply this argument.
request › dateRange › anyOf › 0 › from
Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › dateRange › anyOf › 0 › to
End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight.
Clear enough to supply this argument.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "prediction_market_address_trades",
"title": "Checking prediction market address trades",
"description": "Prediction market trade history for a Polygon wallet.\n\n**Key fields:**\n- `Share Size` is quantity traded in the displayed outcome side.\n- `Value USD` applies to that row only, not the whole transaction.\n\n**Pitfalls:**\n- Use this for wallet trade activity, not profitability.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"address"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for paginated results."
},
"address": {
"type": "string",
"description": "Polygon wallet address to analyze."
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"description": "End token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps without an extra day. Dates and calendar tokens include the final date; TODAY_START stays at midnight."
},
"from": {
"type": "string",
"description": "Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
}
},
"description": "Date range via tokens or dates.\nTokens: NOW, ALL_TIME, XMIN_AGO, XD_AGO, XH_AGO, XY_AGO; THIS_YEAR_START, THIS_QUARTER_START, THIS_MONTH_START, THIS_WEEK_START, TODAY_START; LAST_WEEK_START/END, LAST_MONTH_START/END, LAST_QUARTER_START/END, LAST_YEAR_START/END.\nDurations are exact rolling UTC timestamps at both ends: 1D_AGO equals 24H_AGO; 1Y_AGO equals 365 days. Bare duration aliases and case variants are supported.\nExplicit dates and calendar tokens keep calendar boundaries and inclusive final dates. TODAY_START is current-day midnight. Date-only endpoints keep their calendar contracts.\nALL_TIME is full history. It resolves to 2009-01-03. Use ALL_TIME instead of a very large day count.\nWeek starts Monday. Quarters are calendar. Dates: YYYY-MM-DD or ___-MM-DD (year omitted).\nPlease check detailed system instructions for more information.",
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Optional date range for address trades. Defaults to the last 30 days."
}
},
"description": "Request for address-level prediction market trades.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Prediction market summary metrics for a Polygon wallet.
**When to use:**
- First wallet-level Polymarket tool for a quick trader overview.
- Use before detailed address trades/PnL when the user asks for a general
wallet profile, activity summary, or whether a wallet is active on
Polymarket.
**Key fields:**
- `Markets Traded` and `Markets Won` are lifetime counts; `Win Rate` is
won / traded.
- `Total PnL USD` = realized + unrealized.
- `First Seen` and `Wallet Age (Days)` show how long the wallet has been
active on Polymarket.
**Pitfalls:**
- The API gives no trade count, volume, or ROI here. Do not state them.
For per-market cost and proceeds use `prediction_market_address_pnl`.
- Blank PnL fields mean unavailable data, not zero.
The description explains the capability, when to use it, and what to expect.
Inputs72/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number for paginated results.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › address
Polygon wallet address to analyze.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "prediction_market_address_summary",
"title": "Summarizing prediction market address",
"description": "Prediction market summary metrics for a Polygon wallet.\n\n**When to use:**\n- First wallet-level Polymarket tool for a quick trader overview.\n- Use before detailed address trades/PnL when the user asks for a general\n wallet profile, activity summary, or whether a wallet is active on\n Polymarket.\n\n**Key fields:**\n- `Markets Traded` and `Markets Won` are lifetime counts; `Win Rate` is\n won / traded.\n- `Total PnL USD` = realized + unrealized.\n- `First Seen` and `Wallet Age (Days)` show how long the wallet has been\n active on Polymarket.\n\n**Pitfalls:**\n- The API gives no trade count, volume, or ROI here. Do not state them.\n For per-market cost and proceeds use `prediction_market_address_pnl`.\n- Blank PnL fields mean unavailable data, not zero.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"address"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for paginated results."
},
"address": {
"type": "string",
"description": "Polygon wallet address to analyze."
}
},
"description": "Request for address-level prediction market summary metrics.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Prediction market PnL breakdown for a Polygon wallet, market by market.
**When to use:**
- Wallet-level Polymarket track record with per-market cost and proceeds.
**Key fields:**
- `Total PnL USD` = redemption + unrealized value + sell proceeds − buy
cost, for that market only.
- `Net Buy Cost USD` is what the wallet paid for shares.
- `Net Sell Proceeds USD` is what it received for shares sold before
resolution.
- `Redemption Value USD` is the payout collected after the market settled.
- `Unrealized Value USD` is the marked value of shares still held.
- `Resolved` says whether the market has settled.
**Pitfalls:**
- Each row covers one market. Sum the rows for a wallet total, or use
`prediction_market_address_summary` for the aggregate.
- The API gives no ROI or share count here. Do not state them.
- Blank PnL fields mean unavailable data, not zero.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › page
Page number for paginated results.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
request › address
Polygon wallet address to analyze.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"name": "prediction_market_address_pnl",
"title": "Checking prediction market address PnL",
"description": "Prediction market PnL breakdown for a Polygon wallet, market by market.\n\n**When to use:**\n- Wallet-level Polymarket track record with per-market cost and proceeds.\n\n**Key fields:**\n- `Total PnL USD` = redemption + unrealized value + sell proceeds − buy\n cost, for that market only.\n- `Net Buy Cost USD` is what the wallet paid for shares.\n- `Net Sell Proceeds USD` is what it received for shares sold before\n resolution.\n- `Redemption Value USD` is the payout collected after the market settled.\n- `Unrealized Value USD` is the marked value of shares still held.\n- `Resolved` says whether the market has settled.\n\n**Pitfalls:**\n- Each row covers one market. Sum the rows for a wallet total, or use\n `prediction_market_address_summary` for the aggregate.\n- The API gives no ROI or share count here. Do not state them.\n- Blank PnL fields mean unavailable data, not zero.",
"inputSchema": {
"type": "object",
"required": [
"request"
],
"properties": {
"request": {
"type": "object",
"required": [
"address"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for paginated results."
},
"address": {
"type": "string",
"description": "Polygon wallet address to analyze."
}
},
"description": "Request for address-level prediction market PnL.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}
}
Loading score analytics…
Put your MCP to the test
A few tasks worth trying with this server, chosen from its reviewed tools. These have not been run.
01Prediction market lookupSearch Polymarket for events and markets by name, topic, URL, or slug.
02Prediction market screenerBrowse and sort Polymarket markets, events, or categories.
03Searching tokens, companies, and addressesGeneral search tool.
04Ranking Smart Money by PnLRank smart trader addresses (EXCLUDES whales, large holders, influencers, etc.) by realized, unrealized and total USD PnL over a 1/7/30/90/180 day window, wi…
05Ranking top tokens by Nansen ScoreDiscover and filter a daily list of attractive tokens using Nansen Score Indicators weighted by coefficients (= Performance Score).
Want to run these tasks against your MCP server with us?
nansen-mcp setup, tools, quality score, publishing readiness, and alternatives.
How do I add nansen-mcp to Claude, ChatGPT, or Cursor?
Add nansen-mcp to Claude, ChatGPT, or Cursor by connecting its remote MCP URL in each client's MCP settings. In Claude, add a custom connector. In ChatGPT, add an MCP app. In Cursor, add an MCP server under Settings. The MCP URL is https://mcp.nansen.ai/ra/mcp.
Is nansen-mcp MCP ready for ChatGPT and Claude?
As of November 17, 2026, nansen-mcp scores 96/100 on Manufact's MCP publishing checklist. The scan meets ChatGPT publishing checks and meets Claude publishing checks. Passing these checks does not guarantee marketplace approval.
How clear is nansen-mcp's MCP tool documentation?
As of November 17, 2026, nansen-mcp scores 73/100 in Manufact's review of tool titles, descriptions, input and output schemas, and behavior annotations. The review covers 54 of 54 discovered tools. The quality score measures documentation clarity; runtime behavior and marketplace readiness require separate checks.
What are the best alternatives to nansen-mcp?
As of November 17, 2026, alternatives to nansen-mcp in financial-services on the Manufact MCP leaderboard include Blockworks, SHVL credit control, BankConv, Economico, and DefiLlama.
How can nansen-mcp improve its MCP documentation?
transaction_lookup is the lowest-scoring reviewed tool at 51/100. 0 of 2 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values. Open its review for feedback and a copyable fix prompt, then rerun the documentation review after updating your tool metadata.
Not your MCP?
Review any public or OAuth MCP server for protocol compatibility, tool documentation, and ChatGPT and Claude publishing readiness. No account required.