Nansen

by io.github.hurcanNansen

Overview Discussions Admin

Loading portfolio data

address_portfolio

Read-only

Get comprehensive portfolio overview for a wallet address or entity.

Hyperliquid perpetual positions include liquidation prices to support risk analysis workflows.

For wallet addresses, supports different modes:

'fast-mode-default': Wallet balances + Hyperliquid positions (skip defi, for fast mode only)
'all': Wallet balances + DeFi positions + Hyperliquid positions
'wallet_balances': Only token balances (tokens and native coins across all chains)
'defi': Only DeFi positions (lending, staking, LP tokens, etc., excluding Hyperliquid)
'hyperliquid': Only Hyperliquid data — perp positions (with liquidation prices and margin summary) plus HL spot wallet balances

For entities (e.g., "Binance", "Paradigm Fund"), only on-chain token balances are returned, aggregated across all addresses associated with the entity.

This tool provides flexible portfolio analysis in a single request, allowing users to focus on specific aspects of their holdings.

The output is pre-formatted markdown that should be presented exactly as returned, preserving all tables, sections, and formatting without reinterpretation.

Example Usage: Get full comprehensive portfolio for a wallet: { "walletAddress": "0x28c6c06298d514db089934071355e5743bf21d60", "mode": "all" }

Get only DeFi positions (returns raw JSON):
```
{
    "walletAddress": "0x28c6c06298d514db089934071355e5743bf21d60",
    "mode": "defi"
}
```

Get only Hyperliquid positions (returns raw JSON):
```
{
    "walletAddress": "0x28c6c06298d514db089934071355e5743bf21d60",
    "mode": "hyperliquid"
}
```

Get token balances for an entity:
```
{
    "entity_id": "Binance"
}
```

Input Schema

Name	Required	Description	Default
`request`	Yes	Complete request for Address Portfolio endpoint (flattened). IMPORTANT: Exactly one of 'wallet_address' or 'entity_id' must be provided (not both, not neither).

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 28, 2026

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

removedInput schema / properties / request / anyOf

Removed value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "description": "Complete request for Address Portfolio endpoint (flattened).\n\nIMPORTANT: Exactly one of 'wallet_address' or 'entity_id' must be provided (not both, not neither).",
-    "properties": {
-      "chain": {
-        "default": "all",
-        "type": "string"
-      },
-      "entity_id": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). For entities, only token balances are returned. REQUIRED if wallet_address is not provided. Cannot be used together with wallet_address."
-      },
-      "mode": {
-        "default": "fast-mode-default",
-        "description": "Portfolio mode: 'fast-mode-default' (default - wallet_balances + hyperliquid), 'all' (wallet_balances + defi + hyperliquid), 'wallet_balances' (only token balances), 'defi' (only DeFi positions), 'hyperliquid' (only Hyperliquid positions)",
-        "type": "string"
-      },
-      "walletAddress": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Wallet address to analyze comprehensive portfolio for. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
-      }
-    },
-    "type": "object"
-  }
-]

addedInput schema / properties / request / description

Added value: +"Complete request for Address Portfolio endpoint (flattened).\n\nIMPORTANT: Exactly one of 'wallet_address' or 'entity_id' must be provided (not both, not neither)."

addedInput schema / properties / request / properties

Added value: +{
+  "chain": {
+    "default": "all",
+    "type": "string"
+  },
+  "entity_id": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). For entities, only token balances are returned. REQUIRED if wallet_address is not provided. Cannot be used together with wallet_address."
+  },
+  "mode": {
+    "default": "fast-mode-default",
+    "description": "Portfolio mode: 'fast-mode-default' (default - wallet_balances + hyperliquid), 'all' (wallet_balances + defi + hyperliquid), 'wallet_balances' (only token balances), 'defi' (only DeFi positions), 'hyperliquid' (only Hyperliquid positions)",
+    "type": "string"
+  },
+  "walletAddress": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Wallet address to analyze comprehensive portfolio for. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
+  }
+}

addedInput schema / properties / request / type
```
Added value: +"object"
```

Changed3 schema fields changedMay 19, 2026

removedInput schema / $defs

Removed value: -{
-  "AddressPortfolioRequest": {
-    "description": "Complete request for Address Portfolio endpoint (flattened).\n\nIMPORTANT: Exactly one of 'wallet_address' or 'entity_id' must be provided (not both, not neither).",
-    "properties": {
-      "chain": {
-        "default": "all",
-        "type": "string"
-      },
-      "entity_id": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). For entities, only token balances are returned. REQUIRED if wallet_address is not provided. Cannot be used together with wallet_address."
-      },
-      "mode": {
-        "default": "fast-mode-default",
-        "description": "Portfolio mode: 'fast-mode-default' (default - wallet_balances + hyperliquid), 'all' (wallet_balances + defi + hyperliquid), 'wallet_balances' (only token balances), 'defi' (only DeFi positions), 'hyperliquid' (only Hyperliquid positions)",
-        "type": "string"
-      },
-      "walletAddress": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Wallet address to analyze comprehensive portfolio for. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
-      }
-    },
-    "type": "object"
-  }
-}

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

changedInput schema / properties / request / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "$ref": "#/$defs/AddressPortfolioRequest"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  {
+    "description": "Complete request for Address Portfolio endpoint (flattened).\n\nIMPORTANT: Exactly one of 'wallet_address' or 'entity_id' must be provided (not both, not neither).",
+    "properties": {
+      "chain": {
+        "default": "all",
+        "type": "string"
+      },
+      "entity_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Entity name to analyze (e.g., 'Binance', 'Paradigm Fund'). For entities, only token balances are returned. REQUIRED if wallet_address is not provided. Cannot be used together with wallet_address."
+      },
+      "mode": {
+        "default": "fast-mode-default",
+        "description": "Portfolio mode: 'fast-mode-default' (default - wallet_balances + hyperliquid), 'all' (wallet_balances + defi + hyperliquid), 'wallet_balances' (only token balances), 'defi' (only DeFi positions), 'hyperliquid' (only Hyperliquid positions)",
+        "type": "string"
+      },
+      "walletAddress": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Wallet address to analyze comprehensive portfolio for. REQUIRED if entity_id is not provided. Cannot be used together with entity_id."
+      }
+    },
+    "type": "object"
+  }
+]

First observedFeb 18, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already cover readOnly/destructive/openWorld, so the description's added value is the output-handling contract: 'pre-formatted markdown that should be presented exactly as returned, preserving all tables... without reinterpretation', plus the note that entities aggregate balances across all associated addresses. This is genuinely useful non-schema behavior. It loses a point for internal inconsistency, claiming markdown output globally while examples for 'defi' and 'hyperliquid' say '(returns raw JSON)'.

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

Conciseness3/5

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

The critical behavior (markdown must be preserved verbatim) is buried mid-description after a long mode list, and the mode bullet list duplicates the schema's own mode enum almost verbatim. Filler like 'This tool provides flexible portfolio analysis in a single request, allowing users to focus on specific aspects of their holdings' adds no decision-relevant information, and the four example blocks are repetitive.

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?

With 100% schema coverage, an output schema, and nested request objects, the description covers the pieces an agent needs: mode semantics, the XOR constraint on walletAddress/entity_id, and output presentation rules. The unresolved markdown-vs-raw-JSON ambiguity across modes and the unmentioned 'chain' parameter are the remaining gaps.

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

Parameters3/5

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

Schema description coverage is 100%, and the nested request's mode and identity fields are already documented in the schema in nearly identical wording, so the description mostly restates structured data. The worked examples do add concrete invocation shapes for each mode. The 'chain' parameter (default 'all') is never mentioned in the description, leaving a small gap the schema does not fill either.

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?

States a specific verb and resource ('Get comprehensive portfolio overview') and scopes it to a wallet address or entity, with a mode breakdown that makes the returned surface concrete. It does not explicitly distinguish itself from overlapping siblings such as address_perp_positions, address_historical_balances, or address_dex_trades, so an agent cannot be certain it is the right tool for a narrower question.

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?

Each mode is explained in terms of what it includes and excludes (e.g., fast-mode-default 'skip defi, for fast mode only'; defi 'excluding Hyperliquid'), which gives the agent clear selection context. It also states the entity-vs-wallet constraint. However, it never says when to prefer a sibling tool over one of these modes, so no real exclusion guidance exists.

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?