nansen-cli 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.14.0
+
+### Minor Changes
+
+- [#231](https://github.com/nansen-ai/nansen-cli/pull/231) [`c3968da`](https://github.com/nansen-ai/nansen-cli/commit/c3968dacb52521235ad6502321650148ac825d01) Thanks [@araa47](https://github.com/araa47)! - Agent-first secure wallet flow — OS keychain persistence, no interactive prompts
+
+  - **New `src/keychain.js`**: Password persistence via OS keychain (macOS Keychain / Linux secret-tool), with base64-encoded `.credentials` file fallback for containers/CI. Zero npm dependencies.
+  - **Non-interactive by default**: All readline prompts removed. Agents get structured JSON errors (`PASSWORD_REQUIRED`, `API_KEY_REQUIRED`) with actionable instructions. `--human` flag re-enables interactive mode.
+  - **Two-step wallet creation**: Agent asks user for password, runs `NANSEN_WALLET_PASSWORD=<pw> nansen wallet create`. Password auto-persists to keychain — all future operations are passwordless.
+  - **New commands**: `wallet secure` (migrate to keychain), `wallet forget-password` (clear from all stores).
+  - **Bug fixes**: Clear `passwordHash` on last wallet delete, verify password before keychain writes, exit non-zero when keychain migration fails, source-aware error messages.
+  - **New skill**: `nansen-wallet-migration` for migrating from old `~/.nansen/.env` storage to keychain.
+
+## 1.13.1
+
+### Patch Changes
+
+- [#225](https://github.com/nansen-ai/nansen-cli/pull/225) [`051e4a3`](https://github.com/nansen-ai/nansen-cli/commit/051e4a353641d000facd2133810c059981b9ac7f) Thanks [@TimNooren](https://github.com/TimNooren)! - Remove "recommended, lower fees" label from Base network in wallet create output
+
 ## 1.13.0
 
 ### Minor Changes

package/package.json

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

package/src/api.js

@@ -6,6 +6,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { EVM_CHAINS } from './chain-ids.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -255,12 +256,6 @@ const ADDRESS_PATTERNS = {
   bitcoin: /^(1|3|bc1)[a-zA-HJ-NP-Z0-9]{25,62}$/,
 };
 
-const EVM_CHAINS = [
-  'ethereum', 'arbitrum', 'base', 'bnb', 'polygon', 'optimism',
-  'avalanche', 'linea', 'scroll', 'mantle', 'ronin',
-  'sei', 'plasma', 'sonic', 'monad', 'hyperevm', 'iotaevm'
-];
-
 /**
  * Validate address format for a given chain
  * @param {string} address - The address to validate

package/src/chain-ids.js

@@ -17,3 +17,14 @@ export const EVM_CHAIN_IDS = {
   zksync: 324,
   mantle: 5000,
 };
+
+/**
+ * All EVM chain names recognised by this CLI.
+ * Used for address-format validation (0x...) and ENS resolution gating.
+ * Import from here instead of defining an inline list per file.
+ */
+export const EVM_CHAINS = [
+  'ethereum', 'arbitrum', 'base', 'bnb', 'polygon', 'optimism',
+  'avalanche', 'linea', 'scroll', 'zksync', 'mantle', 'ronin',
+  'sei', 'plasma', 'sonic', 'unichain', 'monad', 'hyperevm', 'iotaevm',
+];

package/src/cli.js

@@ -163,7 +163,7 @@ export function parseArgs(args) {
       const key = arg.slice(2);
       const next = args[i + 1];
       
-      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full') {
+      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full' || key === 'human') {
         result.flags[key] = true;
       } else if (next && !next.startsWith('-')) {
         // Try to parse as JSON first (for objects/arrays/booleans),
@@ -669,8 +669,8 @@ USAGE: nansen <command> [subcommand] [options]
 COMMANDS:
   research    smart-money, profiler, token, search, perp, portfolio, points
   trade       quote, execute
-  wallet      create, list, show, export, default, delete
-  login       Save API key (--api-key <key> or interactive)
+  wallet      create, list, show, export, default, delete, forget-password
+  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)
   cache       clear
@@ -684,7 +684,7 @@ 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 base --from ETH --to USDC --amount 1
+  nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
 
 Research chains: ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, zksync, mantle, ronin, sei, plasma, sonic, unichain, monad, hyperevm, iotaevm
 Trade chains: solana, base
@@ -761,43 +761,51 @@ export function buildCommands(deps = {}) {
       if (flags.help || flags.h) {
         log('nansen login - Save your Nansen API key\n');
         log('USAGE:');
-        log('  nansen login                    (interactive)');
-        log('  nansen login --api-key <key>    (non-interactive)\n');
+        log('  nansen login --api-key <key>');
+        log('  NANSEN_API_KEY=<key> nansen login');
+        log('  nansen login --human              (interactive prompt)\n');
         log('OPTIONS:');
         log('  --api-key <key>   Your Nansen API key');
+        log('  --human           Enable interactive prompt');
         log('  --help            Show this help\n');
         log('Get your API key at: https://app.nansen.ai/api');
         return;
       }
 
-      // Support non-interactive: nansen login --api-key <key>
       let apiKey = options['api-key'] || options.apiKey;
 
       if (!apiKey) {
-        if (!isTTY) {
-          // Non-interactive mode: check env var fallback
-          apiKey = process.env.NANSEN_API_KEY;
-          if (!apiKey) {
-            log('❌ No API key provided. Use: nansen login --api-key <key>\n   Or set NANSEN_API_KEY environment variable.\n   Get your API key at: https://app.nansen.ai/api');
-            exit(1);
-            return;
-          }
-        } else {
-          log('Nansen CLI Login\n');
-          log('Get your API key at: https://app.nansen.ai/api\n');
-          log('Tip: For non-interactive use: nansen login --api-key <key>\n');
+        apiKey = process.env.NANSEN_API_KEY;
+      }
 
-          apiKey = await promptFn('Enter your API key: ', true);
+      if (!apiKey && flags.human) {
+        if (!isTTY) {
+          log(JSON.stringify({
+            error: 'NOT_A_TTY',
+            message: '--human requires an interactive terminal. Use --api-key or NANSEN_API_KEY env var instead.',
+          }));
+          exit(1);
+          return;
         }
+        log('Nansen CLI Login\n');
+        log('Get your API key at: https://app.nansen.ai/api\n');
+        apiKey = await promptFn('Enter your API key: ', true);
       }
 
       if (!apiKey || apiKey.trim().length === 0) {
-        log('\n❌ No API key provided');
+        log(JSON.stringify({
+          error: 'API_KEY_REQUIRED',
+          message: 'No API key provided.',
+          resolution: [
+            'Run: nansen login --api-key <key>',
+            'Or set NANSEN_API_KEY environment variable',
+            'Get your API key at: https://app.nansen.ai/api',
+          ],
+        }));
         exit(1);
         return;
       }
 
-      // Save the config without validation
       saveConfigFn({
         apiKey: apiKey.trim(),
         baseUrl: 'https://api.nansen.ai'

package/src/ens.js

@@ -6,15 +6,10 @@
 
 import https from 'https';
 import { keccak256 } from './crypto.js';
+import { EVM_CHAINS } from './chain-ids.js';
 
 const ENS_PATTERN = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?\.eth$/;
 
-const EVM_CHAINS = [
-  'ethereum', 'base', 'optimism', 'arbitrum', 'polygon', 'bnb',
-  'avalanche', 'fantom', 'gnosis', 'linea', 'scroll', 'zksync',
-  'blast', 'mantle', 'ronin', 'sei', 'plasma', 'sonic', 'unichain', 'monad', 'hyperevm', 'iotaevm'
-];
-
 /**
  * Check if a string looks like an ENS name
  */

package/src/keychain.js

@@ -0,0 +1,229 @@
+/**
+ * Nansen CLI - Password Persistence
+ * Stores/retrieves the wallet password, preferring the native OS credential
+ * store and falling back to a base64-encoded credentials file (not encrypted).
+ *
+ * Resolution order (read):
+ *   1. NANSEN_WALLET_PASSWORD env var
+ *   2. OS keychain (macOS Keychain / Linux secret-tool / Windows cmdkey)
+ *   3. ~/.nansen/wallets/.credentials file (insecure fallback)
+ *
+ * Storage order (write):
+ *   1. Try OS keychain first
+ *   2. Fall back to ~/.nansen/wallets/.credentials (chmod 600)
+ *
+ * Zero npm dependencies — uses native OS commands via child_process.
+ */
+
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+const SERVICE = 'nansen-cli';
+const ACCOUNT = 'wallet-password';
+const TIMEOUT_MS = 5000;
+
+function getCredentialsPath() {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  return path.join(home, '.nansen', 'wallets', '.credentials');
+}
+
+// ============= OS Keychain =============
+
+function keychainStore(password) {
+  try {
+    if (process.platform === 'darwin') {
+      // macOS `security` CLI requires -w <password> as argv — no stdin mode.
+      // Unlike secret-tool, omitting the value prompts from the TTY, not stdin.
+      // Exposure in process listings is brief (sub-second, execFileSync is synchronous).
+      execFileSync('/usr/bin/security', [
+        'add-generic-password',
+        '-s', SERVICE,
+        '-a', ACCOUNT,
+        '-w', password,
+        '-U',
+      ], { timeout: TIMEOUT_MS, stdio: 'pipe' });
+      return true;
+    }
+
+    if (process.platform === 'linux') {
+      execFileSync('secret-tool', [
+        'store',
+        '--label', SERVICE,
+        'service', SERVICE,
+        'account', ACCOUNT,
+      ], { input: password, timeout: TIMEOUT_MS, stdio: ['pipe', 'pipe', 'pipe'] });
+      return true;
+    }
+
+    // Windows: no reliable built-in CLI for credential read-back.
+    // cmdkey stores but can't retrieve passwords. Falls through to .credentials file.
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+function keychainRetrieve() {
+  try {
+    if (process.platform === 'darwin') {
+      const result = execFileSync('/usr/bin/security', [
+        'find-generic-password',
+        '-s', SERVICE,
+        '-a', ACCOUNT,
+        '-w',
+      ], { timeout: TIMEOUT_MS, stdio: ['pipe', 'pipe', 'pipe'] });
+      const pw = result.toString().trim();
+      return pw || null;
+    }
+
+    if (process.platform === 'linux') {
+      const result = execFileSync('secret-tool', [
+        'lookup',
+        'service', SERVICE,
+        'account', ACCOUNT,
+      ], { timeout: TIMEOUT_MS, stdio: ['pipe', 'pipe', 'pipe'] });
+      const pw = result.toString().trim();
+      return pw || null;
+    }
+
+    // Windows: no reliable built-in CLI for credential read-back.
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function keychainDeleteEntry() {
+  try {
+    if (process.platform === 'darwin') {
+      execFileSync('/usr/bin/security', [
+        'delete-generic-password',
+        '-s', SERVICE,
+        '-a', ACCOUNT,
+      ], { timeout: TIMEOUT_MS, stdio: 'pipe' });
+      return true;
+    }
+
+    if (process.platform === 'linux') {
+      execFileSync('secret-tool', [
+        'clear',
+        'service', SERVICE,
+        'account', ACCOUNT,
+      ], { timeout: TIMEOUT_MS, stdio: 'pipe' });
+      return true;
+    }
+
+    // Windows: no keychain entries to delete (uses .credentials file).
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// ============= Credentials File Fallback =============
+
+function credentialsFileRead() {
+  try {
+    const filePath = getCredentialsPath();
+    if (!fs.existsSync(filePath)) return null;
+    const content = fs.readFileSync(filePath, 'utf8').trim();
+    // New format: base64-encoded (handles passwords with newlines/special chars)
+    const b64Match = content.match(/^NANSEN_WALLET_PASSWORD_B64=(.+)$/m);
+    if (b64Match) return Buffer.from(b64Match[1].trim(), 'base64').toString('utf8');
+    // Legacy format: plain text (backward compat)
+    const match = content.match(/^NANSEN_WALLET_PASSWORD=(.+)$/m);
+    return match ? match[1].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function credentialsFileWrite(password) {
+  try {
+    const filePath = getCredentialsPath();
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { mode: 0o700, recursive: true });
+    }
+    const encoded = Buffer.from(password, 'utf8').toString('base64');
+    fs.writeFileSync(filePath, `NANSEN_WALLET_PASSWORD_B64=${encoded}\n`, { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function credentialsFileDelete() {
+  try {
+    const filePath = getCredentialsPath();
+    if (!fs.existsSync(filePath)) return false;
+    fs.unlinkSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ============= Public API =============
+
+/**
+ * Store a password. Tries OS keychain first, falls back to .credentials file.
+ * @param {string} password
+ * @returns {{ stored: boolean, method: 'keychain'|'file'|'none' }}
+ */
+export function storePassword(password) {
+  if (keychainStore(password)) {
+    return { stored: true, method: 'keychain' };
+  }
+  if (credentialsFileWrite(password)) {
+    return { stored: true, method: 'file' };
+  }
+  return { stored: false, method: 'none' };
+}
+
+/**
+ * Retrieve the wallet password from OS keychain or .credentials file.
+ * @returns {{ password: string|null, source: 'env'|'keychain'|'file'|null }}
+ */
+export function retrievePassword() {
+  const envPw = process.env.NANSEN_WALLET_PASSWORD;
+  if (envPw) return { password: envPw, source: 'env' };
+
+  const keychainPw = keychainRetrieve();
+  if (keychainPw) return { password: keychainPw, source: 'keychain' };
+
+  const filePw = credentialsFileRead();
+  if (filePw) return { password: filePw, source: 'file' };
+
+  return { password: null, source: null };
+}
+
+/**
+ * Delete the wallet password from all stores.
+ * @returns {{ keychain: boolean, file: boolean }}
+ */
+export function deletePassword() {
+  return {
+    keychain: keychainDeleteEntry(),
+    file: credentialsFileDelete(),
+  };
+}
+
+/**
+ * Delete only the .credentials file (not the keychain entry).
+ * Used by `wallet secure` after migrating to keychain.
+ * @returns {boolean}
+ */
+export function deleteCredentialsFile() {
+  return credentialsFileDelete();
+}
+
+/**
+ * Resolve the wallet password from available sources.
+ * Order: env var → OS keychain → .credentials file → null
+ * @returns {string|null}
+ */
+export function resolvePassword() {
+  return retrievePassword().password;
+}

package/src/schema.json

@@ -1879,11 +1879,13 @@
     "avalanche",
     "linea",
     "scroll",
+    "zksync",
     "mantle",
     "ronin",
     "sei",
     "plasma",
     "sonic",
+    "unichain",
     "monad",
     "hyperevm",
     "iotaevm"

package/src/trading.js

@@ -12,6 +12,7 @@ import { exportWallet, getDefaultAddress, showWallet, listWallets, getWalletConf
 import { base58Decode } from './transfer.js';
 import { keccak256, signSecp256k1, rlpEncode } from './crypto.js';
 import { getWalletConnectAddress, sendTransactionViaWalletConnect, sendApprovalViaWalletConnect } from './walletconnect-trading.js';
+import { retrievePassword } from './keychain.js';
 
 // ============= Constants =============
 
@@ -652,31 +653,15 @@ export function getWalletChainType(chainName) {
 
 // ============= CLI Helpers =============
 
-async function promptPassword(prompt, deps = {}) {
-  if (deps.promptFn) return deps.promptFn(prompt);
-  const readline = await import('readline');
-  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
-  return new Promise((resolve) => {
-    process.stderr.write(prompt);
-    let input = '';
-    const stdin = process.stdin;
-    const wasRaw = stdin.isRaw;
-    if (stdin.setRawMode) stdin.setRawMode(true);
-    stdin.resume();
-    const onData = (ch) => {
-      const c = ch.toString();
-      if (c === '\n' || c === '\r') {
-        if (stdin.setRawMode) stdin.setRawMode(wasRaw || false);
-        stdin.removeListener('data', onData);
-        process.stderr.write('\n');
-        rl.close();
-        resolve(input);
-      } else if (c === '\u0003') { rl.close(); process.exit(1); }
-      else if (c === '\u007f' || c === '\b') { input = input.slice(0, -1); }
-      else { input += c; }
-    };
-    stdin.on('data', onData);
-  });
+function resolveTradePassword() {
+  const { password, source } = retrievePassword();
+  if (source === 'file') {
+    process.stderr.write(
+      '⚠️  Password loaded from ~/.nansen/wallets/.credentials (insecure — plaintext on disk).\n' +
+      '   For better security, migrate to OS keychain: nansen wallet secure\n'
+    );
+  }
+  return password;
 }
 
 function isNativeToken(mintAddress) {
@@ -958,9 +943,22 @@ EXAMPLES:
         if (!isWalletConnect) {
           // Get wallet credentials once (before the loop)
           const walletConfig = getWalletConfig();
-          const password = walletConfig.passwordHash
-            ? (process.env.NANSEN_WALLET_PASSWORD || await promptPassword('Enter wallet password: ', deps))
-            : null;
+          let password = null;
+          if (walletConfig.passwordHash) {
+            password = resolveTradePassword();
+            if (!password) {
+              log(JSON.stringify({
+                error: 'PASSWORD_REQUIRED',
+                message: 'Wallet is encrypted and no password was found.',
+                resolution: [
+                  'Set NANSEN_WALLET_PASSWORD environment variable',
+                  'Or run: nansen wallet create (password is saved to OS keychain automatically)',
+                ],
+              }));
+              exit(1);
+              return;
+            }
+          }
 
           let effectiveWalletName = walletName;
           if (!effectiveWalletName) {

package/src/wallet.js

@@ -8,6 +8,7 @@ import fs from 'fs';
 import path from 'path';
 import * as readline from 'readline';
 import { base58 } from '@scure/base';
+import { storePassword, retrievePassword, deletePassword, deleteCredentialsFile } from './keychain.js';
 
 // ============= Constants =============
 
@@ -265,7 +266,7 @@ async function promptPassword(question, deps = {}) {
   if (promptFn) {
     return promptFn(question, true);
   }
-  // Fallback to readline
+  // Fallback to readline (only available in --human mode)
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
     if (process.stdout.isTTY) {
@@ -298,6 +299,60 @@ async function promptPassword(question, deps = {}) {
   });
 }
 
+/**
+ * Resolve wallet password from all available sources (non-interactive).
+ * Order: NANSEN_WALLET_PASSWORD env var → OS keychain → .credentials file → null
+ * Emits a warning to stderr when using the insecure .credentials file.
+ * @returns {string|null}
+ */
+function resolveWalletPassword() {
+  const { password, source } = retrievePassword();
+  if (source === 'file') {
+    process.stderr.write(
+      '⚠️  Password loaded from ~/.nansen/wallets/.credentials (insecure — plaintext on disk).\n' +
+      '   For better security, migrate to OS keychain: nansen wallet secure\n' +
+      '   Or set NANSEN_WALLET_PASSWORD via a secrets manager.\n'
+    );
+  }
+  return password;
+}
+
+/**
+ * Resolve wallet password for a command. If --human flag is set and no
+ * password found, falls back to interactive prompt. Otherwise returns
+ * structured error info for agents.
+ *
+ * @param {object} config - wallet config (needs config.passwordHash)
+ * @param {object} flags - CLI flags
+ * @param {object} deps - { promptFn, log, exit }
+ * @returns {{ password: string|null, error: string|null }}
+ */
+async function resolvePasswordForCommand(config, flags, deps) {
+  if (!config.passwordHash) {
+    return { password: null, error: null };
+  }
+
+  const password = resolveWalletPassword();
+  if (password) return { password, error: null };
+
+  if (flags.human && (process.stdin.isTTY || deps.promptFn)) {
+    const prompted = await promptPassword('Enter wallet password: ', deps);
+    if (prompted) return { password: prompted, error: null };
+  }
+
+  return {
+    password: null,
+    error: JSON.stringify({
+      error: 'PASSWORD_REQUIRED',
+      message: 'Wallet is encrypted and no password was found.',
+      resolution: [
+        'Set NANSEN_WALLET_PASSWORD environment variable',
+        'Or re-run wallet create with the password (it will be persisted for future use)',
+      ],
+    }),
+  };
+}
+
 // ============= Public API =============
 
 /**
@@ -468,12 +523,16 @@ export function deleteWallet(name, password) {
 
   fs.unlinkSync(walletFile);
 
-  if (config.defaultWallet === name) {
-    // Pick another wallet as default, or null
-    const remaining = fs.readdirSync(getWalletsDir()).filter(f => f.endsWith('.json') && f !== 'config.json');
-    config.defaultWallet = remaining.length > 0 ? remaining[0].replace('.json', '') : null;
-    saveWalletConfig(config);
+  const remaining = fs.readdirSync(getWalletsDir()).filter(f => f.endsWith('.json') && f !== 'config.json');
+
+  if (remaining.length === 0) {
+    config.defaultWallet = null;
+    config.passwordHash = null;
+    deletePassword();
+  } else if (config.defaultWallet === name) {
+    config.defaultWallet = remaining[0].replace('.json', '');
   }
+  saveWalletConfig(config);
 
   return { deleted: name, newDefault: config.defaultWallet };
 }
@@ -512,32 +571,74 @@ export function buildWalletCommands(deps = {}) {
           if (flags['unsafe-no-password']) {
             process.stderr.write('WARNING: --unsafe-no-password is set. Private keys will be stored UNENCRYPTED on disk.\nAnyone with access to this machine can steal your funds.\n');
             password = null;
-          } else if (!process.env.NANSEN_WALLET_PASSWORD && !process.stdin.isTTY && !deps.promptFn) {
-            log('❌ No password provided. Either:');
-            log('   set NANSEN_WALLET_PASSWORD, or');
-            log('   use --unsafe-no-password (WARNING: Private keys will be stored UNENCRYPTED on disk. Anyone with access to this machine can steal your funds.)');
-            exit(1);
-            return;
           } else {
-            password = process.env.NANSEN_WALLET_PASSWORD || await promptPassword('Enter wallet password: ', deps);
-            if (!password || password.length < 12) {
-              log('❌ Password must be at least 12 characters');
+            // Step 1: Check env var and keychain
+            password = resolveWalletPassword();
+
+            // Step 2: If --human flag, allow interactive prompt (requires TTY)
+            if (!password && flags.human && !process.stdin.isTTY && !deps.promptFn) {
+              log(JSON.stringify({
+                error: 'NOT_A_TTY',
+                message: '--human requires an interactive terminal. Set NANSEN_WALLET_PASSWORD env var instead.',
+              }));
               exit(1);
               return;
             }
-
-            // Confirm password for first wallet (skip if set via env var)
-            const config = getWalletConfig();
-            if (!config.passwordHash && !process.env.NANSEN_WALLET_PASSWORD) {
-              const confirm = await promptPassword('Confirm password: ', deps);
-              if (password !== confirm) {
-                log('❌ Passwords do not match');
+            if (!password && flags.human && (process.stdin.isTTY || deps.promptFn)) {
+              password = await promptPassword('Enter wallet password: ', deps);
+              if (password && password.length < 12) {
+                log('❌ Password must be at least 12 characters');
                 exit(1);
                 return;
               }
+              if (password) {
+                const config = getWalletConfig();
+                if (!config.passwordHash) {
+                  const confirm = await promptPassword('Confirm password: ', deps);
+                  if (password !== confirm) {
+                    log('❌ Passwords do not match');
+                    exit(1);
+                    return;
+                  }
+                }
+              }
+            }
+
+            // Step 3: No password available — return structured error for agents
+            if (!password) {
+              log(JSON.stringify({
+                error: 'PASSWORD_REQUIRED',
+                message: 'A wallet password is required. Ask the user to provide one.',
+                instructions: 'Re-run with: NANSEN_WALLET_PASSWORD=<password> nansen wallet create',
+                note: 'Password must be at least 12 characters. After creation, the password is saved to the OS keychain automatically — future operations will not require it.',
+              }));
+              exit(1);
+              return;
+            }
+
+            if (password.length < 12) {
+              log('❌ Password must be at least 12 characters');
+              exit(1);
+              return;
             }
           }
 
+          // Verify password matches existing wallets BEFORE touching keychain
+          if (password !== null) {
+            const config = getWalletConfig();
+            if (config.passwordHash && !verifyPassword(password, config)) {
+              log('❌ Incorrect password — does not match existing wallets.');
+              exit(1);
+              return;
+            }
+          }
+
+          // Persist password BEFORE creating wallet so we know the storage situation
+          let storageResult = { stored: false, method: 'none' };
+          if (password !== null) {
+            storageResult = storePassword(password);
+          }
+
           try {
             const result = createWallet(name, password);
             log(`\n✓ Wallet "${result.name}" created\n`);
@@ -546,14 +647,29 @@ export function buildWalletCommands(deps = {}) {
             if (result.isDefault) log(`  ★ Set as default wallet`);
             log('');
             log('  Fund this wallet to start making API calls or trading:');
-            log(`    Base (recommended, lower fees): send USDC to ${result.evm}`);
+            log(`    Base: send USDC to ${result.evm}`);
             log(`    Solana: send USDC to ${result.solana}`);
             log('');
             if (password === null) {
               log('  ⚠️  This is an UNENCRYPTED hot wallet — private keys are stored in plaintext on disk.');
+            } else if (storageResult.stored && storageResult.method === 'keychain') {
+              log('  ✓ Password saved to system keychain (secure).');
+              log('    Future wallet operations will retrieve the password automatically.');
+            } else if (storageResult.stored && storageResult.method === 'file') {
+              log('  ⚠️  No OS keychain available. Password saved to ~/.nansen/wallets/.credentials (insecure — plaintext on disk).');
+              log('     Future wallet operations will retrieve the password automatically.');
+              log('     To improve security: migrate to OS keychain with `nansen wallet secure`,');
+              log('     or set NANSEN_WALLET_PASSWORD via a secrets manager.');
             } else {
-              log('  ⚠️  This is a hot wallet and is fundamentally insecure — do not deposit more than you can afford to lose.');
-              log('     Store and handle your password securely, e.g. using a secrets manager or system keychain.');
+              log('  ⚠️  CRITICAL: Password could not be saved anywhere (no keychain, no writable filesystem).');
+              log('     You MUST set NANSEN_WALLET_PASSWORD in your environment for ALL future wallet operations.');
+              log('     If you lose this password, your funds are UNRECOVERABLE.');
+            }
+            if (password !== null) {
+              log('');
+              log('  IMPORTANT: Back up your password separately (e.g. password manager).');
+              log('  If you lose access to this machine AND forget the password, funds are unrecoverable.');
+              log('  This is a hot wallet — do not deposit more than you can afford to lose.');
             }
             log('');
             return;
@@ -608,9 +724,12 @@ export function buildWalletCommands(deps = {}) {
             return;
           }
           const config = getWalletConfig();
-          const password = config.passwordHash
-            ? (process.env.NANSEN_WALLET_PASSWORD || await promptPassword('Enter wallet password: ', deps))
-            : null;
+          const { password, error } = await resolvePasswordForCommand(config, flags, deps);
+          if (error) {
+            log(error);
+            exit(1);
+            return;
+          }
           try {
             const result = exportWallet(name, password);
             log(`\n⚠️  Private keys for "${result.name}" — do not share!\n`);
@@ -653,9 +772,12 @@ export function buildWalletCommands(deps = {}) {
             return;
           }
           const config = getWalletConfig();
-          const password = config.passwordHash
-            ? (process.env.NANSEN_WALLET_PASSWORD || await promptPassword('Enter wallet password: ', deps))
-            : null;
+          const { password, error } = await resolvePasswordForCommand(config, flags, deps);
+          if (error) {
+            log(error);
+            exit(1);
+            return;
+          }
           try {
             const result = deleteWallet(name, password);
             log(`✓ Wallet "${result.deleted}" deleted`);
@@ -703,9 +825,13 @@ export function buildWalletCommands(deps = {}) {
             password = null;
           } else {
             const sendConfig = getWalletConfig();
-            password = sendConfig.passwordHash
-              ? (process.env.NANSEN_WALLET_PASSWORD || await promptPassword('Enter wallet password: ', deps))
-              : null;
+            const resolved = await resolvePasswordForCommand(sendConfig, flags, deps);
+            if (resolved.error) {
+              log(resolved.error);
+              exit(1);
+              return;
+            }
+            password = resolved.password;
           }
           const dryRun = flags['dry-run'] || flags.dryRun;
 
@@ -723,7 +849,6 @@ export function buildWalletCommands(deps = {}) {
             };
 
             if (dryRun) {
-              // Build the transaction but don't broadcast
               const result = await sendTokens(sendOpts);
               log(`\nDry run — transaction not broadcast\n`);
               log(`  From:   ${result.from}`);
@@ -755,6 +880,83 @@ export function buildWalletCommands(deps = {}) {
           }
         },
 
+        'forget-password': async () => {
+          const result = deletePassword();
+          if (result.keychain || result.file) {
+            log('✓ Password removed from:');
+            if (result.keychain) log('  - System keychain');
+            if (result.file) log('  - Credentials file (~/.nansen/wallets/.credentials)');
+          } else {
+            log('No saved password found (keychain or credentials file).');
+          }
+        },
+
+        'secure': async () => {
+          const { password, source } = retrievePassword();
+          if (!password) {
+            log(JSON.stringify({
+              error: 'NO_PASSWORD_FOUND',
+              message: 'No wallet password found in any store.',
+              resolution: [
+                'Set NANSEN_WALLET_PASSWORD and run: nansen wallet secure',
+                'This will store it in the OS keychain.',
+              ],
+            }));
+            exit(1);
+            return;
+          }
+
+          if (source === 'keychain') {
+            log('✓ Password is already stored in the OS keychain (secure).');
+            return;
+          }
+
+          // Verify password actually decrypts wallets before overwriting keychain
+          const walletConfig = getWalletConfig();
+          if (walletConfig.passwordHash && !verifyPassword(password, walletConfig)) {
+            log(JSON.stringify({
+              error: 'INCORRECT_PASSWORD',
+              message: `Password from '${source}' does not match the wallet's stored hash.`,
+              resolution: source === 'file'
+                ? [
+                    'The password in ~/.nansen/wallets/.credentials is incorrect.',
+                    'Run: nansen wallet forget-password  then re-run with the correct password: NANSEN_WALLET_PASSWORD=<pw> nansen wallet secure',
+                  ]
+                : [
+                    'Unset NANSEN_WALLET_PASSWORD if it is stale, then re-run: nansen wallet secure',
+                  ],
+            }));
+            exit(1);
+            return;
+          }
+
+          // Try to migrate to keychain
+          const { stored, method } = storePassword(password);
+          if (stored && method === 'keychain') {
+            const fileRemoved = deleteCredentialsFile();
+            const fromLabel = source === 'file'
+              ? '~/.nansen/wallets/.credentials file'
+              : 'NANSEN_WALLET_PASSWORD env var';
+            log(`✓ Password migrated from ${fromLabel} → OS keychain (secure).`);
+            if (fileRemoved) {
+              log('  Removed ~/.nansen/wallets/.credentials.');
+            }
+          } else {
+            log(JSON.stringify({
+              error: 'KEYCHAIN_UNAVAILABLE',
+              message: source === 'file'
+                ? 'OS keychain is not available. Password remains in ~/.nansen/wallets/.credentials (insecure).'
+                : 'OS keychain is not available. Password is only in the NANSEN_WALLET_PASSWORD env var (not persisted).',
+              resolution: [
+                'Set NANSEN_WALLET_PASSWORD in a secrets manager or system keyring',
+                'Use a containerized secrets agent (e.g. Vault, 1Password CLI)',
+              ],
+            }));
+            exit(1);
+            return;
+          }
+        },
+
         'help': async () => {
           log(`
 Wallet Management - Local key storage for EVM and Solana
@@ -772,6 +974,8 @@ COMMANDS:
   delete <name>              Delete a wallet (requires password)
   send --to <address> --amount <number> --chain <evm|solana> [--token <address>] [--wallet <name>] [--max] [--dry-run]
                              Send tokens or native currency (--max sends entire balance, --dry-run previews without sending)
+  forget-password            Remove saved password from all stores
+  secure                     Migrate password from insecure storage to OS keychain
 
 OPTIONS:
   --name <label>             Wallet name (default: "default")
@@ -782,19 +986,26 @@ OPTIONS:
   --wallet <name>            Wallet to use (optional, uses default if omitted; use "walletconnect" or "wc" for WalletConnect, EVM only)
   --max                      Send entire balance (deducts gas for native transfers)
   --unsafe-no-password       Skip encryption — private keys stored UNENCRYPTED on disk (create only)
+  --human                    Enable interactive prompts (for human terminal use only)
+
+PASSWORD RESOLUTION (automatic, in order):
+  1. NANSEN_WALLET_PASSWORD env var
+  2. OS keychain (saved automatically on wallet create)
+  3. Interactive prompt (only with --human flag)
 
 ENVIRONMENT:
-  NANSEN_WALLET_PASSWORD     Password for non-interactive use (e.g. CI/scripts)
+  NANSEN_WALLET_PASSWORD     Wallet encryption password
   NANSEN_EVM_RPC            Custom EVM RPC endpoint
   NANSEN_SOLANA_RPC         Custom Solana RPC endpoint
 
 EXAMPLES:
-  nansen wallet create --name trading
+  NANSEN_WALLET_PASSWORD=mypass nansen wallet create --name trading
   nansen wallet list
   nansen wallet export trading
   nansen wallet default trading
   nansen wallet send --to 0x742d35Cc... --amount 1.5 --chain evm
   nansen wallet send --to 9WzDXw... --amount 0.1 --chain solana --token So11...
+  nansen wallet forget-password
 `);
           return;
         },

package/src/x402.js

@@ -11,6 +11,7 @@ import {
   fetchRecentBlockhash,
   getSolanaRpcUrl,
 } from './x402-svm.js';
+import { resolvePassword } from './keychain.js';
 
 /**
  * Parse PaymentRequirements from a 402 response.
@@ -108,9 +109,8 @@ export async function* createPaymentSignatures(response, url, options = {}) {
 
   const walletConfig = getWalletConfig();
   const password = walletConfig.passwordHash
-    ? (options.password || process.env.NANSEN_WALLET_PASSWORD || null)
+    ? (options.password || resolvePassword() || null)
     : null;
-  // Encrypted wallets need a password -- silently skip if unavailable
   if (walletConfig.passwordHash && password === null) return;
 
   const wallets = listWallets();