nansen-cli 1.41.1 → 1.43.0

package/src/limit-order.js

@@ -102,12 +102,26 @@ async function loFetch(method, endpoint, { token, body, query } = {}) {
     headers['X-API-Key'] = process.env.NANSEN_API_KEY;
   }
 
-  const opts = { method, headers };
+  // Never follow a redirect on a request carrying the JWT / X-API-Key — undici
+  // forwards the custom X-API-Key header across a cross-origin redirect, leaking
+  // the key to the redirect target.
+  const opts = { method, headers, redirect: 'error' };
   if (body !== undefined) {
     opts.body = JSON.stringify(body);
   }
 
-  const res = await fetch(url.toString(), opts);
+  let res;
+  try {
+    res = await fetch(url.toString(), opts);
+  } catch (err) {
+    // redirect: 'error' rejects with a bare TypeError on any server redirect;
+    // convert it (and genuine network failures) into a coded, actionable error
+    // rather than letting an undecorated crash reach the CLI.
+    throw Object.assign(
+      new Error(`Limit order API request failed (${method} ${url.pathname}): ${err.message}`, { cause: err }),
+      { code: 'LIMIT_ORDER_NETWORK_ERROR' }
+    );
+  }
   const text = await res.text();
 
   let parsed;

package/src/mcp-verify.js

@@ -0,0 +1,292 @@
+import { check, formatChecks, maskKey, resolveAuthConfig } from './doctor.js';
+
+export const DEFAULT_MCP_URL = 'https://mcp.nansen.ai/ra/mcp';
+export const CANARY_TOOL = 'nansen_score_top_tokens';
+
+class McpRequestError extends Error {
+  constructor(message, { status = null, rpcMessage = null } = {}) {
+    super(message);
+    this.name = 'McpRequestError';
+    this.status = status;
+    this.rpcMessage = rpcMessage;
+  }
+}
+
+function responseContentType(response) {
+  return (
+    response.headers?.get?.('content-type')
+    || response.headers?.['content-type']
+    || response.headers?.['Content-Type']
+    || ''
+  ).toLowerCase();
+}
+
+function responseText(message) {
+  const content = [message?.result?.content, message?.content]
+    .filter(Array.isArray)
+    .flat()
+    .map(item => item?.text)
+    .filter(text => typeof text === 'string');
+  const error = message?.error;
+  const errorText = typeof error === 'string'
+    ? error
+    : [error?.message, error?.data].filter(value => typeof value === 'string').join(': ');
+  return [...content, errorText].filter(Boolean).join('\n');
+}
+
+function parseResponseBody(body, contentType, requestId) {
+  if (!contentType.includes('text/event-stream')) return JSON.parse(body);
+
+  for (const line of body.split(/\r?\n/)) {
+    if (!line.startsWith('data:')) continue;
+    const data = line.slice(5).trim();
+    if (!data || data === '[DONE]') continue;
+    try {
+      const message = JSON.parse(data);
+      // String compare: a proxy may re-serialize the JSON-RPC id as "1".
+      if (String(message?.id) === String(requestId)) return message;
+    } catch {
+      // Ignore non-JSON SSE data and keep looking for the JSON-RPC message.
+    }
+  }
+
+  throw new Error(`no JSON-RPC message with id ${requestId} in SSE response`);
+}
+
+/**
+ * Send one stateless MCP JSON-RPC request and parse either JSON or SSE output.
+ */
+export async function mcpRequest(url, method, params, {
+  apiKey,
+  fetchFn = fetch,
+  timeoutMs = 30_000,
+} = {}) {
+  const requestId = 1;
+  const controller = new AbortController();
+  const headers = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json, text/event-stream',
+  };
+  if (apiKey) headers['NANSEN-API-KEY'] = apiKey;
+
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  let body;
+  try {
+    response = await fetchFn(url, {
+      method: 'POST',
+      // The canary carries NANSEN-API-KEY; undici forwards that custom header
+      // across a cross-origin redirect, so refuse to follow one rather than
+      // relay the key to whatever host the (possibly non-default) server points at.
+      redirect: 'error',
+      headers,
+      signal: controller.signal,
+      body: JSON.stringify({ jsonrpc: '2.0', id: requestId, method, params }),
+    });
+    body = await response.text();
+  } finally {
+    clearTimeout(timer);
+  }
+
+  let message;
+  try {
+    message = parseResponseBody(body, responseContentType(response), requestId);
+  } catch (error) {
+    throw new McpRequestError(
+      `MCP server returned an unexpected response${response?.status ? ` (HTTP ${response.status})` : ''}: ${error.message}`,
+      { status: response?.status || null },
+    );
+  }
+
+  if (response?.status && (response.status < 200 || response.status >= 300)) {
+    throw new McpRequestError(
+      `MCP server returned HTTP ${response.status}${responseText(message) ? `: ${responseText(message)}` : ''}`,
+      { status: response.status, rpcMessage: message },
+    );
+  }
+
+  return message;
+}
+
+function errorReason(error) {
+  if (error?.name === 'AbortError') return 'timed out';
+  return error?.cause?.code || error?.message || 'request failed';
+}
+
+function errorText(error) {
+  return error?.rpcMessage ? responseText(error.rpcMessage) : error?.message || 'request failed';
+}
+
+function authFailureCheck(message, httpStatus = null) {
+  const text = responseText(message);
+  const codes = [httpStatus, message?.error?.code, message?.result?.code].filter(Boolean).join(' ');
+  const combined = `${codes} ${text}`;
+
+  // Order matters, most-specific first. Rate limit before credits: rate-limit
+  // texts often say "credit rate limit" and must stay a warn. Credits before
+  // auth: the gateway maps 403 + "insufficient"/"credit" to CREDITS_EXHAUSTED,
+  // and a zero-balance user must not be told their key was rejected — the
+  // create/rotate remedy can itself fail on key-capped plans.
+  if (/\b429\b|rate[- ]?limit|too many requests/i.test(combined)) {
+    return check(
+      'mcp-auth',
+      'warn',
+      `MCP data call was rate limited; the paid data path is not verified${text ? `: ${text}` : ''}`,
+      'Retry the verification shortly.',
+    );
+  }
+  if (/\b402\b|payment required|insufficient|credits?\b/i.test(combined)) {
+    return check(
+      'mcp-auth',
+      'error',
+      `MCP server reports insufficient credits${text ? `: ${text}` : ''}`,
+      'Top up credits or check your Nansen plan.',
+    );
+  }
+  if (/\b40[13]\b|unauthorized|forbidden|api[- ]key.*(?:required|invalid|reject)|header is required/i.test(combined)) {
+    return check(
+      'mcp-auth',
+      'error',
+      `MCP server rejected the API key${text ? `: ${text}` : ''}`,
+      'Check the exact key in your MCP client\'s NANSEN-API-KEY header, or create/rotate it at https://app.nansen.ai/api?tab=api',
+    );
+  }
+  return check(
+    'mcp-auth',
+    'error',
+    `MCP authenticated data call failed${text ? `: ${text}` : ''}`,
+    'Check the MCP server response and retry.',
+  );
+}
+
+function isRpcError(message) {
+  return Boolean(message?.error) || message?.result?.isError === true || message?.isError === true;
+}
+
+function skippedAuth(message) {
+  return check('mcp-auth', 'info', `Skipped authenticated data call: ${message}`);
+}
+
+function keySourceLabel(source) {
+  if (source === 'env') return 'NANSEN_API_KEY env var';
+  if (source === 'config') return 'config file';
+  if (source === 'dev-config') return 'development config file';
+  return '--api-key';
+}
+
+/**
+ * Run the unauthenticated reachability check and the paid authenticated canary.
+ * Every expected failure is represented as a check instead of escaping.
+ */
+export async function runMcpVerifyChecks({
+  apiKey,
+  url = DEFAULT_MCP_URL,
+  env = process.env,
+  fetchFn = fetch,
+  timeoutMs = 30_000,
+  devConfigPath,
+} = {}) {
+  const checks = [];
+  const auth = resolveAuthConfig(env, devConfigPath);
+  // An explicitly passed key — even a bogus null — must never silently fall
+  // back to the saved key: that would verify a key the caller never supplied.
+  const explicitKey = apiKey !== undefined;
+  const resolvedKey = explicitKey ? apiKey : auth.apiKey;
+  const key = typeof resolvedKey === 'string' ? resolvedKey.trim() : '';
+
+  if (key) {
+    checks.push(check('mcp-api-key', 'ok', `API key found (${maskKey(key)}, source: ${explicitKey ? '--api-key' : keySourceLabel(auth.apiKeySource)})`));
+  } else {
+    checks.push(check(
+      'mcp-api-key',
+      'error',
+      'No API key available for the authenticated MCP data-path check',
+      'Create an API key at https://app.nansen.ai/api?tab=api, then set NANSEN_API_KEY or save it with `nansen login --human`',
+    ));
+  }
+
+  if (key && url !== DEFAULT_MCP_URL) {
+    checks.push(check('mcp-url', 'warn', `Non-default MCP URL: ${url} — the API key will be sent to this host`));
+  }
+
+  let serverReady = false;
+  try {
+    const message = await mcpRequest(url, 'tools/list', {}, { fetchFn, timeoutMs });
+    if (isRpcError(message) || !Array.isArray(message?.result?.tools)) {
+      const text = responseText(message);
+      checks.push(check(
+        'mcp-server',
+        'error',
+        `MCP tools/list failed${text ? `: ${text}` : ''}`,
+        `Check the MCP server URL and network: ${url}`,
+      ));
+    } else {
+      serverReady = true;
+      checks.push(check(
+        'mcp-server',
+        'ok',
+        `MCP server reachable: tools/list returned ${message.result.tools.length} tools (unauthenticated; reachability only)`,
+      ));
+    }
+  } catch (error) {
+    checks.push(check(
+      'mcp-server',
+      'error',
+      `MCP server unreachable: ${errorReason(error)}`,
+      `Check your network/proxy or try --url ${url}`,
+    ));
+  }
+
+  if (!key) {
+    checks.push(skippedAuth('no API key was provided'));
+  } else if (!serverReady) {
+    checks.push(skippedAuth('tools/list did not establish server reachability'));
+  } else {
+    try {
+      const message = await mcpRequest(
+        url,
+        'tools/call',
+        { name: CANARY_TOOL, arguments: { request: {} } },
+        { apiKey: key, fetchFn, timeoutMs },
+      );
+      if (isRpcError(message)) {
+        checks.push(authFailureCheck(message));
+      } else if (!Array.isArray(message?.result?.content)) {
+        // A tools/call result always carries a content array; anything else
+        // (e.g. a proxy echoing an unrelated payload) must not verify the key.
+        checks.push(check(
+          'mcp-auth',
+          'error',
+          'MCP data call returned a malformed tools/call result — the key is not verified',
+          `Check the MCP server URL: ${url}`,
+        ));
+      } else {
+        checks.push(check(
+          'mcp-auth',
+          'ok',
+          'Authenticated MCP data call succeeded (~1 credit consumed).',
+        ));
+      }
+    } catch (error) {
+      const text = errorText(error);
+      const message = error.rpcMessage || (error.status ? { error: { message: text } } : null);
+      checks.push(message
+        ? authFailureCheck(message, error.status)
+        : check('mcp-auth', 'error', `MCP authenticated data call failed: ${errorReason(error)}`, 'Check your network/proxy or try the verification again.'));
+    }
+  }
+
+  return checks;
+}
+
+export function formatMcpVerifyReport(checks, url, verified) {
+  const lines = [`Nansen MCP verify — ${url}`, '', formatChecks(checks), ''];
+  if (verified) {
+    lines.push('Verified: the supplied API key works against the MCP server\'s paid data path (~1 credit consumed). Ensure this same key is in your client\'s NANSEN-API-KEY header.');
+  } else {
+    const errors = checks.filter(item => item.status === 'error').length;
+    const warnings = checks.filter(item => item.status === 'warn').length;
+    lines.push(`${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'} found; MCP setup is not verified.`);
+  }
+  return lines.join('\n');
+}

package/src/privy.js

@@ -10,6 +10,7 @@ import fs from "fs";
 import path from "path";
 import { parsePaymentRequirements } from "./x402.js";
 import { isEvmNetwork } from "./x402-evm.js";
+import { evaluatePaymentRequirement, resolvePaymentAmount, resolvePayTo } from "./x402-policy.js";
 import {
   isSvmNetwork,
   getSolanaRpcUrl,
@@ -49,10 +50,20 @@ export class PrivyClient {
       "Content-Type": "application/json",
     };
 
-    const opts = { method, headers };
+    // Never follow a redirect on a request carrying Basic auth / privy-app-id —
+    // a redirect target could otherwise be handed the app credentials.
+    const opts = { method, headers, redirect: "error" };
     if (body) opts.body = JSON.stringify(body);
 
-    const response = await fetch(`${this.baseUrl}${endpoint}`, opts);
+    let response;
+    try {
+      response = await fetch(`${this.baseUrl}${endpoint}`, opts);
+    } catch (err) {
+      // redirect: 'error' rejects with a bare TypeError on any server redirect;
+      // convert it (and genuine network failures) into an actionable message
+      // rather than surfacing an undecorated crash.
+      throw new Error(`Privy API request failed (${method} ${endpoint}): ${err.message}. If PRIVY_* points at a proxy that redirects, use the direct api.privy.io base URL.`, { cause: err });
+    }
 
     if (!response.ok) {
       let msg = `Privy API error: ${response.status}`;
@@ -287,6 +298,11 @@ export async function* createPrivyPaymentSignatures(response, url) {
     const evmWallet = await getPrivyEvmWallet(client);
     if (evmWallet) {
       for (const requirement of evmRequirements) {
+        const decision = evaluatePaymentRequirement(requirement);
+        if (!decision.ok) {
+          console.error(`[x402] ${decision.reason}`);
+          continue;
+        }
         try {
           const typedData = buildEIP712TypedData({
             fromAddress: evmWallet.address,
@@ -301,8 +317,8 @@ export async function* createPrivyPaymentSignatures(response, url) {
 
           const authorization = {
             from: evmWallet.address,
-            to: requirement.payTo,
-            value: (requirement.amount || requirement.maxAmountRequired).toString(),
+            to: resolvePayTo(requirement),
+            value: resolvePaymentAmount(requirement).toString(),
             validAfter: typedData.message.validAfter.toString(),
             validBefore: typedData.message.validBefore.toString(),
             nonce: typedData.message.nonce,
@@ -332,6 +348,11 @@ export async function* createPrivyPaymentSignatures(response, url) {
     const solWallet = await getPrivySolanaWallet(client);
     if (solWallet) {
       for (const requirement of svmRequirements) {
+        const svmDecision = evaluatePaymentRequirement(requirement);
+        if (!svmDecision.ok) {
+          console.error(`[x402] ${svmDecision.reason}`);
+          continue;
+        }
         try {
           const rpcUrl = getSolanaRpcUrl(requirement.network);
           const recentBlockhash = await fetchRecentBlockhash(rpcUrl);

package/src/schema.json

@@ -1800,7 +1800,7 @@
       }
     },
     "wallet": {
-      "description": "Wallet management",
+      "description": "Wallet management. x402 auto-payments are guarded by a client-side policy: per-payment USD cap via NANSEN_X402_MAX_AMOUNT (default 1.00; 'unlimited' to disable) and an optional recipient allowlist via NANSEN_X402_ALLOWED_PAYTO (comma-separated addresses).",
       "subcommands": {
         "create": {
           "description": "Create a new wallet"
@@ -1962,6 +1962,60 @@
         "text",
         "tool_calls"
       ]
+    },
+    "mcp": {
+      "description": "Install, uninstall, or verify the hosted Nansen MCP server (https://mcp.nansen.ai/ra/mcp)",
+      "subcommands": {
+        "verify": {
+          "description": "Check MCP server reachability and verify an API key on the paid data path (~1 credit)",
+          "options": {
+            "api-key": {
+              "type": "string",
+              "description": "API key to test; overrides NANSEN_API_KEY and ~/.nansen/config.json"
+            },
+            "url": {
+              "type": "string",
+              "default": "https://mcp.nansen.ai/ra/mcp",
+              "description": "Hosted MCP server URL"
+            },
+            "json": {
+              "type": "boolean",
+              "description": "Return machine-readable verification checks and exit non-zero on failure"
+            }
+          },
+          "examples": [
+            "npx -y nansen-cli mcp verify",
+            "nansen mcp verify --json",
+            "nansen mcp verify --url https://mcp.example.dev/ra/mcp --api-key <key>"
+          ]
+        },
+        "install": {
+          "description": "Add the Nansen MCP server to a client's config. Client (positional): claude-code, claude-desktop, or cursor. Uses the API key from `nansen login` / NANSEN_API_KEY; re-run after key rotation to update the entry.",
+          "options": {
+            "dry-run": {
+              "type": "boolean",
+              "description": "Print the target config path and entry (API key redacted) without writing"
+            }
+          },
+          "examples": [
+            "nansen mcp install claude-code",
+            "nansen mcp install cursor --dry-run"
+          ]
+        },
+        "uninstall": {
+          "description": "Remove the Nansen MCP server entry from a client's config. Client (positional): claude-code, claude-desktop, or cursor.",
+          "options": {
+            "dry-run": {
+              "type": "boolean",
+              "description": "Report whether the Nansen entry would be removed without writing"
+            }
+          },
+          "examples": [
+            "nansen mcp uninstall claude-code",
+            "nansen mcp uninstall cursor --dry-run"
+          ]
+        }
+      }
     }
   },
   "globalOptions": {

package/src/swap-simulation.js

@@ -213,6 +213,12 @@ async function postSim(rpcUrl, apiKey, method, params, timeoutMs) {
     const sendApiKey = Boolean(apiKey) && isNansenHostedUrl(rpcUrl);
     const res = await fetch(rpcUrl, {
       method: 'POST',
+      // Refuse redirects only when the apikey header is attached — undici
+      // forwards custom credential headers across a cross-origin redirect, so a
+      // redirect would hand the key to whatever host the response points at.
+      // An anonymous call to a user-configured third-party RPC carries nothing
+      // to leak, so it keeps following redirects as before.
+      redirect: sendApiKey ? 'error' : 'follow',
       headers: {
         'Content-Type': 'application/json',
         ...(sendApiKey ? { apikey: apiKey } : {}),

package/src/trade-validation.js

@@ -8,6 +8,7 @@ import { validateAddress } from './api.js';
 import { CHAIN_RPCS } from './rpc-urls.js';
 import { parseTransactionMessage, resolveStaticAccount } from './solana-tx.js';
 import { SOL_SENTINEL } from './solana-simulation.js';
+import { EVM_NATIVE_SENTINEL } from './swap-simulation.js';
 
 const SUPPORTED_CHAINS = ['solana', 'base'];
 
@@ -146,6 +147,21 @@ const NATIVE_TOKEN_ADDRESSES = {
   base: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
 };
 
+// Upper bound on native (ETH) that may leave the wallet as a *sibling* of a
+// cross-chain bridge — some bridges pay a network fee via msg.value on a
+// token-input route, which surfaces as a native outflow distinct from the input
+// token. assertSwapOutcome's no-sibling-drain check (assertion 3) is otherwise
+// strict-zero, so without a bound such a fee would false-block a legitimate
+// bridge. The tolerance is the smaller of the transaction's declared native
+// value and THIS cap (see verifySwapOutcome); capping it — rather than trusting
+// the quote's value outright — is what keeps the check from being turned into a
+// native-ETH drain (a hostile quote could otherwise set value to the whole
+// balance). Conservative and gas-independent (gas is already excluded from the
+// simulated native delta); a real bridge fee is far below it. This is a
+// defence-in-depth loss ceiling, not a fee estimate — revisit if a route ever
+// legitimately needs more.
+export const EVM_BRIDGE_NATIVE_FEE_SLACK = 2_000_000_000_000_000n; // 0.002 ETH
+
 // Native SOL has two on-chain spellings that denote the same asset: the
 // canonical wrapped-SOL mint (what the CLI resolves `SOL` to and persists as
 // the request intent) and the System Program address that aggregators and
@@ -919,7 +935,7 @@ export function assertSwapCalldataNotBareTransfer(data) {
  * Derived from the immutable persisted request intent (not the loose
  * quote/quoteData) so it can't drift between calls or across chains.
  */
-function isBridgeRequest(request) {
+export function isBridgeRequest(request) {
   return request.toChain != null
     && String(request.toChain).toLowerCase() !== String(request.chain).toLowerCase();
 }
@@ -956,8 +972,11 @@ function isBridgeRequest(request) {
  * @param {Set<string>|string[]} [ctx.expectedSpenders] - spenders the wallet may
  *   legitimately (re)approve during the swap (e.g. the approval target and the
  *   router); anything else fails assertion 4. Compared case-insensitively.
- * @param {bigint} [ctx.siblingDustThreshold=0n] - non-input outflow tolerated
- *   before assertion 3 fires (for fee-on-transfer / rounding). Strict 0 default.
+ * @param {bigint} [ctx.siblingDustThreshold=0n] - native-token (ETH) sibling
+ *   outflow tolerated before assertion 3 fires, and only for a cross-chain
+ *   bridge (some bridges pay a fee via msg.value on a token-input route). ERC-20
+ *   siblings and every same-chain swap stay strict 0. The caller must pass a
+ *   bounded value (see EVM_BRIDGE_NATIVE_FEE_SLACK). Strict 0 default.
  * @returns {{verified: true, outputAssertionSkipped: boolean}} outputAssertionSkipped
  *   is true for a cross-chain bridge, meaning assertion 2 did not run — the
  *   caller should surface this.
@@ -1127,10 +1146,18 @@ export function assertSwapOutcome(request, quote, sim, { slippage, expectedSpend
   }
 
   // --- Assertion 3: no token other than the input leaves the wallet ---
-  const dust = siblingDustThreshold > 0n ? siblingDustThreshold : 0n;
+  // A bridge may pay a network fee in native ETH via msg.value on a
+  // token-input route, which shows up here as a native sibling outflow. Tolerate
+  // that — but only native, only for a bridge, and only up to the bounded
+  // threshold the caller passes (gas is already excluded from the native delta).
+  // ERC-20 siblings and every same-chain swap keep strict-zero. This mirrors the
+  // native-only carve-out assertSolanaSwapOutcome already applies for SOL.
+  const nativeDust = isBridge && siblingDustThreshold > 0n ? siblingDustThreshold : 0n;
   for (const [token, delta] of Object.entries(deltas)) {
     if (token === inputToken) continue; // its outflow is bounded by assertion 1
-    if (delta < 0n && -delta > dust) {
+    if (delta >= 0n) continue;
+    const dust = token === EVM_NATIVE_SENTINEL ? nativeDust : 0n;
+    if (-delta > dust) {
       throw fail(`a token other than the one you are selling (${token}) left the wallet (delta ${delta}); a swap must not move any token except the input.`);
     }
   }