nansen-cli 1.10.1 → 1.11.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.11.1
+
+### Patch Changes
+
+- [#194](https://github.com/nansen-ai/nansen-cli/pull/194) [`89225f5`](https://github.com/nansen-ai/nansen-cli/commit/89225f5d5b566f7eda77b1876c77545c2feb6a1c) Thanks [@TimNooren](https://github.com/TimNooren)! - fix: --help on trade subcommands and wallet subcommands now shows full help identical to the no-args case
+
+- [#199](https://github.com/nansen-ai/nansen-cli/pull/199) [`9ae981e`](https://github.com/nansen-ai/nansen-cli/commit/9ae981e6dcf7fa663e47a3608afab7f12e0a9463) Thanks [@TimNooren](https://github.com/TimNooren)! - fix: replace misleading `walletconnect connect` command reference in x402 payment error with actionable guidance mentioning both local wallet (`nansen wallet create`) and external WalletConnect CLI options
+
+## 1.11.0
+
+### Minor Changes
+
+- [#186](https://github.com/nansen-ai/nansen-cli/pull/186) [`feecc50`](https://github.com/nansen-ai/nansen-cli/commit/feecc5080254b55aaef0addb646279d52a468063) Thanks [@TimNooren](https://github.com/TimNooren)! - Trade commands output to stdout instead of stderr; wallet send prints human-readable text instead of JSON
+
+### Patch Changes
+
+- [#166](https://github.com/nansen-ai/nansen-cli/pull/166) [`c1034db`](https://github.com/nansen-ai/nansen-cli/commit/c1034dbb4bf2fc173f377cbc0adbbbe3e67873aa) Thanks [@0xlaveen](https://github.com/0xlaveen)! - fix: pass --page parameter correctly in smart-money, profiler, token, perp, and points commands
+
+- [#137](https://github.com/nansen-ai/nansen-cli/pull/137) [`1214767`](https://github.com/nansen-ai/nansen-cli/commit/12147675aadfd0bd97627cb2f41f1dcc5205b0d7) Thanks [@0xlaveen](https://github.com/0xlaveen)! - Add missing sort/filters options to profiler schema and fix pnl sort/filters forwarding
+
 ## 1.10.1
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/nansen-cli.svg)](https://www.npmjs.com/package/nansen-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **Built by agents, for agents.** Command-line interface for the [Nansen API](https://docs.nansen.ai) with structured JSON output.
+> **Built by agents, for agents.** Command-line interface for the [Nansen API](https://docs.nansen.ai), designed for AI agents.
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.10.1",
+  "version": "1.11.1",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",

package/src/api.js

@@ -62,7 +62,7 @@ export class NansenError extends Error {
     this.name = 'NansenError';
     this.code = code;
     this.status = status;
-    this.data = data;
+    this.details = data;
   }
 
   toJSON() {
@@ -70,7 +70,7 @@ export class NansenError extends Error {
       error: this.message,
       code: this.code,
       status: this.status,
-      details: this.data,
+      details: this.details,
     };
   }
 }
@@ -578,9 +578,20 @@ export class NansenAPI {
                     return await paidResponse.json();
                   }
                 } catch (x402Err) {
-                  message = `x402 auto-payment failed: ${x402Err.message}`;
+                  if (!this.apiKey) {
+                    // No API key and no payment wallet — guide the user to login rather than
+                    // showing a confusing x402 payment dump they can't act on.
+                    // TODO: full fix would skip x402 entirely when no apiKey is set — see PR #<this PR number>
+                    message = 'No API key configured. Run: nansen login --api-key <key>. Get your key at https://app.nansen.ai/api';
+                  } else {
+                    message = `x402 auto-payment failed: ${x402Err.message}`;
+                  }
+                }
+                // Only include raw payment requirements in the error details when the user
+                // has an API key — for unauthenticated users they add noise, not signal.
+                if (this.apiKey) {
+                  data.paymentRequirements = paymentRequirements;
                 }
-                data.paymentRequirements = paymentRequirements;
               }
             }
           }
@@ -733,7 +744,7 @@ export class NansenAPI {
   }
 
   async addressPnl(params = {}) {
-    const { address, chain = 'ethereum', date, days = 30, pagination } = params;
+    const { address, chain = 'ethereum', date, days = 30, filters = {}, orderBy, pagination } = params;
     if (address) {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
@@ -743,6 +754,8 @@ export class NansenAPI {
       address,
       chain,
       date: dateRange,
+      filters,
+      order_by: orderBy,
       pagination
     });
   }

package/src/cli.js

@@ -24,6 +24,16 @@ const schemaDefinition = require('./schema.json');
 // and should be updated whenever the API changes — do not edit returns arrays here.
 export const SCHEMA = { version: VERSION, ...schemaDefinition };
 
+// ============= Pagination =============
+
+export function buildPagination(options) {
+  if (!options.limit && !options.page) return undefined;
+  return {
+    page: Math.max(1, parseInt(options.page, 10) || 1),
+    per_page: options.limit,
+  };
+}
+
 // ============= Field Filtering =============
 
 /**
@@ -313,13 +323,17 @@ export function formatOutput(data, { pretty = false, table = false, csv = false
 
 // Format error data (returns object, does not exit)
 export function formatError(error) {
-  return {
+  const details = error.details ?? error.data ?? null;
+  const result = {
     success: false,
     error: error.message,
     code: error.code || 'UNKNOWN',
     status: error.status || null,
-    details: error.data || null
   };
+  if (details != null && !(typeof details === 'object' && !Array.isArray(details) && Object.keys(details).length === 0)) {
+    result.details = details;
+  }
+  return result;
 }
 
 /**
@@ -606,7 +620,7 @@ export async function compareWallets(api, params = {}) {
 
 export const BANNER = '';
 
-export const HELP = `Nansen CLI v${VERSION} — structured JSON output for AI agents.
+export const HELP = `Nansen CLI v${VERSION} — designed for AI agents.
 
 USAGE: nansen <command> [subcommand] [options]
 
@@ -628,9 +642,10 @@ EXAMPLES:
   nansen research smart-money netflow --chain solana
   nansen research token screener --chain solana --timeframe 24h
   nansen research profiler balance --address 0x... --chain ethereum
-  nansen trade quote --chain ethereum --from ETH --to USDC --amount 1
+  nansen trade quote --chain base --from ETH --to USDC --amount 1
 
-Chains: ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, mantle, ronin, sei, plasma, sonic, monad, hyperevm, iotaevm
+Research chains: ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, mantle, ronin, sei, plasma, sonic, monad, hyperevm, iotaevm
+Trade chains: solana, base
 Labels: Fund, Smart Trader, 30D/90D/180D Smart Trader, Smart HL Perps Trader
 
 Docs: https://docs.nansen.ai
@@ -855,7 +870,7 @@ export function buildCommands(deps = {}) {
       const chains = options.chains || [chain];
       const filters = options.filters || {};
       const orderBy = parseSort(options.sort, options['order-by']);
-      const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+      const pagination = buildPagination(options);
 
       // Add smart money label filter if specified
       if (options.labels) {
@@ -906,7 +921,7 @@ export function buildCommands(deps = {}) {
       }
       const filters = options.filters || {};
       const orderBy = parseSort(options.sort, options['order-by']);
-      const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+      const pagination = buildPagination(options);
       const days = options.days ? parseInt(options.days) : 30;
 
       const handlers = {
@@ -918,7 +933,7 @@ export function buildCommands(deps = {}) {
         },
         'pnl': () => {
           const date = parseDateOption(options.date, days);
-          return apiInstance.addressPnl({ address, chain, date, days, pagination });
+          return apiInstance.addressPnl({ address, chain, date, days, filters, orderBy, pagination });
         },
         'search': () => apiInstance.entitySearch({ query: options.query }),
         'historical-balances': () => apiInstance.addressHistoricalBalances({ address, chain, filters, orderBy, pagination, days }),
@@ -992,7 +1007,7 @@ export function buildCommands(deps = {}) {
       const timeframe = options.timeframe || '24h';
       const filters = options.filters || {};
       const orderBy = parseSort(options.sort, options['order-by']);
-      const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+      const pagination = buildPagination(options);
       const days = options.days ? parseInt(options.days) : 30;
 
       // Convenience filter for smart money only
@@ -1065,6 +1080,28 @@ export function buildCommands(deps = {}) {
 
       let result = await handlers[subcommand]();
 
+      // Warn when OHLCV price data is null (backend coverage gap)
+      // Volume comes from on-chain DEX data and is always available, but price/market_cap
+      // requires a price oracle — some tokens are not tracked and return all-null price fields.
+      if (subcommand === 'ohlcv') {
+        const candles = Array.isArray(result?.data) ? result.data : [];
+        if (candles.length === 0) {
+          process.stderr.write(`⚠️  No OHLCV data returned for token ${tokenAddress} on ${chain}.\n`);
+        } else {
+          const hasPrice = candles.some(c => c.open !== null || c.close !== null);
+          const hasVolume = candles.some(c => c.volume !== null);
+          if (!hasPrice && hasVolume) {
+            process.stderr.write(
+              `⚠️  Price data unavailable for token ${tokenAddress} on ${chain}.\n` +
+              `   open/high/low/close, volume_usd, and market_cap are null.\n` +
+              `   Volume (raw token units) is available. This token may not be tracked by Nansen's price oracle.\n`
+            );
+          } else if (!hasPrice && !hasVolume) {
+            process.stderr.write(`⚠️  No OHLCV data available for token ${tokenAddress} on ${chain}.\n`);
+          }
+        }
+      }
+
       // Enrich transfers with Nansen labels for from/to addresses
       if (subcommand === 'transfers' && (options.enrich || flags.enrich)) {
         result = await enrichTransfers(result, apiInstance, chain);
@@ -1098,7 +1135,7 @@ export function buildCommands(deps = {}) {
       const subcommand = args[0] || 'help';
       const filters = options.filters || {};
       const orderBy = parseSort(options.sort, options['order-by']);
-      const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+      const pagination = buildPagination(options);
       const days = options.days ? parseInt(options.days) : 30;
 
       const handlers = {
@@ -1130,7 +1167,7 @@ export function buildCommands(deps = {}) {
     'points': async (args, apiInstance, flags, options) => {
       const subcommand = args[0] || 'help';
       const tier = options.tier;
-      const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+      const pagination = buildPagination(options);
 
       const handlers = {
         'leaderboard': () => apiInstance.pointsLeaderboard({ tier, pagination }),
@@ -1346,17 +1383,9 @@ export async function runCLI(rawArgs, deps = {}) {
           return { type: 'command-help', command: `research ${category}` };
         }
       }
-      // Handle 'trade <sub> --help'
-      if (command === 'trade' && subcommand) {
-        const tradeSchema = SCHEMA.commands.trade?.subcommands?.[subcommand];
-        if (tradeSchema) {
-          output(`\ntrade ${subcommand} - ${tradeSchema.description}\n`);
-          notify();
-          return { type: 'subcommand-help', command: 'trade', subcommand };
-        }
-      }
       // First try subcommand help
-      if (command && subcommand) {
+      // Skip for 'trade' — its handlers show their own rich usage when required args are missing
+      if (command && subcommand && command !== 'trade') {
         const subHelp = generateSubcommandHelp(command, subcommand);
         if (subHelp) {
           output(subHelp);
@@ -1365,7 +1394,8 @@ export async function runCLI(rawArgs, deps = {}) {
         }
       }
       // Then try command-level help (list subcommands)
-      const cmdSchemaLookup = SCHEMA.commands[command] || SCHEMA.commands.research.subcommands[command];
+      // Skip for 'trade' — let the handler show its own usage
+      const cmdSchemaLookup = command !== 'trade' && (SCHEMA.commands[command] || SCHEMA.commands.research.subcommands[command]);
       if (command && cmdSchemaLookup) {
         const cmdSchema = cmdSchemaLookup;
         const lines = [`${command} — ${cmdSchema.description}`];

package/src/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 /**
  * Nansen CLI - Command-line interface for Nansen API
- * Designed for AI agents with structured JSON output
- * 
+ * Designed for AI agents.
+ *
  * Usage: nansen <command> [options]
- * 
- * All output is JSON for easy parsing by AI agents.
+ *
+ * Research commands return JSON; operational commands print human-readable text.
  * Use --pretty for human-readable formatting.
  * 
  * Core logic lives in cli.js for testability.