nansen-cli 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 1.17.0
+
+### Minor Changes
+
+- [#279](https://github.com/nansen-ai/nansen-cli/pull/279) [`174a3d6`](https://github.com/nansen-ai/nansen-cli/commit/174a3d612b3f198c5e5b979c269d896f9d906704) Thanks [@kome12](https://github.com/kome12)! - Add `nansen account` command to verify API key and check credit balance
+
+  Users can now run `nansen account` to confirm their API key is valid and see
+  their current plan and remaining credits — without consuming any credits.
+
+  This calls the new `GET /api/v1/account` endpoint (ECINT-6365).
+
+- [#234](https://github.com/nansen-ai/nansen-cli/pull/234) [`10a5ced`](https://github.com/nansen-ai/nansen-cli/commit/10a5ced9f1f751666d034cecfc431e335183741c) Thanks [@kome12](https://github.com/kome12)! - Reduced schema.json to a minimal format (~66% smaller).
+
+### Patch Changes
+
+- [#272](https://github.com/nansen-ai/nansen-cli/pull/272) [`50213c1`](https://github.com/nansen-ai/nansen-cli/commit/50213c1d82375a153aa1bad3a53bbd7059cd9f5b) Thanks [@TimNooren](https://github.com/TimNooren)! - fix: show human-readable error when trade fails due to insufficient ETH
+
+  When a wallet has no ETH and a trade is attempted, the raw Ethereum RPC
+  error ("insufficient funds for gas \* price + value: ... have 0 want
+  400000000000000 (supplied gas 600000000)") is now translated into a
+  user-friendly message showing amounts in ETH with a funding hint, e.g.
+  "Insufficient ETH: wallet has 0.000000 ETH but this trade needs ~0.000400
+  ETH (amount + gas). Send ETH to 0x... before trading."
+
+## 1.16.1
+
+### Patch Changes
+
+- [#249](https://github.com/nansen-ai/nansen-cli/pull/249) [`0c17437`](https://github.com/nansen-ai/nansen-cli/commit/0c17437cf65d8b4f0516ede386adefec57d8ab3d) Thanks [@0xlaveen](https://github.com/0xlaveen)! - Add `pm` to top-level COMMAND_ALIASES so `nansen pm <subcommand>` works (previously only `nansen research pm <subcommand>` resolved the alias)
+
+- [#244](https://github.com/nansen-ai/nansen-cli/pull/244) [`6427a9f`](https://github.com/nansen-ai/nansen-cli/commit/6427a9fdb7295dee94d7aed10cdb0164c46c7d73) Thanks [@Nicolai1205](https://github.com/Nicolai1205)! - Add 7 new agent skills: nansen-token-search, nansen-sm-trend, nansen-wallet-cluster, nansen-wallet-compare, nansen-token-indicators, nansen-cross-chain-flow, nansen-batch-wallet. All validated against live API.
+
 ## 1.16.0
 
 ### Minor Changes

package/package.json

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

package/src/api.js

@@ -418,6 +418,52 @@ export class NansenAPI {
     );
   }
 
+  /**
+   * Retry a POST request with a payment signature.
+   * Returns parsed JSON if the paid request succeeds, or null if still rejected.
+   * Logs the payment and warns about low balance when walletLabel and network are given.
+   *
+   * @param {string} signature - Payment-Signature header value
+   * @param {string|null} walletLabel - Display label for logging, e.g. "local wallet alice"
+   * @param {string|null} network - x402 network string for balance check, e.g. "eip155:8453"
+   * @param {string} url - Request URL
+   * @param {object} body - Request body (will be cleaned)
+   * @param {object} [options={}] - Request options (may include .headers)
+   * @returns {Promise<object|null>} Parsed JSON on success, null if rejected
+   *
+   * TODO: full fix — extract the entire x402 provider dispatch from request() into
+   * an attemptX402Payment() method so adding a new payment provider only requires
+   * touching that one method, not hunting inside the retry loop.
+   */
+  async _x402Retry(signature, walletLabel, network, url, body, options = {}) {
+    const paidResponse = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Client-Type': 'nansen-cli',
+        'X-Client-Version': packageVersion,
+        'Payment-Signature': signature,
+        ...this.defaultHeaders,
+        ...options.headers,
+      },
+      body: JSON.stringify(NansenAPI.cleanBody(body)),
+    });
+    if (!paidResponse.ok) return null;
+    if (walletLabel) {
+      console.error(`[x402] Paid via ${walletLabel}${network ? ` (${network})` : ''}`);
+    }
+    if (network) {
+      try {
+        const { checkX402Balance } = await import('./x402.js');
+        const balance = await checkX402Balance(network);
+        if (balance !== null && balance < 0.25) {
+          console.error(`[x402] Warning: USDC balance low ($${balance.toFixed(2)}). Fund your wallet to avoid interruptions.`);
+        }
+      } catch { /* balance check is best-effort */ }
+    }
+    return await paidResponse.json();
+  }
+
   async request(endpoint, body = {}, options = {}) {
     const url = `${this.baseUrl}${endpoint}`;
     const { maxRetries, baseDelayMs, maxDelayMs, retryOnStatus } = this.retryOptions;
@@ -439,17 +485,19 @@ export class NansenAPI {
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       let response;
       try {
+        const method = options.method || 'POST';
+        const isGet = method === 'GET';
         response = await fetch(url, {
-          method: 'POST',
+          method,
           headers: {
-            'Content-Type': 'application/json',
+            ...(!isGet && { 'Content-Type': 'application/json' }),
             'X-Client-Type': 'nansen-cli',
             'X-Client-Version': packageVersion,
             ...(this.apiKey ? { 'apikey': this.apiKey } : {}),
             ...this.defaultHeaders,
             ...options.headers
           },
-          body: JSON.stringify(NansenAPI.cleanBody(body))
+          ...(!isGet && { body: JSON.stringify(NansenAPI.cleanBody(body)) })
         });
       } catch (err) {
         // Network-level errors - retry these too
@@ -524,29 +572,8 @@ export class NansenAPI {
               try {
                 const { createPrivyPaymentSignatures } = await import('./privy.js');
                 for await (const { signature, network } of createPrivyPaymentSignatures(response, url)) {
-                  const paidResponse = await fetch(url, {
-                    method: 'POST',
-                    headers: {
-                      'Content-Type': 'application/json',
-                      'X-Client-Type': 'nansen-cli',
-                      'X-Client-Version': packageVersion,
-                      'Payment-Signature': signature,
-                      ...this.defaultHeaders,
-                      ...options.headers,
-                    },
-                    body: JSON.stringify(NansenAPI.cleanBody(body)),
-                  });
-                  if (paidResponse.ok) {
-                    console.error(`[x402] Paid via Privy wallet ${defaultWalletName} (${network})`);
-                    try {
-                      const { checkX402Balance } = await import('./x402.js');
-                      const balance = await checkX402Balance(network);
-                      if (balance !== null && balance < 0.25) {
-                        console.error(`[x402] Warning: USDC balance low ($${balance.toFixed(2)}). Fund your wallet to avoid interruptions.`);
-                      }
-                    } catch { /* balance check is best-effort */ }
-                    return await paidResponse.json();
-                  }
+                  const result = await this._x402Retry(signature, `Privy wallet ${defaultWalletName}`, network, url, body, options);
+                  if (result !== null) return result;
                 }
               } catch (privyErr) {
                 message = `x402 Privy payment failed: ${privyErr.message}`;
@@ -557,30 +584,8 @@ export class NansenAPI {
               try {
                 const { createPaymentSignatures } = await import('./x402.js');
                 for await (const { signature, network } of createPaymentSignatures(response, url)) {
-                  const paidResponse = await fetch(url, {
-                    method: 'POST',
-                    headers: {
-                      'Content-Type': 'application/json',
-                      'X-Client-Type': 'nansen-cli',
-                      'X-Client-Version': packageVersion,
-                      'Payment-Signature': signature,
-                      ...this.defaultHeaders,
-                      ...options.headers,
-                    },
-                    body: JSON.stringify(NansenAPI.cleanBody(body)),
-                  });
-                  if (paidResponse.ok) {
-                    console.error(`[x402] Paid via local wallet ${defaultWalletName} (${network})`);
-                    // Check remaining balance and warn if low
-                    try {
-                      const { checkX402Balance } = await import('./x402.js');
-                      const balance = await checkX402Balance(network);
-                      if (balance !== null && balance < 0.25) {
-                        console.error(`[x402] Warning: USDC balance low ($${balance.toFixed(2)}). Fund your wallet to avoid interruptions.`);
-                      }
-                    } catch { /* balance check is best-effort */ }
-                    return await paidResponse.json();
-                  }
+                  const result = await this._x402Retry(signature, `local wallet ${defaultWalletName}`, network, url, body, options);
+                  if (result !== null) return result;
                   // This payment option was rejected, try next
                 }
               } catch { /* local wallet unavailable, try WalletConnect */ }
@@ -604,21 +609,8 @@ export class NansenAPI {
                   try {
                     const { handleX402Payment } = await import('./walletconnect-x402.js');
                     const paymentSignature = await handleX402Payment(paymentRequirements);
-                    const paidResponse = await fetch(url, {
-                      method: 'POST',
-                      headers: {
-                        'Content-Type': 'application/json',
-                        'X-Client-Type': 'nansen-cli',
-                        'X-Client-Version': packageVersion,
-                        'Payment-Signature': paymentSignature,
-                        ...this.defaultHeaders,
-                        ...options.headers,
-                      },
-                      body: JSON.stringify(NansenAPI.cleanBody(body)),
-                    });
-                    if (paidResponse.ok) {
-                      return await paidResponse.json();
-                    }
+                    const result = await this._x402Retry(paymentSignature, 'WalletConnect', null, url, body, options);
+                    if (result !== null) return result;
                   } catch (x402Err) {
                     if (!this.apiKey) {
                       message = 'No API key configured. Two ways to authenticate:\n' +
@@ -674,6 +666,12 @@ export class NansenAPI {
     throw lastError;
   }
 
+  // ============= Account Endpoint =============
+
+  async getAccount() {
+    return this.request('/api/v1/account', {}, { method: 'GET', cache: false });
+  }
+
   // ============= Smart Money Endpoints =============
   
   async smartMoneyNetflow(params = {}) {
@@ -1145,7 +1143,7 @@ export class NansenAPI {
 
   async pmOhlcv(params = {}) {
     const { marketId, sort, pagination } = params;
-    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/ohlcv', {
       market_id: marketId,
       sort,
@@ -1155,7 +1153,7 @@ export class NansenAPI {
 
   async pmOrderbook(params = {}) {
     const { marketId, pagination } = params;
-    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/orderbook', {
       market_id: marketId,
       pagination
@@ -1164,7 +1162,7 @@ export class NansenAPI {
 
   async pmTopHolders(params = {}) {
     const { marketId, sort, pagination } = params;
-    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/top-holders', {
       market_id: marketId,
       sort,
@@ -1174,7 +1172,7 @@ export class NansenAPI {
 
   async pmTradesByMarket(params = {}) {
     const { marketId, pagination } = params;
-    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/trades-by-market', {
       market_id: marketId,
       pagination
@@ -1214,7 +1212,7 @@ export class NansenAPI {
 
   async pmPnlByMarket(params = {}) {
     const { marketId, pagination } = params;
-    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/pnl-by-market', {
       market_id: marketId,
       pagination
@@ -1234,7 +1232,7 @@ export class NansenAPI {
 
   async pmPositionDetail(params = {}) {
     const { marketId, pagination } = params;
-    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/position-detail', {
       market_id: marketId,
       pagination

package/src/cli.js

@@ -654,8 +654,8 @@ export async function compareWallets(api, params = {}) {
     shared_counterparties: sharedCpAddrs,
     shared_tokens: sharedTokens,
     balances: [
-      { address: addr1, total_usd: tokens1.reduce((sum, t) => sum + (t.balance_usd || 0), 0) },
-      { address: addr2, total_usd: tokens2.reduce((sum, t) => sum + (t.balance_usd || 0), 0) },
+      { address: addr1, total_usd: tokens1.reduce((sum, t) => sum + (t.value_usd ?? t.balance_usd ?? 0), 0) },
+      { address: addr2, total_usd: tokens2.reduce((sum, t) => sum + (t.value_usd ?? t.balance_usd ?? 0), 0) },
     ],
   };
 }
@@ -670,6 +670,7 @@ COMMANDS:
   research    smart-money, profiler, token, search, perp, portfolio, points
   trade       quote, execute
   wallet      create, list, show, export, default, delete, forget-password
+  account     Show API key status, plan, and remaining credits
   login       Save API key (--api-key <key> or NANSEN_API_KEY env var)
   logout      Remove saved API key
   schema      JSON schema for all commands (use "nansen schema <cmd>" for one)
@@ -757,6 +758,10 @@ export function buildCommands(deps = {}) {
   } = deps;
 
   const cmds = {
+    'account': async (_args, apiInstance, _flags, _options) => {
+      return apiInstance.getAccount();
+    },
+
     'login': async (args, apiInstance, flags, options) => {
       if (flags.help || flags.h) {
         log('nansen login - Save your Nansen API key\n');
@@ -1240,6 +1245,9 @@ export function buildCommands(deps = {}) {
     },
 
     'prediction-market': async (args, apiInstance, flags, options) => {
+      if (Date.now() < new Date('2026-03-16T00:00:00Z').getTime()) {
+        process.stderr.write('⚠️  PnL data for prediction markets is temporarily unavailable while we improve accuracy. We\'ll update once resolved.\n');
+      }
       const subcommand = args[0] || 'help';
       const marketId = options['market-id'];
       const address = options.address;
@@ -1345,7 +1353,8 @@ export const COMMAND_ALIASES = {
   'tgm': 'token',           // Token God Mode
   'sm': 'smart-money',      // Smart Money
   'prof': 'profiler',       // Profiler
-  'port': 'portfolio'       // Portfolio
+  'port': 'portfolio',      // Portfolio
+  'pm': 'prediction-market' // Prediction Market
 };
 
 // Aliases used inside the 'research' namespace

package/src/rpc-urls.js

@@ -0,0 +1,29 @@
+/**
+ * Single source of truth for chain RPC endpoints.
+ *
+ * Both trading.js and transfer.js read from here so that:
+ *   (a) adding a new chain only requires one edit, and
+ *   (b) env-var overrides work consistently across all commands.
+ *
+ * Override env vars:
+ *   NANSEN_EVM_RPC        Custom Ethereum RPC (also used as generic EVM fallback)
+ *   NANSEN_BASE_RPC       Custom Base RPC
+ *   NANSEN_SOLANA_RPC     Custom Solana RPC
+ *
+ * Backward-compat aliases (deprecated — prefer the forms above):
+ *   NANSEN_RPC_BASE       Old name for NANSEN_BASE_RPC; trading.js previously read this
+ *                         but transfer.js never did, so the two commands were inconsistent.
+ *                         Both forms are now accepted here so existing .env files keep
+ *                         working while new code uses the standardised NANSEN_BASE_RPC name.
+ */
+
+const DEFAULT_EVM_RPC    = 'https://eth.public-rpc.com';
+const DEFAULT_BASE_RPC   = 'https://mainnet.base.org';
+const DEFAULT_SOLANA_RPC = 'https://api.mainnet-beta.solana.com';
+
+export const CHAIN_RPCS = {
+  ethereum: process.env.NANSEN_EVM_RPC    || DEFAULT_EVM_RPC,
+  evm:      process.env.NANSEN_EVM_RPC    || DEFAULT_EVM_RPC,   // generic EVM fallback
+  base:     process.env.NANSEN_BASE_RPC   || process.env.NANSEN_RPC_BASE || DEFAULT_BASE_RPC,
+  solana:   process.env.NANSEN_SOLANA_RPC || DEFAULT_SOLANA_RPC,
+};