Skip to main content
Glama

Nansen

by io.github.hurcanNansen
OverviewDiscussionsAdmin

Comparing wallet connections

address_counterparties_batch
Read-only

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 }

Input Schema

NameRequiredDescriptionDefault
requestYesComplete request for batch address counterparties (flattened). Wallet addresses only. Use AddressCounterpartiesRequest for one wallet or for an entity name.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / request / properties / filters / anyOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "description": "Row filters for batch counterparties. Each filter drops counterparty rows.",
-    "properties": {
-      "excludeSmartMoneyLabels": {
-        "anyOf": [
-          {
-            "items": {
-              "enum": [
-                "30D Smart Trader",
-                "90D Smart Trader",
-                "180D Smart Trader",
-                "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": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Drop counterparties that carry one of these labels"
-      },
-      "includeSmartMoneyLabels": {
-        "anyOf": [
-          {
-            "items": {
-              "enum": [
-                "30D Smart Trader",
-                "90D Smart Trader",
-                "180D Smart Trader",
-                "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": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Keep only counterparties that carry one of these labels"
-      },
-      "interactionCount": {
-        "anyOf": [
-          {
-            "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
-            "properties": {
-              "from": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Minimum value (inclusive), optional"
-              },
-              "to": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Maximum value (inclusive), optional"
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Keep counterparties whose interaction count is in this range"
-      },
-      "totalVolumeUsd": {
-        "anyOf": [
-          {
-            "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
-            "properties": {
-              "from": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Minimum value (inclusive), optional"
-              },
-              "to": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Maximum value (inclusive), optional"
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Keep counterparties whose total USD volume is in this range"
-      },
-      "volumeInUsd": {
-        "anyOf": [
-          {
-            "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
-            "properties": {
-              "from": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Minimum value (inclusive), optional"
-              },
-              "to": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Maximum value (inclusive), optional"
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Keep counterparties whose incoming USD volume is in this range"
-      },
-      "volumeOutUsd": {
-        "anyOf": [
-          {
-            "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
-            "properties": {
-              "from": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Minimum value (inclusive), optional"
-              },
-              "to": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Maximum value (inclusive), optional"
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Keep counterparties whose outgoing USD volume is in this range"
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "description": "Row filters for batch counterparties. Each filter drops counterparty rows.",
+    "properties": {
+      "excludeSmartMoneyLabels": {
+        "anyOf": [
+          {
+            "items": {
+              "enum": [
+                "30D Smart Trader",
+                "90D Smart Trader",
+                "180D Smart Trader",
+                "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": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Drop counterparties that carry one of these labels"
+      },
+      "includeSmartMoneyLabels": {
+        "anyOf": [
+          {
+            "items": {
+              "enum": [
+                "30D Smart Trader",
+                "90D Smart Trader",
+                "180D Smart Trader",
+                "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": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Keep only counterparties that carry one of these labels"
+      },
+      "interactionCount": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
+            "properties": {
+              "from": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "Minimum value (inclusive), optional"
+              },
+              "to": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "Maximum value (inclusive), optional"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Keep counterparties whose interaction count is in this range"
+      },
+      "totalVolumeUsd": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
+            "properties": {
+              "from": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "Minimum value (inclusive), optional"
+              },
+              "to": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "Maximum value (inclusive), optional"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Keep counterparties whose total USD volume is in this range"
+      },
+      "volumeInUsd": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
+            "properties": {
+              "from": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "Minimum value (inclusive), optional"
+              },
+              "to": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "Maximum value (inclusive), optional"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Keep counterparties whose incoming USD volume is in this range"
+      },
+      "volumeOutUsd": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
+            "properties": {
+              "from": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "Minimum value (inclusive), optional"
+              },
+              "to": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "Maximum value (inclusive), optional"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Keep counterparties whose outgoing USD volume is in this range"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / request / properties / timeRange / additionalProperties
      Added value: +false
  2. Changed2 schema fields changed
    • changedInput schema / properties / request / properties / timeRange / properties / from / description
      Previous value: -"Start value: token (see above) or date (YYYY-MM-DD or ___-MM-DD)."New value: +"Start token or date (YYYY-MM-DD or ___-MM-DD). Durations use exact rolling UTC timestamps; dates and calendar tokens start at midnight."
    • changedInput schema / properties / request / properties / timeRange / properties / to / description
      Previous value: -"End value: token (see above) or date (YYYY-MM-DD or ___-MM-DD)."New value: +"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."
  3. Added

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the read-only annotations, the description discloses important behavioral constraints: per-wallet lists are not aggregated, repeated addresses are removed, at most 10 addresses are allowed, the date range cannot exceed 90 days, and chain families cannot be mixed. It also warns that multi-chain results may repeat counterparties across rows and should not be summed.

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 front-loaded with purpose, per-wallet behavior, use cases, limits, and an example. It is somewhat long and repeats some schema details, but the example and constraints generally earn their place for a complex batch tool.

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

Completeness5/5

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

Given the output schema and rich annotations, the description covers the key invocation risks: wallet count, date window, chain-family mixing, pagination implications, and the correct sibling for non-batch use. Nothing essential for correct tool selection or invocation is missing.

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?

Schema coverage is already 100%, so the schema documents parameters thoroughly. The description still adds operational meaning through a concrete request example, sort options, chain behavior, and limits that help an agent construct valid calls.

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 states a specific verb and resource: getting top counterparties for up to 10 wallet addresses in one call. It clearly distinguishes this batch tool from the single-wallet/entity tool by naming address_counterparties as the alternative.

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?

It explicitly says when to use this tool for comparing wallets, shared counterparties, common CEX deposits, or one fund with many wallets. It also states when not to use it: for one wallet or an entity name, use address_counterparties.

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

All Nansen toolsInspect
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