Nansen

Analyzing wallet connections

address_counterparties

Read-only

Get 25 (per page) addresses or entities with the most common interactions with input addresses Default sort is net value transferred between them. Also returns the top 3 tokens transferred by count for each counterparty

Note: To get related wallets:

Focus on direct value transfers to get most likely addresses.
Include CEX deposit addresses (not withdrawal addresses!) as well.
Also go one level deeper:
- Find addresses that interacted with the most likely addresses.
- Find addresses that deposited to the same CEX deposit (NOT withdrawal!) addresses.
Address structure / string is not important, but the relationship is!

Sorting Options (all fields support "ASC"/"DESC"): Available for sorting: total_volume_usd, volume_in_usd, volume_out_usd, interaction_count

Examples:

Query by single address

{ "address": "0x123...", "sourceInput": "Combined", "groupBy": "wallet", "chain": "ethereum", "timeRange": {"from": "30D_AGO", "to": "NOW"}, "order_by": "total_volume_usd", "order_by_direction": "desc" }

Query by entity

{ "entity_id": "Binance", "sourceInput": "Combined", "groupBy": "entity", "chain": "all", "timeRange": {"from": "7D_AGO", "to": "NOW"} }

Input Schema

TableJSON Schema

Name	Required	Description	Default
`request`	Yes	Complete request for address counterparties (flattened).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 10, 2026

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."

Changed5 schema fields changedJul 24, 2026

removedInput schema / properties / request / anyOf

Removed value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "description": "Complete request for address counterparties (flattened).",
-    "properties": {
-      "address": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Single wallet address to analyze. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
-      },
-      "addresses": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "List of wallet addresses to analyze. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
-      },
-      "chain": {
-        "default": "all",
-        "type": "string"
-      },
-      "entity_id": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). REQUIRED if addresses is not provided. Cannot be used together with addresses."
-      },
-      "groupBy": {
-        "default": "wallet",
-        "description": "Grouping method for counterparties analysis",
-        "enum": [
-          "wallet",
-          "entity"
-        ],
-        "type": "string"
-      },
-      "orderBy": {
-        "anyOf": [
-          {
-            "enum": [
-              "interaction_count",
-              "total_volume_usd",
-              "volume_in_usd",
-              "volume_out_usd"
-            ],
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Sort field. Pass an exact value above or None for default ('total_volume_usd')."
-      },
-      "order_by_direction": {
-        "default": "DESC",
-        "enum": [
-          "ASC",
-          "DESC",
-          "asc",
-          "desc"
-        ],
-        "type": "string"
-      },
-      "page": {
-        "default": 1,
-        "type": "integer"
-      },
-      "sourceInput": {
-        "default": "Combined",
-        "description": "Source input type for counterparties analysis",
-        "enum": [
-          "Combined",
-          "Tokens",
-          "ETH"
-        ],
-        "type": "string"
-      },
-      "timeRange": {
-        "description": "Date range for counterparties analysis. Max window: 365 days — longer ranges are clamped to the most recent year (prevents timeouts in fast/expert mode) and the effective range is reported in the response. Prefer relative tokens (7D_AGO, 30D_AGO, 90D_AGO, 1Y_AGO).",
-        "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"
-      }
-    },
-    "required": [
-      "timeRange"
-    ],
-    "type": "object"
-  }
-]

addedInput schema / properties / request / description

Added value: +"Complete request for address counterparties (flattened)."

addedInput schema / properties / request / properties

Added value: +{
+  "address": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Single wallet address to analyze. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
+  },
+  "chain": {
+    "default": "all",
+    "type": "string"
+  },
+  "entity_id": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). REQUIRED if address is not provided. Cannot be used together with address."
+  },
+  "groupBy": {
+    "default": "wallet",
+    "description": "Grouping method for counterparties analysis",
+    "enum": [
+      "wallet",
+      "entity"
+    ],
+    "type": "string"
+  },
+  "orderBy": {
+    "anyOf": [
+      {
+        "enum": [
+          "interaction_count",
+          "total_volume_usd",
+          "volume_in_usd",
+          "volume_out_usd"
+        ],
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Sort field. Pass an exact value above or None for default ('total_volume_usd')."
+  },
+  "order_by_direction": {
+    "default": "DESC",
+    "enum": [
+      "ASC",
+      "DESC",
+      "asc",
+      "desc"
+    ],
+    "type": "string"
+  },
+  "page": {
+    "default": 1,
+    "type": "integer"
+  },
+  "sourceInput": {
+    "default": "Combined",
+    "description": "Source input type for counterparties analysis",
+    "enum": [
+      "Combined",
+      "Tokens",
+      "ETH"
+    ],
+    "type": "string"
+  },
+  "timeRange": {
+    "description": "Date range for counterparties analysis. Max window: 365 days — longer ranges are clamped to the most recent year (prevents timeouts in fast/expert mode) and the effective range is reported in the response. Prefer relative tokens (7D_AGO, 30D_AGO, 90D_AGO, 1Y_AGO).",
+    "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"
+  }
+}

addedInput schema / properties / request / required
```
Added value: +[
+  "timeRange"
+]
```
addedInput schema / properties / request / type
```
Added value: +"object"
```

Changed1 schema field changedMay 29, 2026

changedInput schema / properties / request / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "description": "Complete request for address counterparties (flattened).",
-    "properties": {
-      "address": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Single wallet address to analyze. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
-      },
-      "addresses": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "List of wallet addresses to analyze. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
-      },
-      "chain": {
-        "default": "all",
-        "type": "string"
-      },
-      "entity_id": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). REQUIRED if addresses is not provided. Cannot be used together with addresses."
-      },
-      "groupBy": {
-        "default": "wallet",
-        "description": "Grouping method for counterparties analysis",
-        "enum": [
-          "wallet",
-          "entity"
-        ],
-        "type": "string"
-      },
-      "order_by": {
-        "default": "total_volume_usd",
-        "type": "string"
-      },
-      "order_by_direction": {
-        "default": "desc",
-        "enum": [
-          "asc",
-          "desc",
-          "ASC",
-          "DESC"
-        ],
-        "type": "string"
-      },
-      "page": {
-        "default": 1,
-        "type": "integer"
-      },
-      "sourceInput": {
-        "default": "Combined",
-        "description": "Source input type for counterparties analysis",
-        "enum": [
-          "Combined",
-          "Tokens",
-          "ETH"
-        ],
-        "type": "string"
-      },
-      "timeRange": {
-        "description": "Date range for counterparties analysis. Max window: 365 days — longer ranges are clamped to the most recent year (prevents timeouts in fast/expert mode) and the effective range is reported in the response. Prefer relative tokens (7D_AGO, 30D_AGO, 90D_AGO, 1Y_AGO).",
-        "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"
-      }
-    },
-    "required": [
-      "timeRange"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  {
+    "description": "Complete request for address counterparties (flattened).",
+    "properties": {
+      "address": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Single wallet address to analyze. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
+      },
+      "addresses": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "List of wallet addresses to analyze. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
+      },
+      "chain": {
+        "default": "all",
+        "type": "string"
+      },
+      "entity_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). REQUIRED if addresses is not provided. Cannot be used together with addresses."
+      },
+      "groupBy": {
+        "default": "wallet",
+        "description": "Grouping method for counterparties analysis",
+        "enum": [
+          "wallet",
+          "entity"
+        ],
+        "type": "string"
+      },
+      "orderBy": {
+        "anyOf": [
+          {
+            "enum": [
+              "interaction_count",
+              "total_volume_usd",
+              "volume_in_usd",
+              "volume_out_usd"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Sort field. Pass an exact value above or None for default ('total_volume_usd')."
+      },
+      "order_by_direction": {
+        "default": "DESC",
+        "enum": [
+          "ASC",
+          "DESC",
+          "asc",
+          "desc"
+        ],
+        "type": "string"
+      },
+      "page": {
+        "default": 1,
+        "type": "integer"
+      },
+      "sourceInput": {
+        "default": "Combined",
+        "description": "Source input type for counterparties analysis",
+        "enum": [
+          "Combined",
+          "Tokens",
+          "ETH"
+        ],
+        "type": "string"
+      },
+      "timeRange": {
+        "description": "Date range for counterparties analysis. Max window: 365 days — longer ranges are clamped to the most recent year (prevents timeouts in fast/expert mode) and the effective range is reported in the response. Prefer relative tokens (7D_AGO, 30D_AGO, 90D_AGO, 1Y_AGO).",
+        "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"
+      }
+    },
+    "required": [
+      "timeRange"
+    ],
+    "type": "object"
+  }
+]

Changed3 schema fields changedMay 19, 2026

removedInput schema / $defs

Removed value: -{
-  "AddressCounterpartiesRequest": {
-    "description": "Complete request for address counterparties (flattened).",
-    "properties": {
-      "address": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Single wallet address to analyze. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
-      },
-      "addresses": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "List of wallet addresses to analyze. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
-      },
-      "chain": {
-        "default": "all",
-        "type": "string"
-      },
-      "entity_id": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). REQUIRED if addresses is not provided. Cannot be used together with addresses."
-      },
-      "groupBy": {
-        "$ref": "#/$defs/GroupBy",
-        "default": "wallet",
-        "description": "Grouping method for counterparties analysis"
-      },
-      "order_by": {
-        "default": "total_volume_usd",
-        "type": "string"
-      },
-      "order_by_direction": {
-        "default": "desc",
-        "enum": [
-          "asc",
-          "desc",
-          "ASC",
-          "DESC"
-        ],
-        "type": "string"
-      },
-      "page": {
-        "default": 1,
-        "type": "integer"
-      },
-      "sourceInput": {
-        "$ref": "#/$defs/SourceInput",
-        "default": "Combined",
-        "description": "Source input type for counterparties analysis"
-      },
-      "timeRange": {
-        "$ref": "#/$defs/DateRange",
-        "description": "Date range for counterparties analysis. Max window: 365 days — longer ranges are clamped to the most recent year (prevents timeouts in fast/expert mode) and the effective range is reported in the response. Prefer relative tokens (7D_AGO, 30D_AGO, 90D_AGO, 1Y_AGO)."
-      }
-    },
-    "required": [
-      "timeRange"
-    ],
-    "type": "object"
-  },
-  "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"
-  },
-  "GroupBy": {
-    "description": "Grouping methods for counterparties analysis.",
-    "enum": [
-      "wallet",
-      "entity"
-    ],
-    "type": "string"
-  },
-  "SourceInput": {
-    "description": "Source input types for counterparties analysis.",
-    "enum": [
-      "Combined",
-      "Tokens",
-      "ETH"
-    ],
-    "type": "string"
-  }
-}

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

changedInput schema / properties / request / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "$ref": "#/$defs/AddressCounterpartiesRequest"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  {
+    "description": "Complete request for address counterparties (flattened).",
+    "properties": {
+      "address": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Single wallet address to analyze. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
+      },
+      "addresses": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "List of wallet addresses to analyze. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
+      },
+      "chain": {
+        "default": "all",
+        "type": "string"
+      },
+      "entity_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). REQUIRED if addresses is not provided. Cannot be used together with addresses."
+      },
+      "groupBy": {
+        "default": "wallet",
+        "description": "Grouping method for counterparties analysis",
+        "enum": [
+          "wallet",
+          "entity"
+        ],
+        "type": "string"
+      },
+      "order_by": {
+        "default": "total_volume_usd",
+        "type": "string"
+      },
+      "order_by_direction": {
+        "default": "desc",
+        "enum": [
+          "asc",
+          "desc",
+          "ASC",
+          "DESC"
+        ],
+        "type": "string"
+      },
+      "page": {
+        "default": 1,
+        "type": "integer"
+      },
+      "sourceInput": {
+        "default": "Combined",
+        "description": "Source input type for counterparties analysis",
+        "enum": [
+          "Combined",
+          "Tokens",
+          "ETH"
+        ],
+        "type": "string"
+      },
+      "timeRange": {
+        "description": "Date range for counterparties analysis. Max window: 365 days — longer ranges are clamped to the most recent year (prevents timeouts in fast/expert mode) and the effective range is reported in the response. Prefer relative tokens (7D_AGO, 30D_AGO, 90D_AGO, 1Y_AGO).",
+        "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"
+      }
+    },
+    "required": [
+      "timeRange"
+    ],
+    "type": "object"
+  }
+]

Changed2 schema fields changedMay 19, 2026

addedInput schema / $defs / AddressCounterpartiesRequest / properties / address

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Single wallet address to analyze. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
+}

changedInput schema / $defs / AddressCounterpartiesRequest / properties / order_by / default
```
Previous value: -"usdNetflow"New value: +"total_volume_usd"
```

Changed1 schema field changedApr 24, 2026

changedInput schema / $defs / AddressCounterpartiesRequest / properties / timeRange / description

Previous value: -"Date range for counterparties analysis"New value: +"Date range for counterparties analysis. Max window: 365 days — longer ranges are clamped to the most recent year (prevents timeouts in fast/expert mode) and the effective range is reported in the response. Prefer relative tokens (7D_AGO, 30D_AGO, 90D_AGO, 1Y_AGO)."

First observedFeb 18, 2026

TDQS

Score is being calculated.

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?