nansen-cli 1.22.0 → 1.23.1

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 1.23.1
+
+### Patch Changes
+
+- [#361](https://github.com/nansen-ai/nansen-cli/pull/361) [`ff22da3`](https://github.com/nansen-ai/nansen-cli/commit/ff22da376c1072ef06e84054f6ee31c058e6e08c) Thanks [@TimNooren](https://github.com/TimNooren)! - fix(alerts): error when --webhook-secret is passed without --webhook
+
+  Previously, passing --webhook-secret with a non-webhook channel (e.g. --telegram)
+  silently discarded the secret with no warning. The alert was created successfully
+  but without any signing, giving the false impression that the secret was active.
+
+  Now throws an actionable error: "--webhook-secret requires --webhook".
+
+- [#358](https://github.com/nansen-ai/nansen-cli/pull/358) [`70ee712`](https://github.com/nansen-ai/nansen-cli/commit/70ee71205343fb2d003eb5f50144e266bdc6109e) Thanks [@TimNooren](https://github.com/TimNooren)! - Add pre-quote trade input validation: rejects same-token swaps, invalid address formats, and non-positive amounts before any network call.
+
+## 1.23.0
+
+### Minor Changes
+
+- [#341](https://github.com/nansen-ai/nansen-cli/pull/341) [`4b60056`](https://github.com/nansen-ai/nansen-cli/commit/4b6005697d52b5d432b9b32bcd1d36422f9166cc) Thanks [@gulshngill](https://github.com/gulshngill)! - Add `--webhook <url>` and `--webhook-secret <secret>` flags to `alerts create` and `alerts update`.
+
+  Allows alerts to be delivered to any HTTP/HTTPS endpoint via POST, alongside
+  the existing `--telegram`, `--slack`, and `--discord` channels. The optional
+  `--webhook-secret` enables HMAC payload signing for verification.
+
+### Patch Changes
+
+- [#344](https://github.com/nansen-ai/nansen-cli/pull/344) [`3dc09cc`](https://github.com/nansen-ai/nansen-cli/commit/3dc09cc8aa38cd4da4ae305f83e9599efb3b9ff9) Thanks [@0xlaveen](https://github.com/0xlaveen)! - Add nansen-agent-guide skill — routing guide for when to use `nansen agent` vs direct CLI data commands
+
+- [#347](https://github.com/nansen-ai/nansen-cli/pull/347) [`a243c7a`](https://github.com/nansen-ai/nansen-cli/commit/a243c7a33f28057949d2060c732083642422eb18) Thanks [@kome12](https://github.com/kome12)! - Add --buy-or-sell option to `token who-bought-sold` command — allows filtering by buy or sell side (BUY | SELL, defaults to BUY)
+
 ## 1.22.0
 
 ### Minor Changes

package/README.md

@@ -27,6 +27,8 @@ Get your API key at [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/
 
 ```
 nansen research <category> <subcommand> [options]
+nansen agent "<question>"             # AI research agent (200 credits, Pro)
+nansen agent "<question>" --expert    # deeper analysis (750 credits, Pro)
 nansen trade <subcommand> [options]
 nansen wallet <subcommand> [options]
 nansen schema [command] [--pretty]    # full command reference (no API key needed)

package/package.json

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

package/skills/nansen-agent-guide/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: nansen-agent-guide
+description: Routing guide -- when to use `nansen agent` (AI research) vs direct CLI data commands. Use when deciding how to answer a user's research question with Nansen tools.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - NANSEN_API_KEY
+      bins:
+        - nansen
+    primaryEnv: NANSEN_API_KEY
+    install:
+      - kind: node
+        package: nansen-cli
+        bins: [nansen]
+allowed-tools: Bash(nansen:*)
+---
+
+# Agent vs CLI Routing
+
+| Need a... | Use |
+|-----------|-----|
+| **take** (analysis, interpretation) | `nansen agent` |
+| **table** (raw data, specific metrics) | Direct CLI commands |
+| **report** (both) | Agent for narrative + CLI for data |
+
+## Use `nansen agent` when
+
+- Question requires interpretation or synthesis across multiple data sources
+- Open-ended research: "analyse this wallet", "what's happening with ETH smart money?"
+
+```bash
+nansen agent "What are top smart money tokens on Solana today and why?"
+nansen agent "Analyse wallet 0x123... -- is this a smart trader?"
+nansen agent "..." --expert   # deeper analysis, 750 credits
+```
+
+Cost: 200 credits (fast) / 750 credits (expert)
+
+## Use direct CLI commands when
+
+- You need specific structured data -- prices, volumes, holders, flows
+- Deterministic question: "top 10 tokens by netflow on ethereum"
+- Piping output or building a data table
+
+```bash
+nansen research token screener --chain ethereum --smart-money --limit 10
+nansen research smart-money netflow --chain solana
+nansen research profiler balance --address 0x123... --chain ethereum
+```
+
+Cost: 5-50 credits per call
+
+## Anti-patterns
+
+- Don't use `nansen agent` for simple data fetches -- 40x more expensive
+- Don't use raw CLI for open-ended analysis -- returns data, not interpretation
+- Don't chain 3+ agent calls -- get raw data via CLI, call agent once for synthesis

package/skills/nansen-smart-alerts/SKILL.md

@@ -41,6 +41,8 @@ nansen alerts delete <id>
 | `--telegram` | chat ID | optional | | |
 | `--slack` | webhook URL | optional | | |
 | `--discord` | webhook URL | optional | | |
+| `--webhook` | endpoint URL | optional | optional | |
+| `--webhook-secret` | optional (webhook only) | optional | | |
 | `--description` | optional | optional | | |
 | `--enabled` | | flag | flag | |
 | `--disabled` | flag | flag | flag | |
@@ -131,7 +133,8 @@ nansen alerts create \
 ## Notes
 
 - Chain aliases: Hyperliquid = `hyperevm`, BSC = `bnb`.
-- Multiple channels can be combined: `--telegram 123 --slack https://...`
+- Multiple channels can be combined: `--telegram 123 --slack https://... --webhook https://...`
+- `--webhook <url>` sends a POST request with the alert payload to any HTTP/HTTPS endpoint. Useful for server deployments, Zapier, n8n, or custom integrations. The endpoint must be publicly reachable and return a 2xx response.
 - `--data '<json>'` merges raw JSON on top of named flags (escape hatch for fields without named flags).
 - Alert endpoints are internal-only. Non-internal users receive 404.
 - Use single quotes for names with `$` or special characters: `--name 'SM >$1M'`

package/src/api.js

@@ -293,6 +293,19 @@ export function validateAddress(address, chain = 'ethereum') {
   return { valid: true };
 }
 
+/**
+ * Normalize EVM address to lowercase for API compatibility.
+ * The API should handle case-insensitive addresses server-side, but this is
+ * a defensive client-side measure since checksummed addresses currently
+ * return empty results.
+ */
+export function normalizeAddress(address, chain = 'ethereum') {
+  if (address && typeof address === 'string' && address.startsWith('0x') && EVM_CHAINS.includes(chain)) {
+    return address.toLowerCase();
+  }
+  return address;
+}
+
 /**
  * Validate token address (same rules as wallet address)
  */
@@ -1030,7 +1043,7 @@ export class NansenAPI {
   }
 
   async tokenWhoBoughtSold(params = {}) {
-    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination, days = 30, date } = params;
+    const { tokenAddress, chain = 'solana', buyOrSell = 'BUY', filters = {}, orderBy, pagination, days = 30, date } = params;
     if (tokenAddress) {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
@@ -1039,6 +1052,7 @@ export class NansenAPI {
     return this.request('/api/v1/tgm/who-bought-sold', {
       token_address: tokenAddress,
       chain,
+      buy_or_sell: buyOrSell,
       date: dateRange,
       filters,
       order_by: orderBy,

package/src/cli.js

@@ -3,7 +3,7 @@
  * Extracted from index.js for coverage
  */
 
-import { NansenAPI, NansenError, ErrorCode, saveConfig, deleteConfig, getConfigFile, clearCache, getCacheDir, validateAddress, sleep } from './api.js';
+import { NansenAPI, NansenError, ErrorCode, saveConfig, deleteConfig, getConfigFile, clearCache, getCacheDir, validateAddress, normalizeAddress, sleep } from './api.js';
 import { buildWalletCommands } from './wallet.js';
 import { buildTradingCommands } from './trading.js';
 import { formatAlertsTable, buildAlertsCommands } from './commands/alerts.js';
@@ -870,7 +870,7 @@ export function buildCommands(deps = {}) {
         return;
       }
 
-      let apiKey = options['api-key'] || options.apiKey;
+      let apiKey = options['api-key'];
 
       if (!apiKey) {
         apiKey = process.env.NANSEN_API_KEY;
@@ -1187,9 +1187,9 @@ export function buildCommands(deps = {}) {
 
     'token': async (args, apiInstance, flags, options) => {
       const subcommand = args[0] || 'help';
-      const tokenAddress = options.token || options['token-address'];
-      const tokenSymbol = options.symbol || options['token-symbol'];
       const chain = options.chain || 'solana';
+      const tokenAddress = normalizeAddress(options.token || options['token-address'], chain);
+      const tokenSymbol = options.symbol || options['token-symbol'];
       const chains = options.chains || [chain];
       const timeframe = options.timeframe || '24h';
       const filters = options.filters || {};
@@ -1247,7 +1247,8 @@ export function buildCommands(deps = {}) {
         'pnl': () => apiInstance.tokenPnlLeaderboard({ tokenAddress, chain, filters, orderBy, pagination, days }),
         'who-bought-sold': () => {
           const date = parseDateOption(options.date, days);
-          return apiInstance.tokenWhoBoughtSold({ tokenAddress, chain, filters, orderBy, pagination, days, date });
+          const buyOrSell = (options['buy-or-sell'] || 'BUY').toUpperCase();
+          return apiInstance.tokenWhoBoughtSold({ tokenAddress, chain, buyOrSell, filters, orderBy, pagination, days, date });
         },
         'flow-intelligence': () => apiInstance.tokenFlowIntelligence({ tokenAddress, chain, days }),
         'transfers': () => {

package/src/commands/alerts.js

@@ -484,10 +484,11 @@ USAGE:
 REQUIRED:
   --name <name>                Alert name
   --type <type>                sm-token-flows | common-token-transfer | smart-contract-call
-  At least one channel:        --telegram <chatId> | --slack <url> | --discord <url>
+  At least one channel:        --telegram <chatId> | --slack <url> | --discord <url> | --webhook <url>
 
 OPTIONS (all types):
   --chains <chains>            Comma-separated chains (e.g. ethereum,solana)
+  --webhook-secret <secret>    Signing secret for webhook payload verification (webhook only)
   --token <address:chain>      Include token (repeatable)
   --exclude-token <addr:chain> Exclude token (repeatable)
   --description '<text>'       Alert description
@@ -559,12 +560,23 @@ USAGE:
         return;
       }
 
-      // Build channels array from --telegram/--slack/--discord flags
+      // Build channels array from --telegram/--slack/--discord/--webhook flags
       function buildChannels() {
+        if (options["webhook-secret"] && !options.webhook) {
+          throw new NansenError('--webhook-secret requires --webhook', ErrorCode.INVALID_PARAMS);
+        }
         const channels = [];
         if (options.telegram) channels.push({ type: 'telegram', data: { chatId: String(options.telegram) } });
         if (options.slack) channels.push({ type: 'slack', data: { webhookUrl: options.slack } });
         if (options.discord) channels.push({ type: 'discord', data: { webhookUrl: options.discord } });
+        if (options.webhook) {
+          const webhookData = { webhookUrl: options.webhook };
+          if (options["webhook-secret"]) {
+            if (options["webhook-secret"].length < 16) throw new NansenError('--webhook-secret must be at least 16 characters', ErrorCode.INVALID_PARAMS);
+            webhookData.secret = options["webhook-secret"];
+          }
+          channels.push({ type: 'webhook', data: webhookData });
+        }
         return channels.length > 0 ? channels : null;
       }
 
@@ -608,7 +620,7 @@ USAGE:
           if (!name) missing.push('--name');
           if (!type) missing.push('--type');
           if (!options.chains) missing.push('--chains');
-          if (!channels) missing.push('a channel (--telegram, --slack, or --discord)');
+          if (!channels) missing.push('a channel (--telegram, --slack, --discord, or --webhook)');
           if (missing.length > 0) {
             throw new NansenError(`Required: ${missing.join(', ')}`, ErrorCode.MISSING_PARAM);
           }
@@ -707,7 +719,9 @@ USAGE:
               ? `Invalid Slack webhook URL. Check the URL and try again.`
               : ch?.type === 'discord'
                 ? `Invalid Discord webhook URL. Check the URL and try again.`
-                : err.message;
+                : ch?.type === 'webhook'
+                  ? `Invalid webhook URL (${ch.data.webhookUrl}). Ensure the endpoint is reachable and returns 2xx.`
+                  : err.message;
           throw new NansenError(hint, err.code ?? ErrorCode.INVALID_PARAMS, err.status);
         }
         throw err;

package/src/schema.json

@@ -300,6 +300,11 @@
                 },
                 "days": {
                   "default": 30
+                },
+                "buy-or-sell": {
+                  "description": "Filter by buy or sell side",
+                  "enum": ["BUY", "SELL"],
+                  "default": "BUY"
                 }
               }
             },
@@ -669,6 +674,14 @@
               "type": "string",
               "description": "Discord webhook URL for notifications"
             },
+            "webhook": {
+              "type": "string",
+              "description": "HTTP/HTTPS endpoint URL to POST alert payloads to"
+            },
+            "webhook-secret": {
+              "type": "string",
+              "description": "Signing secret for webhook payload verification (optional, webhook only)"
+            },
             "data": {
               "type": "string",
               "description": "Alert config JSON. --chains is merged on top."
@@ -710,6 +723,14 @@
               "type": "string",
               "description": "Discord webhook URL"
             },
+            "webhook": {
+              "type": "string",
+              "description": "HTTP/HTTPS endpoint URL to POST alert payloads to"
+            },
+            "webhook-secret": {
+              "type": "string",
+              "description": "Signing secret for webhook payload verification (optional, webhook only)"
+            },
             "data": {
               "type": "string",
               "description": "Alert config JSON. --chains merged on top."

package/src/trade-validation.js

@@ -0,0 +1,54 @@
+/**
+ * Trade input validation for the Nansen CLI.
+ * Catches common agent errors (wrong addresses, same-token swaps,
+ * bad amounts) before any network call.
+ */
+
+import { validateAddress } from './api.js';
+
+const SUPPORTED_CHAINS = ['solana', 'base'];
+
+/**
+ * Validate quote inputs before any network call.
+ * Throws on validation failure with an actionable error message.
+ */
+export function validateQuoteInput({ chain, from, to, amount }) {
+  // 1. Chain must be supported
+  const normalizedChain = chain?.toLowerCase();
+  if (!SUPPORTED_CHAINS.includes(normalizedChain)) {
+    throw new Error(
+      `Unsupported chain "${chain}". Supported chains: ${SUPPORTED_CHAINS.join(', ')}.`
+    );
+  }
+
+  // 2. Amount must be a positive finite number
+  const numAmount = Number(amount);
+  if (!Number.isFinite(numAmount) || numAmount <= 0) {
+    throw new Error(
+      `Invalid amount "${amount}". Must be a positive number.`
+    );
+  }
+
+  // 3. Token address format must match the chain (reuses api.js validateAddress)
+  const fromResult = validateAddress(from, normalizedChain);
+  if (!fromResult.valid) {
+    throw new Error(
+      `Invalid sell token address for ${normalizedChain}. ${fromResult.error}`
+    );
+  }
+  const toResult = validateAddress(to, normalizedChain);
+  if (!toResult.valid) {
+    throw new Error(
+      `Invalid buy token address for ${normalizedChain}. ${toResult.error}`
+    );
+  }
+
+  // 4. Sell and buy tokens must be different
+  const fromNorm = normalizedChain === 'solana' ? from : from.toLowerCase();
+  const toNorm = normalizedChain === 'solana' ? to : to.toLowerCase();
+  if (fromNorm === toNorm) {
+    throw new Error(
+      `Cannot swap ${from} for itself. Sell and buy tokens must be different.`
+    );
+  }
+}

package/src/trading.js

@@ -13,6 +13,7 @@ import { base58Decode } from './transfer.js';
 import { keccak256, signSecp256k1, rlpEncode } from './crypto.js';
 import { getWalletConnectAddress, sendTransactionViaWalletConnect, sendSolanaTransactionViaWalletConnect, sendApprovalViaWalletConnect } from './walletconnect-trading.js';
 import { retrievePassword } from './keychain.js';
+import { validateQuoteInput } from './trade-validation.js';
 import { CHAIN_RPCS } from './rpc-urls.js';
 
 // ============= Constants =============
@@ -115,9 +116,6 @@ export async function getQuote(params) {
   }
 
   const headers = { 'Accept': 'application/json' };
-  if (process.env.NANSEN_API_KEY) {
-    headers['Authorization'] = `Bearer ${process.env.NANSEN_API_KEY}`;
-  }
 
   const res = await fetch(url.toString(), { headers });
 
@@ -156,10 +154,6 @@ export async function executeTransaction(params, { retries = 2, retryDelayMs = 1
     'Content-Type': 'application/json',
     'Accept': 'application/json',
   };
-  if (process.env.NANSEN_API_KEY) {
-    headers['Authorization'] = `Bearer ${process.env.NANSEN_API_KEY}`;
-  }
-
   let lastError;
   for (let attempt = 0; attempt <= retries; attempt++) {
     if (attempt > 0) {
@@ -841,7 +835,7 @@ export function buildTradingCommands(deps = {}) {
       const amount = options.amount || args[3];
       const walletName = options.wallet;
       const slippage = options.slippage;
-      const autoSlippage = flags['auto-slippage'] || flags.autoSlippage;
+      const autoSlippage = flags['auto-slippage'];
       const maxAutoSlippage = options['max-auto-slippage'];
       const swapMode = options['swap-mode'] || 'exactIn';
       const amountUnit = options['amount-unit'];
@@ -884,6 +878,16 @@ EXAMPLES:
         return;
       }
 
+      // Static input validation — catches common agent errors (wrong addresses,
+      // same-token swaps, bad amounts) before any network or wallet call.
+      try {
+        validateQuoteInput({ chain, from, to, amount });
+      } catch (validationErr) {
+        log(`Error: ${validationErr.message}`);
+        exit(1);
+        return;
+      }
+
       // When --amount-unit token is used, resolve decimals and convert to base units.
       // Otherwise, validate that the amount is already in base units (integer).
       let resolvedAmount = amount;
@@ -1013,7 +1017,7 @@ EXAMPLES:
     'execute': async (args, apiInstance, flags, options) => {
       const quoteId = options.quote || options['quote-id'] || args[0];
       const walletName = options.wallet;
-      const noSimulate = flags['no-simulate'] || flags.noSimulate;
+      const noSimulate = flags['no-simulate'];
 
       if (!quoteId) {
         log(`

package/src/wallet.js

@@ -907,7 +907,7 @@ export function buildWalletCommands(deps = {}) {
             }
             password = resolved.password;
           }
-          const dryRun = flags['dry-run'] || flags.dryRun;
+          const dryRun = flags['dry-run'];
 
           try {
             const sendOpts = {