nansen-cli 1.38.0 → 1.40.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 1.40.0
+
+### Minor Changes
+
+- [#509](https://github.com/nansen-ai/nansen-cli/pull/509) [`430c300`](https://github.com/nansen-ai/nansen-cli/commit/430c3003d28a44bd1bfb123eef9290a7350a7e1e) Thanks [@kome12](https://github.com/kome12)! - `trade execute` now revokes an existing on-chain ERC-20 allowance before
+  re-approving when it is more than 10x the current trade's scoped amount, such
+  as a legacy unlimited approval or an allowance granted by another app. Most
+  trades are unaffected. Opt out with `--no-revoke-excessive-allowance`.
+
+  After each revoke or reapproval, the CLI reads the resulting allowance back
+  on-chain and fails closed (instead of proceeding to the swap) if it doesn't
+  match what was expected or can't be read.
+
+### Patch Changes
+
+- [#498](https://github.com/nansen-ai/nansen-cli/pull/498) [`a964dd1`](https://github.com/nansen-ai/nansen-cli/commit/a964dd19c826f5231d2651547212d8169a74e7fe) Thanks [@crazywriter1](https://github.com/crazywriter1)! - Use `pending` nonce block tag for EVM sends: back-to-back transfers no longer risk reusing the same nonce when mempool transactions are queued.
+
+- [#493](https://github.com/nansen-ai/nansen-cli/pull/493) [`bc89fef`](https://github.com/nansen-ai/nansen-cli/commit/bc89fef74489da3df32a12079effbdfa899373fd) Thanks [@crazywriter1](https://github.com/crazywriter1)! - Validate `--slippage-bps` on `limit-order create`: values outside 0-10000 now fail with a clear error before any auth/API call.
+
+## 1.39.0
+
+### Minor Changes
+
+- [#495](https://github.com/nansen-ai/nansen-cli/pull/495) [`3306897`](https://github.com/nansen-ai/nansen-cli/commit/3306897c1aaae594f4401fd4656b2451ab375d78) Thanks [@kome12](https://github.com/kome12)! - Add EVM swap-outcome verification to `trade execute`. Before broadcasting a swap on an EVM chain (Base), the CLI now simulates the transaction and confirms the wallet's balance changes match the quote — the input is spent within your maximum, at least the expected output is received, and no other token or NFT leaves the wallet — refusing to sign when they don't. This runs on top of the existing pre-broadcast checks and needs a simulation-capable RPC (`NANSEN_BASE_SIM_RPC`); when none is available it degrades with a warning rather than blocking the trade. Skip it with `--no-verify-outcome`. Solana is unaffected.
+
+### Patch Changes
+
+- [#495](https://github.com/nansen-ai/nansen-cli/pull/495) [`e8cf217`](https://github.com/nansen-ai/nansen-cli/commit/e8cf217feaa9e7c8f68f4f3c3c2a49adcda07101) Thanks [@kome12](https://github.com/kome12)! - Harden swap-outcome verification error handling: a revert reported by the simulation endpoint as a top-level JSON-RPC error (rather than a per-call status) now fails closed (blocks the swap) instead of degrading, and a non-2xx simulation response (e.g. HTTP 401 "Invalid API key") now degrades with the real status and message instead of a misleading "returned no call result" warning.
+
+- [#499](https://github.com/nansen-ai/nansen-cli/pull/499) [`de0bcc5`](https://github.com/nansen-ai/nansen-cli/commit/de0bcc562bcd20a80edd3ab2f486870b80629c83) Thanks [@gulshngill](https://github.com/gulshngill)! - Fix `profiler labels`: call `/api/v1/profiler/address/labels` with its v1 request body — the beta endpoint previously used was removed from the Nansen API. `profiler batch --include labels` now returns the label array itself instead of the raw `{pagination, data}` envelope.
+
+- [#506](https://github.com/nansen-ai/nansen-cli/pull/506) [`f407edb`](https://github.com/nansen-ai/nansen-cli/commit/f407edb19444d6b5a1a631d29b4c4fb9bd280708) Thanks [@gulshngill](https://github.com/gulshngill)! - Add a canonical MCP setup section to the README — endpoint `https://mcp.nansen.ai/ra/mcp`, `NANSEN-API-KEY` auth, per-client setup paths for Claude Code, Claude Tag, and generic or stdio-only clients, plus a pointer to the connection docs for Claude Desktop and Cursor — and point the out-of-credits and low-credit warnings at the credits tab of the billing page, `app.nansen.ai/api?tab=api`, instead of the bare `app.nansen.ai/api`.
+
+- [#500](https://github.com/nansen-ai/nansen-cli/pull/500) [`9ccf8a2`](https://github.com/nansen-ai/nansen-cli/commit/9ccf8a20841a9ca01a2627ccf5de2575bf016a46) Thanks [@gulshngill](https://github.com/gulshngill)! - Document global pagination options in `nansen schema`.
+
 ## 1.38.0
 
 ### Minor Changes

package/README.md

@@ -51,6 +51,61 @@ nansen schema [command] [--pretty]    # full command reference (no API key neede
 
 Run `nansen schema --pretty` for the full subcommand and field reference.
 
+## MCP
+
+Connect any MCP client to Nansen's streamable HTTP server:
+
+- **Endpoint:** `https://mcp.nansen.ai/ra/mcp`
+- **Authentication:** `NANSEN-API-KEY` header
+- **API key:** [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/agent-setup)
+
+**Claude Desktop and Cursor:** setup instructions for both — the Claude Desktop `.dxt` bundle and the Cursor install deep link — are in the connection docs: [docs.nansen.ai/mcp/connecting](https://docs.nansen.ai/mcp/connecting).
+
+**One-command (Claude Code):**
+
+```bash
+claude mcp add --transport http nansen https://mcp.nansen.ai/ra/mcp --header "NANSEN-API-KEY: <your-key>"
+```
+
+**Manual (any streamable-HTTP client):** for example, add this to Cursor's `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "nansen": {
+      "url": "https://mcp.nansen.ai/ra/mcp",
+      "headers": {
+        "NANSEN-API-KEY": "<your-key>"
+      }
+    }
+  }
+}
+```
+
+**Manual (stdio-only clients):** use `mcp-remote` as a bridge. Keep the header as one argument with no space after the colon:
+
+```json
+{
+  "mcpServers": {
+    "nansen": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "https://mcp.nansen.ai/ra/mcp",
+        "--header",
+        "NANSEN-API-KEY:${NANSEN_API_KEY}"
+      ],
+      "env": {
+        "NANSEN_API_KEY": "<your-key>"
+      }
+    }
+  }
+}
+```
+
+**Claude Tag (Claude in Slack):** an admin must attach a plugin whose `.mcp.json` points at `https://mcp.nansen.ai/ra/mcp` and add a custom credential allowing the host `mcp.nansen.ai`. See the [Claude Tag custom-connections documentation](https://claude.com/docs/claude-tag/admins/connections/custom). Per-user fallback: use Claude Code or Claude Desktop.
+
 ## Trading
 
 DEX swaps on `solana` and `base`. Two-step: quote then execute.
@@ -216,7 +271,7 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
 
 | Code | Action |
 |------|--------|
-| `CREDITS_EXHAUSTED` | Stop all API calls immediately. `details.credits.remaining` is your actual balance. Top up at [app.nansen.ai/api](https://app.nansen.ai/api). |
+| `CREDITS_EXHAUSTED` | Stop all API calls immediately. `details.credits.remaining` is your actual balance. Top up at [app.nansen.ai/api?tab=api](https://app.nansen.ai/api?tab=api). |
 | `UNAUTHORIZED` | Wrong or missing key. Re-auth. |
 | `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
 | `UNSUPPORTED_FILTER` | Remove the filter and retry. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.38.0",
+  "version": "1.40.0",
   "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
   "main": "src/index.js",
   "type": "module",

package/skills/nansen-wallet-batch/SKILL.md

@@ -19,7 +19,7 @@ allowed-tools: Bash(nansen:*)
 ADDRESSES="0xaddr1,0xaddr2,0xaddr3,..." CHAIN=ethereum
 nansen research profiler batch --addresses "$ADDRESSES" --chain $CHAIN --include labels,balance
 # → .data.{total, completed, results[]: {address, chain, labels[], balance, error}}
-# labels[]: {label, category ("smart_money","fund","social","behavioral","others"), fullname}
+# labels[]: {label, category ("smart_money","fund","social","behavioral","others"), kind[]}
 # balance: {data[]: {token_symbol, token_amount, price_usd, value_usd}}
 ```
 Check .error per result — invalid addresses return an error message, not a crash. Skip those.

package/skills/nansen-wallet-profiler/SKILL.md

@@ -92,7 +92,7 @@ nansen research profiler compare --addresses "0xabc,0xdef" --chain ethereum
 
 - `pnl-summary` has no pagination support (returns aggregate stats, not a list).
 - `perp-positions` has no pagination support.
-- `labels` has no pagination support — the API ignores `per_page` and always returns all labels for the address. `--limit` is not available for this sub-command.
+- `labels` supports pagination — `--limit`/`--page` are honoured and the response is `{pagination: {page, per_page, is_last_page}, data[]: {label, category, kind[]}}`.
 - `transactions` caps at per_page=100 (API limit).
 - `trace` makes many API calls — use `--width` conservatively.
 - `batch` accepts `--file <path>` with one address per line as alternative to `--addresses`.

package/src/api.js

@@ -393,7 +393,7 @@ function requireValidToken(tokenAddress, chain) {
   if (!v.valid) throw new NansenError(v.error, v.code);
 }
 
-function loadConfig() {
+export function loadConfig() {
   // Base config from files, then env vars override individual fields
   let config = null;
 
@@ -908,8 +908,9 @@ export class NansenAPI {
   async addressLabels(params = {}) {
     const { address, chain = 'ethereum', pagination = { page: 1, per_page: 100 } } = params;
     if (address) requireValidAddress(address, chain);
-    return this.request('/api/beta/profiler/address/labels', {
-      parameters: { address, chain },
+    return this.request('/api/v1/profiler/address/labels', {
+      address,
+      chain,
       pagination
     });
   }

package/src/cli.js

@@ -190,7 +190,7 @@ export function parseArgs(args) {
       const key = arg.slice(2);
       const next = args[i + 1];
       
-      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full' || key === 'human' || key === 'enabled' || key === 'disabled' || key === 'expert' || key === 'json' || key === 'offline') {
+      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full' || key === 'human' || key === 'enabled' || key === 'disabled' || key === 'expert' || key === 'json' || key === 'offline' || key === 'no-simulate' || key === 'no-verify-outcome' || key === 'no-revoke-excessive-allowance') {
         result.flags[key] = true;
       } else if (next && (!next.startsWith('-') || /^-\d/.test(next))) {
         // Try to parse as JSON first (for objects/arrays/booleans),
@@ -489,7 +489,9 @@ async function enrichTransfers(result, apiInstance, chain) {
   for (const addr of addrs) {
     try {
       const labelsResult = await apiInstance.addressLabels({ address: addr, chain });
-      labelMap[addr] = labelsResult?.labels || labelsResult?.data?.results || [];
+      labelMap[addr] = Array.isArray(labelsResult?.data)
+        ? labelsResult.data.map(item => item.label)
+        : labelsResult?.labels || [];
     } catch {
       labelMap[addr] = [];
     }
@@ -568,7 +570,10 @@ export async function batchProfile(api, params = {}) {
     }
     try {
       if (include.includes('labels')) {
-        entry.labels = await api.addressLabels({ address, chain });
+        const labelsResult = await api.addressLabels({ address, chain });
+        entry.labels = Array.isArray(labelsResult?.data)
+          ? labelsResult.data
+          : labelsResult?.labels || [];
       }
       if (include.includes('balance')) {
         entry.balance = await api.addressBalance({ address, chain });

package/src/limit-order.js

@@ -401,6 +401,17 @@ export function parseExpiry(expiryStr) {
   throw new Error(`Invalid expiry format: "${expiryStr}". Use "24h", "7d", "30d", or epoch ms.`);
 }
 
+// Whole integer bps in [0, 10000], matching bridge parseSlippageBps.
+// Number() would accept "1.5", "1e2", "0x10", and boolean true.
+function parseSlippageBps(raw) {
+  const s = String(raw).trim();
+  const bad = 'Error: --slippage-bps must be a whole integer between 0 and 10000 basis points.';
+  if (!/^\d+$/.test(s)) throw new Error(bad);
+  const n = parseInt(s, 10);
+  if (!Number.isInteger(n) || n < 0 || n > 10000) throw new Error(bad);
+  return n;
+}
+
 // ============= Order Formatting =============
 
 function formatOrderStatus(status) {
@@ -501,7 +512,7 @@ export function buildLimitOrderCommands(deps = {}) {
       const triggerPrice = options['trigger-price'];
       const triggerCondition = options['trigger-condition'];
       const triggerMintRaw = options['trigger-mint'];
-      const slippageBps = options['slippage-bps'] != null ? Number(options['slippage-bps']) : undefined;
+      const slippageBpsRaw = options['slippage-bps'];
       const expiresStr = options.expires || '30d';
       const walletName = options.wallet;
 
@@ -516,7 +527,7 @@ OPTIONS:
   --trigger-mint <symbol|addr>   Token whose price triggers the order (e.g. SOL)
   --trigger-condition <cond>     "above" or "below"
   --trigger-price <usd>          Trigger price in USD (must be a positive number)
-  --slippage-bps <bps>               Slippage in basis points (100 = 1%), omit for auto
+  --slippage-bps <bps>           Whole integer bps, 0-10000 (100 = 1%), omit for auto
   --expires <duration>           Expiry duration: "24h", "7d", "30d" (default: 30d)
   --wallet <name>                Wallet name (or "walletconnect"/"wc")
 
@@ -581,6 +592,18 @@ EXAMPLES:
         return;
       }
 
+      // Same bounds as update / bridge: whole-integer bps in 0–10000.
+      let slippageBps;
+      if (slippageBpsRaw != null) {
+        try {
+          slippageBps = parseSlippageBps(slippageBpsRaw);
+        } catch (err) {
+          log(err.message);
+          exit(1);
+          return;
+        }
+      }
+
       let expiresAt;
       try {
         expiresAt = parseExpiry(expiresStr);
@@ -820,7 +843,7 @@ Usage: nansen trade limit-order update --order <orderId> [--trigger-price <usd>]
 OPTIONS:
   --order <id>            Order ID to update
   --trigger-price <usd>   New trigger price in USD
-  --slippage-bps <bps>    Slippage in basis points (100 = 1%)
+  --slippage-bps <bps>    Whole integer bps, 0-10000 (100 = 1%)
   --wallet <name>         Wallet name (or "walletconnect"/"wc")
 
 NOTE: Only provided fields are updated. Auto slippage can only be set at creation time
@@ -850,13 +873,13 @@ EXAMPLES:
         updateBody.triggerPriceUsd = price;
       }
       if (slippageBps != null) {
-        const bps = Number(slippageBps);
-        if (isNaN(bps) || bps < 0 || bps > 10000) {
-          log('Error: --slippage-bps must be between 0 and 10000 basis points.');
+        try {
+          updateBody.slippageBps = parseSlippageBps(slippageBps);
+        } catch (err) {
+          log(err.message);
           exit(1);
           return;
         }
-        updateBody.slippageBps = bps;
       }
 
       try {

package/src/response-meta.js

@@ -118,12 +118,12 @@ export function creditWarning(meta) {
   const { used, remaining, cost } = credits;
   if (remaining === null) return null;
   if (remaining === 0) {
-    return '⚠️  Out of API credits. Top up at https://app.nansen.ai/api';
+    return '⚠️  Out of API credits. Top up at https://app.nansen.ai/api?tab=api';
   }
   // The cost header is the authoritative charge; used is the fallback.
   const charged = cost ?? used;
   if (charged !== null && charged > 0 && remaining < charged) {
-    return `⚠️  ${remaining} API credit${remaining === 1 ? '' : 's'} left — less than this call cost (${charged}). Top up at https://app.nansen.ai/api`;
+    return `⚠️  ${remaining} API credit${remaining === 1 ? '' : 's'} left — less than this call cost (${charged}). Top up at https://app.nansen.ai/api?tab=api`;
   }
   return null;
 }

package/src/rpc-urls.js

@@ -11,6 +11,23 @@
  *   NANSEN_BSC_RPC        Custom BNB Smart Chain RPC
  *   NANSEN_XLAYER_RPC     Custom X Layer RPC
  *   NANSEN_SOLANA_RPC     Custom Solana RPC
+ *   NANSEN_BASE_SIM_RPC   Custom Base simulation RPC (see SIMULATION_RPCS below)
+ *
+ * Simulation RPCs (SIMULATION_RPCS) are a SEPARATE registry from the cheap
+ * defaults above. Swap-outcome verification (src/swap-simulation.js) needs an
+ * endpoint that supports state-changing simulation with asset-transfer tracing
+ * (`eth_simulateV1` / `debug_traceCall`), which the free public defaults in
+ * CHAIN_RPCS deliberately DISABLE. Keeping the two registries apart means only
+ * the (pricey) simulation calls hit the trace-capable endpoint; ordinary reads
+ * (nonce, balance, allowance, eth_call revert check) stay on the cheap default.
+ *
+ * The shipped simulation endpoint is a Nansen-hosted service authenticated with
+ * the user's existing Nansen API key (no secret in this public package): the
+ * trace-capable upstream is reached server-side, so the baked default carries no
+ * credential. With no NANSEN_BASE_SIM_RPC override, swap-outcome verification
+ * uses this default; if the service is ever unreachable it degrades with a
+ * warning rather than blocking the trade. To use your own endpoint (or for local
+ * dev/e2e), point NANSEN_BASE_SIM_RPC at any trace-capable RPC in a gitignored .env.
  *
  * Backward-compat aliases (deprecated — prefer the forms above):
  *   NANSEN_RPC_BASE       Old name for NANSEN_BASE_RPC; trading.js previously read this
@@ -40,3 +57,53 @@ export const CHAIN_RPCS = {
   polygon:  process.env.NANSEN_POLYGON_RPC  || DEFAULT_POLYGON_RPC,
   bnb:      process.env.NANSEN_BNB_RPC      || DEFAULT_BNB_RPC,
 };
+
+// Zero-config default for the shipped Nansen-hosted simulation endpoint. It
+// authenticates with the user's existing Nansen API key (attached automatically
+// by swap-simulation.js), and the trace-capable upstream is reached server-side —
+// so this URL carries no secret and is safe to bake into a public package. Never
+// embed an RPC URL that carries an inline token here; any embedded secret would
+// leak on publish.
+const DEFAULT_BASE_SIM_RPC = 'https://api.nansen.ai/api/v1/trade/simulate-swap';
+
+// Separate registry for swap-outcome simulation (src/swap-simulation.js). These
+// endpoints must support state-changing simulation with asset-transfer tracing
+// (`eth_simulateV1` / `debug_traceCall`), which the CHAIN_RPCS public defaults
+// disable. Only outcome verification reads this registry; every other RPC call
+// stays on the cheap CHAIN_RPCS default. A null entry (no baked default and no
+// override) signals "no sim-capable endpoint" to the caller, which degrades.
+//
+// Intentionally a mutable export: unit tests override an entry in-place (e.g.
+// `SIMULATION_RPCS.base = ...`) to point at a mock or to null out the endpoint,
+// restoring it in afterEach. Runtime code only ever reads it.
+export const SIMULATION_RPCS = {
+  base: process.env.NANSEN_BASE_SIM_RPC || DEFAULT_BASE_SIM_RPC,
+};
+
+// Nansen hosts the API key may be forwarded to. Kept to an explicit allowlist
+// (not a `*.nansen.ai` wildcard): the key only ever authenticates the sim proxy
+// on api.nansen.ai, and a wildcard would forward it to any subdomain that
+// resolves — including a misconfigured or compromised one. Add new sim hosts
+// here deliberately if one is ever introduced.
+const NANSEN_HOSTED_SIM_HOSTS = new Set(['api.nansen.ai']);
+
+/**
+ * Whether a simulation URL is a Nansen-hosted endpoint that may receive the
+ * user's Nansen API key. The key authenticates the shipped default proxy
+ * (DEFAULT_BASE_SIM_RPC); a NANSEN_BASE_SIM_RPC override can point at ANY host
+ * (dev node, third-party trace RPC), and forwarding the credential there would
+ * leak it. So the key is attached ONLY when this returns true — every other
+ * endpoint is called anonymously.
+ *
+ * Trust is: https + hostname is one of NANSEN_HOSTED_SIM_HOSTS. Anything else
+ * (http, other host, unparseable) is untrusted and gets no key.
+ */
+export function isNansenHostedUrl(url) {
+  try {
+    const u = new URL(url);
+    if (u.protocol !== 'https:') return false;
+    return NANSEN_HOSTED_SIM_HOSTS.has(u.hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}

package/src/schema.json

@@ -1620,7 +1620,15 @@
             },
             "no-simulate": {
               "type": "boolean",
-              "description": "Skip the pre-broadcast simulation."
+              "description": "Skip the pre-broadcast simulation (the eth_call revert check)."
+            },
+            "no-verify-outcome": {
+              "type": "boolean",
+              "description": "Skip EVM swap-outcome verification. That check simulates the swap and confirms the wallet's balance changes match the quote (input spent within your max, expected output received, no other token moved) before broadcasting; it needs a simulation-capable endpoint (NANSEN_BASE_SIM_RPC) and degrades with a warning when none is available. No effect on Solana."
+            },
+            "no-revoke-excessive-allowance": {
+              "type": "boolean",
+              "description": "Skip revoking an existing on-chain ERC-20 allowance before re-approving when it exceeds 10x this trade's scoped amount. By default, an oversized or legacy allowance is revoked to zero and a fresh trade-scoped allowance is granted. WalletConnect users will see separate wallet prompts for the revoke and re-approval."
             }
           }
         },
@@ -1686,7 +1694,7 @@
                 },
                 "slippage-bps": {
                   "type": "number",
-                  "description": "Slippage tolerance in basis points (e.g. 50 = 0.5%)"
+                  "description": "Slippage as a whole integer in basis points, 0-10000 (50 = 0.5%), omit for auto"
                 },
                 "expires": {
                   "type": "string",
@@ -1775,7 +1783,7 @@
                 },
                 "slippage-bps": {
                   "type": "number",
-                  "description": "New slippage in basis points (0-10000)"
+                  "description": "New slippage as a whole integer in basis points (0-10000)"
                 },
                 "wallet": {
                   "type": "string",
@@ -1968,6 +1976,15 @@
       "type": "string",
       "description": "Comma-separated list of fields to include in output"
     },
+    "limit": {
+      "type": "number",
+      "description": "Maximum results per page for list-returning research commands; maps to pagination.per_page. General endpoints default to 10 (max 1000), while profiler address endpoints default to 20 (max 100). Supported by smart-money, profiler, token, perp, points, prediction-market, and supported research historical-* commands. Commands that declare their own limit option (search, token top-tokens, trade limit-order list) use those command-specific semantics instead; token ohlcv, profiler perp-positions, and historical-token-flow-summary do not support pagination. profiler labels defaults to 100 when omitted."
+    },
+    "page": {
+      "type": "number",
+      "default": 1,
+      "description": "1-based page number for list-returning research commands; maps to pagination.page. Supported by smart-money, profiler, token, perp, points, prediction-market, and supported research historical-* commands. Trade, wallet, and operational commands ignore it; token ohlcv, profiler perp-positions, and historical-token-flow-summary do not support pagination. profiler labels defaults to page 1 when omitted."
+    },
     "no-retry": {
       "type": "boolean",
       "description": "Disable automatic retry on rate limits/errors"