Nansen

Tracking token movements

token_flows

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`request`	Yes	TokenFlowsRequest containing parameters and pagination settings

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

Changed1 schema field changedAug 10, 2026

changedInput schema / properties / request / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "description": "Complete request for token flows (flattened).",
-    "properties": {
-      "chain": {
-        "default": "ethereum",
-        "description": "Blockchain network. Supported: arbitrum, 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",
-        "type": "string"
-      },
-      "dateRange": {
-        "description": "Date range for flow analysis",
-        "properties": {
-          "from": {
-            "description": "Start value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
-            "type": "string"
-          },
-          "to": {
-            "description": "End value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
-            "type": "string"
-          }
-        },
-        "required": [
-          "from",
-          "to"
-        ],
-        "type": "object"
-      },
-      "holder_segment": {
-        "default": "top_100_holders",
-        "description": "Label types for holder analysis and filtering.",
-        "enum": [
-          "whale",
-          "public_figure",
-          "smart_money",
-          "top_100_holders",
-          "exchange"
-        ],
-        "type": "string"
-      },
-      "mode": {
-        "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'.",
-        "enum": [
-          "onchain_tokens",
-          "perps"
-        ],
-        "type": "string"
-      },
-      "tokenAddress": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "tokenAddress"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  {
+    "description": "Complete request for token flows (flattened).",
+    "properties": {
+      "chain": {
+        "default": "ethereum",
+        "description": "Blockchain network. Supported: arbitrum, 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",
+        "type": "string"
+      },
+      "dateRange": {
+        "description": "Date range for flow analysis",
+        "properties": {
+          "from": {
+            "description": "Start value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
+            "type": "string"
+          },
+          "to": {
+            "description": "End value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "from",
+          "to"
+        ],
+        "type": "object"
+      },
+      "holder_segment": {
+        "default": "top_100_holders",
+        "description": "Label types for holder analysis and filtering.",
+        "enum": [
+          "whale",
+          "public_figure",
+          "smart_money",
+          "top_100_holders",
+          "exchange"
+        ],
+        "type": "string"
+      },
+      "mode": {
+        "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'.",
+        "enum": [
+          "onchain_tokens",
+          "perps"
+        ],
+        "type": "string"
+      },
+      "page": {
+        "default": 1,
+        "description": "Page number, starting at 1",
+        "minimum": 1,
+        "type": "integer"
+      },
+      "perPage": {
+        "default": 10,
+        "description": "Number of records per page, from 1 to 1000",
+        "maximum": 1000,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "tokenAddress": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "tokenAddress"
+    ],
+    "type": "object"
+  }
+]

Changed1 schema field changedJul 18, 2026

changedInput schema / properties / request / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "description": "Complete request for token flows (flattened).",
-    "properties": {
-      "chain": {
-        "default": "ethereum",
-        "description": "Blockchain network. Supported: arbitrum, avalanche, base, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync",
-        "type": "string"
-      },
-      "dateRange": {
-        "description": "Date range for flow analysis",
-        "properties": {
-          "from": {
-            "description": "Start value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
-            "type": "string"
-          },
-          "to": {
-            "description": "End value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
-            "type": "string"
-          }
-        },
-        "required": [
-          "from",
-          "to"
-        ],
-        "type": "object"
-      },
-      "holder_segment": {
-        "default": "top_100_holders",
-        "description": "Label types for holder analysis and filtering.",
-        "enum": [
-          "whale",
-          "public_figure",
-          "smart_money",
-          "top_100_holders",
-          "exchange"
-        ],
-        "type": "string"
-      },
-      "mode": {
-        "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'.",
-        "enum": [
-          "onchain_tokens",
-          "perps"
-        ],
-        "type": "string"
-      },
-      "tokenAddress": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "tokenAddress"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  {
+    "description": "Complete request for token flows (flattened).",
+    "properties": {
+      "chain": {
+        "default": "ethereum",
+        "description": "Blockchain network. Supported: arbitrum, 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",
+        "type": "string"
+      },
+      "dateRange": {
+        "description": "Date range for flow analysis",
+        "properties": {
+          "from": {
+            "description": "Start value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
+            "type": "string"
+          },
+          "to": {
+            "description": "End value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "from",
+          "to"
+        ],
+        "type": "object"
+      },
+      "holder_segment": {
+        "default": "top_100_holders",
+        "description": "Label types for holder analysis and filtering.",
+        "enum": [
+          "whale",
+          "public_figure",
+          "smart_money",
+          "top_100_holders",
+          "exchange"
+        ],
+        "type": "string"
+      },
+      "mode": {
+        "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'.",
+        "enum": [
+          "onchain_tokens",
+          "perps"
+        ],
+        "type": "string"
+      },
+      "tokenAddress": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "tokenAddress"
+    ],
+    "type": "object"
+  }
+]

Changed1 schema field changedJun 12, 2026

changedInput schema / properties / request / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "description": "Complete request for token flows (flattened).",
-    "properties": {
-      "chain": {
-        "default": "ethereum",
-        "description": "Blockchain network. Supported: arbitrum, avalanche, base, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync",
-        "type": "string"
-      },
-      "dateRange": {
-        "description": "Date range for flow analysis",
-        "properties": {
-          "from": {
-            "description": "Start value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
-            "type": "string"
-          },
-          "to": {
-            "description": "End value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
-            "type": "string"
-          }
-        },
-        "required": [
-          "from",
-          "to"
-        ],
-        "type": "object"
-      },
-      "holder_segment": {
-        "default": "top_100_holders",
-        "description": "Label types for holder analysis and filtering.",
-        "enum": [
-          "whale",
-          "public_figure",
-          "smart_money",
-          "top_100_holders",
-          "exchange"
-        ],
-        "type": "string"
-      },
-      "mode": {
-        "default": "onchain_tokens",
-        "description": "Analysis mode: 'onchain_tokens' for on-chain tokens by contract address, 'perps' for Hyperliquid perpetual futures by symbol",
-        "enum": [
-          "onchain_tokens",
-          "perps"
-        ],
-        "type": "string"
-      },
-      "tokenAddress": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "tokenAddress"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  {
+    "description": "Complete request for token flows (flattened).",
+    "properties": {
+      "chain": {
+        "default": "ethereum",
+        "description": "Blockchain network. Supported: arbitrum, avalanche, base, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync",
+        "type": "string"
+      },
+      "dateRange": {
+        "description": "Date range for flow analysis",
+        "properties": {
+          "from": {
+            "description": "Start value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
+            "type": "string"
+          },
+          "to": {
+            "description": "End value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "from",
+          "to"
+        ],
+        "type": "object"
+      },
+      "holder_segment": {
+        "default": "top_100_holders",
+        "description": "Label types for holder analysis and filtering.",
+        "enum": [
+          "whale",
+          "public_figure",
+          "smart_money",
+          "top_100_holders",
+          "exchange"
+        ],
+        "type": "string"
+      },
+      "mode": {
+        "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'.",
+        "enum": [
+          "onchain_tokens",
+          "perps"
+        ],
+        "type": "string"
+      },
+      "tokenAddress": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "tokenAddress"
+    ],
+    "type": "object"
+  }
+]

Changed4 schema fields changedMay 19, 2026

removedInput schema / $defs

Removed value: -{
-  "DateRange": {
-    "description": "Date range via tokens or dates.\nTokens: NOW, XMIN_AGO, XD_AGO, XH_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.\nWeek starts Monday. Quarters are calendar. Dates: YYYY-MM-DD or ___-MM-DD (year omitted).\nPlease check detailed system instructions for more information.",
-    "properties": {
-      "from": {
-        "description": "Start value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
-        "type": "string"
-      },
-      "to": {
-        "description": "End value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
-        "type": "string"
-      }
-    },
-    "required": [
-      "from",
-      "to"
-    ],
-    "type": "object"
-  },
-  "SegmentType": {
-    "description": "Label types for holder analysis and filtering.",
-    "enum": [
-      "whale",
-      "public_figure",
-      "smart_money",
-      "top_100_holders",
-      "exchange"
-    ],
-    "type": "string"
-  },
-  "TokenFlowsRequest": {
-    "description": "Complete request for token flows (flattened).",
-    "properties": {
-      "chain": {
-        "default": "ethereum",
-        "description": "Blockchain network. Supported: arbitrum, avalanche, base, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync",
-        "type": "string"
-      },
-      "dateRange": {
-        "$ref": "#/$defs/DateRange",
-        "description": "Date range for flow analysis"
-      },
-      "holder_segment": {
-        "$ref": "#/$defs/SegmentType",
-        "default": "top_100_holders"
-      },
-      "mode": {
-        "default": "onchain_tokens",
-        "description": "Analysis mode: 'onchain_tokens' for on-chain tokens by contract address, 'perps' for Hyperliquid perpetual futures by symbol",
-        "enum": [
-          "onchain_tokens",
-          "perps"
-        ],
-        "type": "string"
-      },
-      "tokenAddress": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "tokenAddress"
-    ],
-    "type": "object"
-  }
-}

addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / request / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "$ref": "#/$defs/TokenFlowsRequest"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  {
+    "description": "Complete request for token flows (flattened).",
+    "properties": {
+      "chain": {
+        "default": "ethereum",
+        "description": "Blockchain network. Supported: arbitrum, avalanche, base, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync",
+        "type": "string"
+      },
+      "dateRange": {
+        "description": "Date range for flow analysis",
+        "properties": {
+          "from": {
+            "description": "Start value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
+            "type": "string"
+          },
+          "to": {
+            "description": "End value: token (see above) or date (YYYY-MM-DD or ___-MM-DD).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "from",
+          "to"
+        ],
+        "type": "object"
+      },
+      "holder_segment": {
+        "default": "top_100_holders",
+        "description": "Label types for holder analysis and filtering.",
+        "enum": [
+          "whale",
+          "public_figure",
+          "smart_money",
+          "top_100_holders",
+          "exchange"
+        ],
+        "type": "string"
+      },
+      "mode": {
+        "default": "onchain_tokens",
+        "description": "Analysis mode: 'onchain_tokens' for on-chain tokens by contract address, 'perps' for Hyperliquid perpetual futures by symbol",
+        "enum": [
+          "onchain_tokens",
+          "perps"
+        ],
+        "type": "string"
+      },
+      "tokenAddress": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "tokenAddress"
+    ],
+    "type": "object"
+  }
+]

addedInput schema / properties / request / description

Added value: +"TokenFlowsRequest containing parameters and pagination settings"

Changed1 schema field changedMay 13, 2026

changedInput schema / $defs / TokenFlowsRequest / properties / chain / description

Previous value: -"Blockchain network. Supported: arbitrum, avalanche, base, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, monad, near, optimism, plasma, polygon, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync"New value: +"Blockchain network. Supported: arbitrum, avalanche, base, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync"

Changed1 schema field changedApr 1, 2026

changedInput schema / $defs / TokenFlowsRequest / properties / chain / description

Previous value: -"Blockchain network. Supported: arbitrum, avalanche, base, bnb, ethereum, hyperevm, iotaevm, linea, mantle, monad, near, optimism, plasma, polygon, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync"New value: +"Blockchain network. Supported: arbitrum, avalanche, base, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, monad, near, optimism, plasma, polygon, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync"

First observedFeb 18, 2026

TDQS

A4.5/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses important behavioral traits: the return granularity (hourly), the mode-dependent behavior (perps auto-sets chain to hyperliquid), and the surprising native-token fallback behavior (native placeholder addresses return Hyperliquid perpetual-futures flows with a data-source warning). It also warns about the smart_money segment not being a market proxy. It could add pagination behavior or response shape details, but the key behavioral quirks are covered.

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

Conciseness4/5

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

The description is moderately sized but well-structured with clear sections for modes and a prominent note. It front-loads the core purpose in the first sentence. While the native-token note is long, all content is substantive and earns its place. It loses one point for being somewhat verbose in the final note, but overall it is organized and readable.

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

Completeness4/5

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

Given the tool's complexity (multiple modes, native-token fallback, holder segment caveats) the description covers the critical decision points well. The output schema is present, so return values don't need to be described. It does not explicitly mention pagination parameters or the default holder_segment, but those are in the schema. The description suffices for correct tool selection and invocation, with minor gaps in clarifying that 'more granular' means hourly versus the sibling's snapshot.

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

Parameters4/5

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

The input schema covers parameter descriptions extensively (100% coverage per context), so the description doesn't need to repeat them. The description adds semantic value beyond the schema by explaining the total flows over time frame broken down by segment, and by describing the perps mode meaning (Hyperliquid perpetual futures by symbol) and the native-token fallback behavior, which clarifies the tokenAddress parameter's behavior beyond its bare schema entry.

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

Purpose5/5

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

The description clearly states the tool returns 'hourly token-flow history for ONE holder segment over a date range', identifying the specific verb (get), resource (token-flow history), and scope (one holder segment, date range). It distinguishes itself from sibling token_recent_flows_summary by noting it is 'more granular' and provides 'TOTAL flows over the entire time frame broken down by segment'.

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

Usage Guidelines5/5

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

The description provides explicit guidance on when to use this tool versus alternatives: it says to use token_recent_flows_summary instead for an on-chain snapshot across ALL wallet categories. It also gives a specific warning that holder_segment: smart_money is 'not a good proxy for an overall market view' and should only be used if explicitly requested. The modes section explains when to use perps vs onchain_tokens.

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

All Nansen tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.6/5.0

Disambiguation4/5

Most tools have clearly distinct purposes (address vs token vs prediction market vs transaction). Overlapping tools like token_discovery_screener and nansen_score_top_tokens, or address_counterparties and address_related_addresses, are explicitly disambiguated with detailed usage guidance. A few tools (token_flows vs token_recent_flows_summary) require careful reading but are still distinguishable.

Naming Consistency4/5

Tool names consistently use snake_case with resource prefixes (address_*, token_*, prediction_market_*). Minor deviations include general_search, growth_chain_rank, and nansen_score_top_tokens, and some names like smart_traders_and_funds_perp_trades are verbose but still follow the pattern.

Tool Count3/5

38 tools is a heavy surface, but it matches Nansen's broad domain covering address analytics, token intelligence, prediction markets, and Hyperliquid perps. The count is on the high end and may overwhelm agents, but each tool appears to serve a distinct function within a reasonably scoped analytics platform.

Completeness5/5

The tool surface is comprehensive: address lifecycle (portfolio, transactions, balances, counterparties, PnL), token analytics (price, OHLCV, indicators, flows, transfers, holders, discovery), prediction markets (lookup, orderbook, trades, top holders, PnL), and specialized features (smart money, chain rankings). No obvious dead ends or missing critical operations are apparent.

Resources

Need Help?