nansen-cli 1.21.0 → 1.23.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 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
+
+- [#336](https://github.com/nansen-ai/nansen-cli/pull/336) [`c3b1fbd`](https://github.com/nansen-ai/nansen-cli/commit/c3b1fbdee46c15326a1656bf27a314f6c55dddf8) Thanks [@kome12](https://github.com/kome12)! - Add --label option to `token flows` command to filter by holder segment (top_100_holders, smart_money, public_figure, whale, exchange).
+
+- [#334](https://github.com/nansen-ai/nansen-cli/pull/334) [`83244c6`](https://github.com/nansen-ai/nansen-cli/commit/83244c658d4ece2072dea0c6ed405a088c98aa4f) Thanks [@kome12](https://github.com/kome12)! - Add `--include-stablecoins` flag to `token screener` command. Pass `--include-stablecoins false` to exclude stablecoins from screener results (API default is `true`). Supports combined usage with `--smart-money`.
+
+- [#339](https://github.com/nansen-ai/nansen-cli/pull/339) [`27ebcfc`](https://github.com/nansen-ai/nansen-cli/commit/27ebcfc2a3afd836db595df6d5a2a5f9242b624c) Thanks [@TimNooren](https://github.com/TimNooren)! - Add --amount-unit token flag to trade quote for human-readable amounts
+
 ## 1.21.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.21.0",
+  "version": "1.23.0",
   "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/skills/nansen-trading/SKILL.md

@@ -58,9 +58,16 @@ nansen trade execute --quote "$quote_id"
 | ETH | Base | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` |
 | USDC | Base | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
 
-## Amounts are in base units — NEVER USD
+## Amounts
 
-`--amount` accepts **integer base units only** (lamports, wei, etc). It is never a USD value.
+By default, `--amount` accepts **integer base units** (lamports, wei, etc). Use `--amount-unit token` to specify human-readable token amounts instead — the CLI resolves decimals locally and sends base units to the API.
+
+```bash
+# Base units (default)
+nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
+# Token units (0.5 SOL = 500000000 lamports, resolved automatically)
+nansen trade quote --chain solana --from SOL --to USDC --amount 0.5 --amount-unit token
+```
 
 | Token | Decimals | 1 token = |
 |-------|----------|-----------|
@@ -68,7 +75,7 @@ nansen trade execute --quote "$quote_id"
 | ETH | 18 | `1000000000000000000` |
 | USDC | 6 | `1000000` |
 
-If the user says "$20 worth of X", you must convert USD → token amount → base units. For example, to buy $20 of SOL at $150/SOL: $20 ÷ $150 = 0.1333 SOL = 133,300,000 lamports → `--amount 133300000`. Use a price lookup (e.g. `nansen research token info`) to get the current price first.
+If the user says "$20 worth of X", you must convert USD → token amount, then either pass base units or use `--amount-unit token`. For example, to buy $20 of SOL at $150/SOL: $20 ÷ $150 = 0.1333 SOL → `--amount 0.1333 --amount-unit token`. Use a price lookup (e.g. `nansen research token info`) to get the current price first.
 
 ## Flags
 
@@ -77,7 +84,8 @@ If the user says "$20 worth of X", you must convert USD → token amount → bas
 | `--chain` | `solana` or `base` |
 | `--from` | Source token (symbol or address) |
 | `--to` | Destination token (symbol or address) |
-| `--amount` | Amount in base units (integer) |
+| `--amount` | Amount in base units (integer), or token units with `--amount-unit token` |
+| `--amount-unit` | Set to `token` to specify amount in token units (e.g. 0.5 SOL) |
 | `--wallet` | Wallet name (default: default wallet) |
 | `--slippage` | Slippage tolerance as decimal (e.g. 0.03) |
 | `--quote` | Quote ID for execute |

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)
  */
@@ -974,7 +987,7 @@ export class NansenAPI {
   }
 
   async tokenFlows(params = {}) {
-    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination, days = 30, date } = params;
+    const { tokenAddress, chain = 'solana', label, filters = {}, orderBy, pagination, days = 30, date } = params;
     if (tokenAddress) {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
@@ -984,6 +997,7 @@ export class NansenAPI {
       token_address: tokenAddress,
       chain,
       date: dateRange,
+      label,
       filters,
       order_by: orderBy,
       pagination
@@ -1029,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);
@@ -1038,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 || {};
@@ -1200,10 +1200,15 @@ export function buildCommands(deps = {}) {
       // Convenience filter for smart money only
       const onlySmartMoney = options['smart-money'] || flags['smart-money'] || false;
       if (onlySmartMoney) {
-        filters.include_smart_money_labels = filters.include_smart_money_labels || 
+        filters.include_smart_money_labels = filters.include_smart_money_labels ||
           ['Fund', 'Smart Trader', '30D Smart Trader', '90D Smart Trader', '180D Smart Trader'];
       }
 
+      const includeStablecoins = options['include-stablecoins'] ?? flags['include-stablecoins'];
+      if (includeStablecoins !== undefined) {
+        filters.include_stablecoins = includeStablecoins;
+      }
+
       const handlers = {
         'indicators': () => apiInstance.tokenIndicators({ tokenAddress, chain }),
         'ohlcv': () => apiInstance.tokenOhlcv({ tokenAddress, chain, timeframe: options.timeframe || '1d' }),
@@ -1235,13 +1240,15 @@ export function buildCommands(deps = {}) {
         'holders': () => apiInstance.tokenHolders({ tokenAddress, chain, labelType: onlySmartMoney ? 'smart_money' : 'all_holders', filters, orderBy, pagination }),
         'flows': () => {
           const date = parseDateOption(options.date, days);
-          return apiInstance.tokenFlows({ tokenAddress, chain, filters, orderBy, pagination, days, date });
+          const label = options.label;
+          return apiInstance.tokenFlows({ tokenAddress, chain, label, filters, orderBy, pagination, days, date });
         },
         'dex-trades': () => apiInstance.tokenDexTrades({ tokenAddress, chain, onlySmartMoney, filters, orderBy, pagination, days }),
         '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': () => {
@@ -1257,7 +1264,7 @@ export function buildCommands(deps = {}) {
         'help': () => ({
           commands: ['info', 'ohlcv', 'screener', 'holders', 'flows', 'dex-trades', 'pnl', 'who-bought-sold', 'flow-intelligence', 'transfers', 'jup-dca', 'perp-trades', 'perp-positions', 'perp-pnl-leaderboard'],
           description: 'Token God Mode endpoints',
-          example: 'nansen token screener --chain solana --timeframe 24h --smart-money'
+          example: 'nansen token screener --chain solana --timeframe 24h --smart-money --include-stablecoins false'
         })
       };
 

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
@@ -565,6 +566,14 @@ USAGE:
         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 +617,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 +716,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

@@ -280,6 +280,11 @@
                 },
                 "days": {
                   "default": 30
+                },
+                "label": {
+                  "description": "Holder segment to filter flows by",
+                  "enum": ["top_100_holders", "smart_money", "public_figure", "whale", "exchange"],
+                  "default": "top_100_holders"
                 }
               }
             },
@@ -295,6 +300,11 @@
                 },
                 "days": {
                   "default": 30
+                },
+                "buy-or-sell": {
+                  "description": "Filter by buy or sell side",
+                  "enum": ["BUY", "SELL"],
+                  "default": "BUY"
                 }
               }
             },
@@ -463,6 +473,10 @@
                 },
                 "chain": {
                   "default": "solana"
+                },
+                "include-stablecoins": {
+                  "description": "Whether to include stablecoins in screener results (default true on API side)",
+                  "default": true
                 }
               }
             }
@@ -660,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."
@@ -701,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."
@@ -762,7 +792,11 @@
             "amount": {
               "type": "string",
               "required": true,
-              "description": "Amount to swap"
+              "description": "Amount to swap (base units by default, or token units with --amount-unit token)"
+            },
+            "amount-unit": {
+              "type": "string",
+              "description": "\"token\" to specify amount in token units (e.g. 0.5 SOL), or \"base\" for base units (default). Decimals are resolved locally and the API always receives base units."
             },
             "wallet": {
               "type": "string",

package/src/trading.js

@@ -115,9 +115,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 +153,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) {
@@ -683,6 +676,101 @@ export function getWrappedNativeFromWarning(tokenAddress, chain) {
   return null;
 }
 
+// ============= Token Decimal Resolution =============
+
+// Hardcoded decimals for well-known tokens — avoids RPC calls in the common case.
+const KNOWN_DECIMALS = {
+  // Solana
+  'So11111111111111111111111111111111111111112': 9,   // SOL/WSOL
+  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v': 6, // USDC
+  'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB': 6,  // USDT
+  // Base (EVM) — lowercase for case-insensitive matching
+  '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee': 18, // ETH native
+  '0x4200000000000000000000000000000000000006': 18, // WETH
+  '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': 6, // USDC
+  '0xfde4c96c8593536e31f229ea8f37b2ada2699bb2': 6, // USDT
+};
+
+/**
+ * Resolve the number of decimals for a token.
+ * Checks a hardcoded map first, then falls back to an RPC call.
+ * Solana: getAccountInfo with jsonParsed encoding.
+ * EVM: eth_call to decimals() selector 0x313ce567.
+ */
+export async function resolveTokenDecimals(tokenAddress, chainName) {
+  // Normalise for map lookup (EVM addresses are case-insensitive)
+  const key = tokenAddress.startsWith('0x') ? tokenAddress.toLowerCase() : tokenAddress;
+  if (KNOWN_DECIMALS[key] !== undefined) return KNOWN_DECIMALS[key];
+
+  const chain = chainName.toLowerCase();
+  const chainConfig = CHAIN_MAP[chain];
+  if (!chainConfig) throw new Error(`Unknown chain: ${chain}`);
+
+  // Validate address format before making RPC calls.
+  // A bare symbol like "SOL" that didn't resolve means it's not recognized on this chain.
+  if (chainConfig.type === 'solana') {
+    if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(tokenAddress)) {
+      throw new Error(`"${tokenAddress}" is not a recognized token on ${chainName}. Use a valid Solana address (base58, 32-44 chars).`);
+    }
+  } else {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(tokenAddress)) {
+      throw new Error(`"${tokenAddress}" is not a recognized token on ${chainName}. Use a valid EVM address (0x + 40 hex chars).`);
+    }
+  }
+
+  if (chainConfig.type === 'solana') {
+    const rpcUrl = CHAIN_RPCS.solana;
+    const res = await fetch(rpcUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getAccountInfo', params: [tokenAddress, { encoding: 'jsonParsed' }] }),
+    });
+    const body = await res.json();
+    const decimals = body.result?.value?.data?.parsed?.info?.decimals;
+    if (decimals === undefined) throw new Error(`Could not resolve decimals for Solana token ${tokenAddress}`);
+    return decimals;
+  }
+
+  // EVM — eth_call to decimals()
+  const result = await evmRpcCall(chain, 'eth_call', [{ to: tokenAddress, data: '0x313ce567' }, 'latest']);
+  const decimals = parseInt(result, 16);
+  if (isNaN(decimals) || decimals > 255) throw new Error(`Could not resolve decimals for EVM token ${tokenAddress}`);
+  return decimals;
+}
+
+/**
+ * Convert a human-readable token amount to base units using string math.
+ * Avoids floating-point precision issues by operating on digit strings.
+ * Example: convertToBaseUnits('0.5', 9) => '500000000'
+ */
+export function convertToBaseUnits(amount, decimals) {
+  const str = String(amount);
+  if (!/^\d+(\.\d+)?$/.test(str)) {
+    throw new Error(`Invalid amount: "${str}". Must be a non-negative number (e.g. "0.5", "100").`);
+  }
+  const dotIndex = str.indexOf('.');
+  if (dotIndex === -1) {
+    // Whole number — append zeros and strip leading zeros
+    const raw = str + '0'.repeat(decimals);
+    return raw.replace(/^0+/, '') || '0';
+  }
+  const whole = str.slice(0, dotIndex);
+  let frac = str.slice(dotIndex + 1);
+  if (frac.length > decimals) {
+    // Reject if meaningful (non-zero) digits would be lost
+    const excess = frac.slice(decimals);
+    if (/[1-9]/.test(excess)) {
+      throw new Error(`Amount "${str}" has more fractional digits than the token supports (${decimals} decimals). The smallest unit is ${decimals === 0 ? '1 token' : '0.' + '0'.repeat(decimals - 1) + '1'}.`);
+    }
+    frac = frac.slice(0, decimals);
+  } else {
+    frac = frac.padEnd(decimals, '0');
+  }
+  // Strip leading zeros from the combined result
+  const raw = (whole + frac).replace(/^0+/, '') || '0';
+  return raw;
+}
+
 /**
  * Check if amount contains a decimal point (i.e. not in base units).
  * Returns an error string if invalid, or null if OK. Pure function.
@@ -690,8 +778,12 @@ export function getWrappedNativeFromWarning(tokenAddress, chain) {
 export function validateBaseUnitAmount(amount) {
   if (!amount) return null;
   const str = String(amount);
+  if (str.startsWith('-')) {
+    return 'Amount cannot be negative. Got: ' + str;
+  }
   if (str.includes('.')) {
-    return 'Amount must be in base units (integer), not token units. ' +
+    return 'Amount must be in base units (integer). ' +
+      'Use --amount-unit token to specify token amounts (e.g. --amount 0.5 --amount-unit token). ' +
       'Examples: 1000000000 lamports = 1 SOL, 1000000000000000000 wei = 1 ETH, ' +
       '1000000 = 1 USDC. Got: ' + str;
   }
@@ -742,9 +834,10 @@ 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'];
 
       if (!chain || !from || !to || !amount) {
         log(`
@@ -760,6 +853,7 @@ OPTIONS:
   --from <symbol|address>   Input token (symbol like SOL, USDC or address)
   --to <symbol|address>     Output token (symbol like USDC, ETH or address)
   --amount <units>          Amount in BASE UNITS (e.g. lamports, wei)
+  --amount-unit <unit>      "token" to specify amount in token units (e.g. 0.5 SOL)
   --wallet <name>           Wallet name (default: default wallet). Use "walletconnect" or "wc" for WalletConnect.
   --slippage <pct>          Slippage as decimal (e.g. 0.03 for 3%). Default: 0.03
   --auto-slippage           Enable auto slippage calculation
@@ -768,6 +862,7 @@ OPTIONS:
 
 EXAMPLES:
   nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
+  nansen trade quote --chain solana --from SOL --to USDC --amount 0.5 --amount-unit token
   nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
   nansen trade quote --chain solana --from So11111111111111111111111111111111111111112 --to EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --amount 1000000000
 `);
@@ -775,13 +870,35 @@ EXAMPLES:
         return;
       }
 
-      const amountError = validateBaseUnitAmount(amount);
-      if (amountError) {
-        log(`Error: ${amountError}`);
+      // Validate --amount-unit if provided
+      if (amountUnit && amountUnit !== 'token' && amountUnit !== 'base') {
+        log(`Error: Unknown --amount-unit "${amountUnit}". Supported values: token, base`);
         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;
+      if (amountUnit === 'token') {
+        try {
+          const tokenForDecimals = swapMode === 'exactOut' ? to : from;
+          const decimals = await resolveTokenDecimals(tokenForDecimals, chain);
+          resolvedAmount = convertToBaseUnits(amount, decimals);
+        } catch (err) {
+          log(`Error resolving token decimals: ${err.message}`);
+          exit(1);
+          return;
+        }
+      } else {
+        const amountError = validateBaseUnitAmount(amount);
+        if (amountError) {
+          log(`Error: ${amountError}`);
+          exit(1);
+          return;
+        }
+      }
+
       try {
         const chainConfig = resolveChain(chain);
         const chainType = chainConfig.type === 'evm' ? 'evm' : 'solana';
@@ -837,7 +954,7 @@ EXAMPLES:
           chainIndex: chainConfig.index,
           fromTokenAddress: from,
           toTokenAddress: to,
-          amount,
+          amount: resolvedAmount,
           userWalletAddress: walletAddress,
         };
         if (slippage) params.slippagePercent = slippage;
@@ -889,7 +1006,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 = {