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
`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
`buy_or_sell`	No
`token_address`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed13 schema fields changedSep 23, 2026

addedOutput schema / description

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

addedOutput schema / properties / buy_or_sell

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

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 / 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 / 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": "Aggregated DEX buy and sell volume of one address for the token.",
+    "properties": {
+      "address": {
+        "title": "Address",
+        "type": "string"
+      },
+      "address_label": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Address Label"
+      },
+      "bought_token_volume": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Bought Token Volume"
+      },
+      "bought_volume_usd": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Bought Volume Usd"
+      },
+      "sold_token_volume": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Sold Token Volume"
+      },
+      "sold_volume_usd": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Sold Volume Usd"
+      },
+      "token_trade_volume": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Gross token volume (bought + sold).",
+        "title": "Token Trade Volume"
+      },
+      "trade_volume_usd": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Gross USD volume (bought + sold).",
+        "title": "Trade Volume Usd"
+      }
+    },
+    "required": [
+      "address"
+    ],
+    "title": "TokenTraderVolumeRow",
+    "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: +"TokenWhoBoughtSoldOutput"

removedOutput schema / x-fastmcp-wrap-result
```
Removed value: -true
```

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

A3.8/5.0

Behavior5/5

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

With readOnly/openWorld/non-destructive annotations already covering safety, the description adds meaningful behavioral detail: DEX-only coverage, aggregated markdown output, empty-string behavior, listed columns, time-range aggregation, and buy_or_sell net-buyer/net-seller semantics. No contradiction with 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-organized with a purpose sentence, output columns, sorting options, and notes, and it front-loads the core use case. Minor redundancy (DEX-only stated twice) and a fairly long column list keep it from a perfect conciseness score.

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

Completeness3/5

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

For a fairly complex request object, the description covers high-level behavior and output but omits important call details such as required fields, label filtering, minimum volume, pagination, and exact sort field names. The inaccurate sorting statement creates a real risk, though the schema's nested descriptions and output schema mitigate some gaps.

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?

Schema coverage is low, so the description needed to compensate, but it only explains buy_or_sell, sorting, and time range while leaving chain, tokenAddress, include_labels, page, and min_trade_volume_usd to the schema. Worse, its sorting guidance says sort by bought_volume_usd/sold_volume_usd, while the schema's orderBy enum exposes bought_token_volume/sold_token_volume and says USD volume fields are disabled, so the description is actively misleading.

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

Purpose4/5

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

The description opens with a precise verb-and-resource statement: 'Get TOTAL amount of tokens bought/sold by address for a token on DEX ONLY.' This clearly conveys aggregation scope and DEX-only restriction, and it differentiates conceptually from raw transaction listers, though it does not explicitly name a sibling alternative.

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?

'Use this tool to find out WHO is buying or selling a token ... then check if they are liquidating profits or accumulating more' gives a concrete selection criterion and follow-up workflow. It does not state exclusions or name alternatives such as token_dex_trades for trade-level data, so it stops short of full routing guidance.

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?