Nansen

Tracking token movements

token_flows

Read-only

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
`mode`	No
`rows`	No
`chain`	No
`date_to`	No
`message`	No	Notice or error text when the tool returns no data rows.
`date_from`	No
`pagination`	No
`token_address`	No
`holder_segment`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedSep 23, 2026

addedOutput schema / description

Added value: +"Structured result of `token_flows`."

addedOutput schema / properties / chain

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Chain"
+}

addedOutput schema / properties / date_from

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Date From"
+}

addedOutput schema / properties / date_to

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Date To"
+}

addedOutput schema / properties / holder_segment

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Holder Segment"
+}

addedOutput schema / properties / message

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Notice or error text when the tool returns no data rows.",
+  "title": "Message"
+}

addedOutput schema / properties / mode

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "onchain_tokens",
+        "perps"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Mode"
+}

addedOutput schema / properties / pagination

Added value: +{
+  "anyOf": [
+    {
+      "description": "Page position of the returned rows.",
+      "properties": {
+        "is_last_page": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Is Last Page"
+        },
+        "page": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Page"
+        },
+        "per_page": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Per Page"
+        }
+      },
+      "title": "Pagination",
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

removedOutput schema / properties / result

Removed value: -{
-  "type": "string"
-}

addedOutput schema / properties / rows

Added value: +{
+  "items": {
+    "description": "One time bucket of tracked holdings for the requested holder segment.",
+    "properties": {
+      "date": {
+        "description": "Bucket timestamp (UTC).",
+        "title": "Date",
+        "type": "string"
+      },
+      "holders_count": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Holders in the segment.",
+        "title": "Holders Count"
+      },
+      "price_usd": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Token price in USD.",
+        "title": "Price Usd"
+      },
+      "token_amount": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Tracked balance in tokens (perps: total position size).",
+        "title": "Token Amount"
+      },
+      "total_inflows_count": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Inflows in the bucket (perps: longs).",
+        "title": "Total Inflows Count"
+      },
+      "total_outflows_count": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Outflows in the bucket (perps: shorts).",
+        "title": "Total Outflows Count"
+      },
+      "value_usd": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Tracked balance in USD.",
+        "title": "Value Usd"
+      }
+    },
+    "required": [
+      "date"
+    ],
+    "title": "TokenFlowRow",
+    "type": "object"
+  },
+  "title": "Rows",
+  "type": "array"
+}

addedOutput schema / properties / token_address

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Token Address"
+}

removedOutput schema / required
```
Removed value: -[
-  "result"
-]
```
addedOutput schema / title
```
Added value: +"TokenFlowsOutput"
```
removedOutput schema / x-fastmcp-wrap-result
```
Removed value: -true
```

Changed1 schema field changedSep 16, 2026