Nansen

Finding recent traders

token_who_bought_sold

Read-only

Get TOTAL amount of tokens bought/sold by address for 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
- **Gross Token Volume**: Combined buy and sell volume in tokens
- **Bought Volume USD**: USD value of all token purchases
- **Sold Volume USD**: USD value of all token sales
- **Gross Volume USD**: Combined USD trading volume

Sorting Options: You can sort asc or desc by bought_volume_usd or sold_volume_usd

Notes: - buy_or_sell parameter filters for "BUY" (net buyers) or "SELL" (net sellers) - Aggregates all trading activity within the specified time range

Input Schema

TableJSON Schema

Name	Required	Description	Default
`request`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedMay 29, 2026

changedInput schema / properties / request / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "description": "Complete request for token who bought/sold (flattened).",
-    "properties": {
-      "buy_or_sell": {
-        "description": "Transaction type for buyers or sellers analysis",
-        "enum": [
-          "BUY",
-          "SELL"
-        ],
-        "type": "string"
-      },
-      "chain": {
-        "type": "string"
-      },
-      "include_labels": {
-        "description": "Filter based on a particular set of segments based on label, default is empty which includes all segments",
-        "items": {
-          "description": "Wallet labels for holder analysis and filtering.",
-          "enum": [
-            "Whale",
-            "Public Figure",
-            "Exchange",
-            "Fund",
-            "30D Smart Trader",
-            "90D Smart Trader",
-            "180D Smart Trader",
-            "All Time Smart Trader"
-          ],
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "min_trade_volume_usd": {
-        "default": 10,
-        "type": "number"
-      },
-      "order_by": {
-        "default": "bought_volume_usd",
-        "type": "string"
-      },
-      "order_by_direction": {
-        "default": "DESC",
-        "enum": [
-          "asc",
-          "desc",
-          "ASC",
-          "DESC"
-        ],
-        "type": "string"
-      },
-      "page": {
-        "default": 1,
-        "type": "integer"
-      },
-      "time_range": {
-        "description": "Date range for 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"
-      },
-      "tokenAddress": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "chain",
-      "tokenAddress",
-      "buy_or_sell"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  {
+    "description": "Complete request for token who bought/sold (flattened).",
+    "properties": {
+      "buy_or_sell": {
+        "description": "Transaction type for buyers or sellers analysis",
+        "enum": [
+          "BUY",
+          "SELL"
+        ],
+        "type": "string"
+      },
+      "chain": {
+        "type": "string"
+      },
+      "include_labels": {
+        "description": "Filter based on a particular set of segments based on label, default is empty which includes all segments",
+        "items": {
+          "description": "Wallet labels for holder analysis and filtering.",
+          "enum": [
+            "Whale",
+            "Public Figure",
+            "Exchange",
+            "Fund",
+            "30D Smart Trader",
+            "90D Smart Trader",
+            "180D Smart Trader",
+            "All Time Smart Trader"
+          ],
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "min_trade_volume_usd": {
+        "default": 10,
+        "type": "number"
+      },
+      "orderBy": {
+        "anyOf": [
+          {
+            "enum": [
+              "token_trade_volume",
+              "bought_token_volume",
+              "sold_token_volume"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Sort field. Pass an exact value above or None for default ('token_trade_volume'). USD volume fields are disabled; native token volume is preferred."
+      },
+      "order_by_direction": {
+        "default": "DESC",
+        "enum": [
+          "ASC",
+          "DESC",
+          "asc",
+          "desc"
+        ],
+        "type": "string"
+      },
+      "page": {
+        "default": 1,
+        "type": "integer"
+      },
+      "time_range": {
+        "description": "Date range for 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"
+      },
+      "tokenAddress": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "chain",
+      "tokenAddress",
+      "buy_or_sell"
+    ],
+    "type": "object"
+  }
+]

Changed3 schema fields changedMay 19, 2026

removedInput schema / $defs

Removed value: -{
-  "BuyOrSell": {
-    "description": "Transaction types for buy/sell analysis.",
-    "enum": [
-      "BUY",
-      "SELL"
-    ],
-    "type": "string"
-  },
-  "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"
-  },
-  "TokenWhoBoughtSoldRequest": {
-    "description": "Complete request for token who bought/sold (flattened).",
-    "properties": {
-      "buy_or_sell": {
-        "$ref": "#/$defs/BuyOrSell",
-        "description": "Transaction type for buyers or sellers analysis"
-      },
-      "chain": {
-        "type": "string"
-      },
-      "include_labels": {
-        "description": "Filter based on a particular set of segments based on label, default is empty which includes all segments",
-        "items": {
-          "$ref": "#/$defs/WalletLabel"
-        },
-        "type": "array"
-      },
-      "min_trade_volume_usd": {
-        "default": 10,
-        "type": "number"
-      },
-      "order_by": {
-        "default": "bought_volume_usd",
-        "type": "string"
-      },
-      "order_by_direction": {
-        "default": "DESC",
-        "enum": [
-          "asc",
-          "desc",
-          "ASC",
-          "DESC"
-        ],
-        "type": "string"
-      },
-      "page": {
-        "default": 1,
-        "type": "integer"
-      },
-      "time_range": {
-        "$ref": "#/$defs/DateRange",
-        "description": "Date range for analysis"
-      },
-      "tokenAddress": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "chain",
-      "tokenAddress",
-      "buy_or_sell"
-    ],
-    "type": "object"
-  },
-  "WalletLabel": {
-    "description": "Wallet labels for holder analysis and filtering.",
-    "enum": [
-      "Whale",
-      "Public Figure",
-      "Exchange",
-      "Fund",
-      "30D Smart Trader",
-      "90D Smart Trader",
-      "180D Smart Trader",
-      "All Time Smart Trader"
-    ],
-    "type": "string"
-  }
-}

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

changedInput schema / properties / request / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "$ref": "#/$defs/TokenWhoBoughtSoldRequest"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  {
+    "description": "Complete request for token who bought/sold (flattened).",
+    "properties": {
+      "buy_or_sell": {
+        "description": "Transaction type for buyers or sellers analysis",
+        "enum": [
+          "BUY",
+          "SELL"
+        ],
+        "type": "string"
+      },
+      "chain": {
+        "type": "string"
+      },
+      "include_labels": {
+        "description": "Filter based on a particular set of segments based on label, default is empty which includes all segments",
+        "items": {
+          "description": "Wallet labels for holder analysis and filtering.",
+          "enum": [
+            "Whale",
+            "Public Figure",
+            "Exchange",
+            "Fund",
+            "30D Smart Trader",
+            "90D Smart Trader",
+            "180D Smart Trader",
+            "All Time Smart Trader"
+          ],
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "min_trade_volume_usd": {
+        "default": 10,
+        "type": "number"
+      },
+      "order_by": {
+        "default": "bought_volume_usd",
+        "type": "string"
+      },
+      "order_by_direction": {
+        "default": "DESC",
+        "enum": [
+          "asc",
+          "desc",
+          "ASC",
+          "DESC"
+        ],
+        "type": "string"
+      },
+      "page": {
+        "default": 1,
+        "type": "integer"
+      },
+      "time_range": {
+        "description": "Date range for 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"
+      },
+      "tokenAddress": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "chain",
+      "tokenAddress",
+      "buy_or_sell"
+    ],
+    "type": "object"
+  }
+]

First observedFeb 18, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context beyond that: DEX-only scope, aggregation behavior, markdown output, empty-string behavior when no data exists, net buyer/seller semantics for buy_or_sell, and time-range aggregation. No contradiction exists between the description and annotations.

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

Conciseness4/5

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

The description is well-structured with clear sections for returns, columns, sorting, and notes, making it easy for an agent to scan. The column list is lengthy but earns its place because the output format matters for downstream parsing. It is slightly redundant given an output schema exists, but not excessively bloated.

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?

For a read-only DEX analysis tool, the description covers the core decision context, return shape, sorting intent, and net buyer/seller semantics. The main gaps are the missing optional parameter guidance and the misleading sorting field names, though the input schema partially compensates for those. Overall it is complete enough for an agent to use the tool successfully most of the time.

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

Parameters2/5

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

With schema description coverage reported at 0%, the description carries the burden of explaining parameters, but it only partially does so. It usefully clarifies buy_or_sell and time-range semantics, but omits several parameters such as chain, tokenAddress, include_labels, page, min_trade_volume_usd, and order_by_direction. More seriously, the sorting guidance mentions bought_volume_usd/sold_volume_usd, which do not match the orderBy enum values (bought_token_volume/sold_token_volume) and conflicts with the schema note that USD volume fields are disabled.

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 opens with a specific verb and resource: 'Get TOTAL amount of tokens bought/sold by address for a token on DEX ONLY.' It clearly defines this as an aggregated per-trader view rather than a raw transaction log, which distinguishes it from sibling trade/list tools. The title 'Finding recent traders' reinforces the intended use case without creating ambiguity.

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

Usage Guidelines4/5

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

The description explicitly states when to use it: to find out who is buying or selling a token and to infer whether they are liquidating profits or accumulating more. It also constrains the tool to DEX-only data. It does not name sibling alternatives or explicitly state when not to use it, so it stops short of a 5.

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

All Nansen tools Inspect

Try in Browser

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

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?