nansen-cli 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.20.0
+
+### Minor Changes
+
+- [#302](https://github.com/nansen-ai/nansen-cli/pull/302) [`3f0a5ab`](https://github.com/nansen-ai/nansen-cli/commit/3f0a5abad463c0386122efbe746809913aa823ba) Thanks [@arein](https://github.com/arein)! - Add post-install onboarding that interactively offers to install the Nansen AI coding skill and run a test query after `npm install -g nansen-cli`. Non-interactive environments (CI, piped stdin) receive a one-liner tip and are never blocked.
+
+### Patch Changes
+
+- [#313](https://github.com/nansen-ai/nansen-cli/pull/313) [`bb4d9e4`](https://github.com/nansen-ai/nansen-cli/commit/bb4d9e475158147645cae9b8bdd2555568a1e515) Thanks [@0xlaveen](https://github.com/0xlaveen)! - Update API key setup URL from app.nansen.ai/api to app.nansen.ai/auth/agent-setup across CLI help text, error messages, README, and postinstall script.
+
 ## 1.19.0
 
 ### Minor Changes

package/README.md

@@ -15,11 +15,13 @@ npx skills add nansen-ai/nansen-cli  # load agent skill files
 ## Auth
 
 ```bash
-nansen login              # interactive — saves to ~/.nansen/config.json
-export NANSEN_API_KEY=... # or env var (highest priority)
+nansen login --api-key <key>   # save key to ~/.nansen/config.json
+nansen login --human           # interactive prompt
+export NANSEN_API_KEY=...      # env var (highest priority)
+nansen logout                  # remove saved key
 ```
 
-Get your API key at [app.nansen.ai/api](https://app.nansen.ai/api). AI agents can use the [Agent Setup](https://app.nansen.ai/auth/agent-setup) flow instead.
+Get your API key at [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/agent-setup).
 
 ## Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",
@@ -12,9 +12,11 @@
     "src/**/*.json",
     "!src/__tests__/**",
     "skills/**",
+    "scripts/postinstall.js",
     "CHANGELOG.md"
   ],
   "scripts": {
+    "postinstall": "node scripts/postinstall.js",
     "start": "node src/index.js",
     "pretest": "node scripts/check-changeset.js",
     "test": "vitest run",

package/scripts/postinstall.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install onboarding for nansen-cli.
+ *
+ * Runs after `npm install -g nansen-cli` and offers two optional steps:
+ *   1. Install the Nansen AI coding skill (`npx skills add nansen-ai/nansen-cli`)
+ *   2. Check account status to verify the API key works (0 credits)
+ *
+ * Non-interactive environments (CI, piped stdin) get a one-liner tip instead.
+ * Always exits 0 — onboarding failures must never break installation.
+ */
+
+import { createInterface } from "readline";
+import { execFileSync, spawn } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const CYAN = "\x1b[36m";
+const RESET = "\x1b[0m";
+
+const SKILL_REPO = "nansen-ai/nansen-cli";
+const TEST_QUERY = ["account"];
+const TEST_QUERY_DISPLAY = "nansen account";
+
+// Path to the CLI entry point (works even if `nansen` bin isn't linked yet)
+const CLI_ENTRY = join(__dirname, "..", "src", "index.js");
+
+function log(msg = "") {
+  process.stderr.write(`  ${msg}\n`);
+}
+
+function hasTTY() {
+  return process.stdin.isTTY && process.stderr.isTTY;
+}
+
+function hasNpx() {
+  try {
+    execFileSync("npx", ["--version"], { stdio: "ignore", shell: process.platform === "win32" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isLoggedIn() {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  const configFile = join(home, ".nansen", "config.json");
+  if (!existsSync(configFile)) return false;
+  try {
+    const config = JSON.parse(readFileSync(configFile, "utf8"));
+    return !!(config.apiKey || config.api_key);
+  } catch {
+    return false;
+  }
+}
+
+function isSkillInstalled() {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  const locations = [
+    join(home, ".claude", "skills", "nansen-cli"),
+    join(home, ".claude", "skills", "nansen-ai--nansen-cli"),
+  ];
+  return locations.some((loc) => existsSync(loc));
+}
+
+function prompt(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    let answered = false;
+    rl.on("close", () => { if (!answered) resolve(""); });
+    rl.question(question, (answer) => {
+      answered = true;
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function runCommand(cmd, args) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: "inherit", shell: process.platform === "win32" });
+    child.on("close", (code) => resolve(code === 0));
+    child.on("error", () => resolve(false));
+  });
+}
+
+async function installSkill() {
+  if (isSkillInstalled()) {
+    log(`${GREEN}✓${RESET} Nansen skill already installed.`);
+    return;
+  }
+
+  if (!hasNpx()) {
+    log(`${DIM}Tip: Run 'npx skills add ${SKILL_REPO}' to install the Nansen AI coding skill.${RESET}`);
+    return;
+  }
+
+  log(`The Nansen skill lets AI coding agents (Cursor, Claude Code, etc.) query`);
+  log(`on-chain data, track smart money, and analyze tokens on your behalf.`);
+  const answer = await prompt(`  Install Nansen skill for your AI coding agent? [Y/n] `);
+
+  if (/^n/i.test(answer)) {
+    log(`Skipped. You can install it later with: ${CYAN}npx skills add ${SKILL_REPO}${RESET}`);
+    return;
+  }
+
+  log(`Installing Nansen skill...`);
+  const ok = await runCommand("npx", ["-y", "skills", "add", SKILL_REPO]);
+  if (!ok) {
+    log(`${YELLOW}Skill installation failed. You can retry with: npx skills add ${SKILL_REPO}${RESET}`);
+  }
+}
+
+async function testQuery() {
+  if (!isLoggedIn()) {
+    log();
+    log(`Not logged in yet. Run ${CYAN}nansen login --api-key <key>${RESET} to authenticate.`);
+    log(`Get your API key at: ${CYAN}https://app.nansen.ai/auth/agent-setup${RESET}`);
+    return;
+  }
+
+  log();
+  log(`Your API key is configured. Let's verify it works.`);
+  const answer = await prompt(`  Check account status? (${DIM}${TEST_QUERY_DISPLAY}${RESET}) [Y/n] `);
+
+  if (/^n/i.test(answer)) {
+    log(`Skipped. You're all set! Try: ${CYAN}nansen research smart-money netflow --chain solana${RESET}`);
+    return;
+  }
+
+  log(`Running: ${DIM}${TEST_QUERY_DISPLAY}${RESET}`);
+  log();
+  // Use process.execPath + CLI_ENTRY so it works even if `nansen` bin isn't linked yet
+  const ok = await runCommand(process.execPath, [CLI_ENTRY, ...TEST_QUERY, "--pretty"]);
+  if (ok) {
+    log();
+    log(`${GREEN}✓${RESET} All set! Run ${CYAN}nansen help${RESET} to see all available commands.`);
+  } else {
+    log();
+    log(`${YELLOW}Query failed. Check your API key with: nansen login --api-key <key>${RESET}`);
+  }
+}
+
+async function main() {
+  // Only run for global installs; skip local npm install / npm ci
+  if (process.env.npm_lifecycle_event === "postinstall" && process.env.npm_config_global !== "true") {
+    return;
+  }
+
+  log();
+
+  if (!hasTTY()) {
+    log(`${BOLD}Nansen CLI installed!${RESET}`);
+    log();
+    log(`Tip: Run '${CYAN}npx skills add ${SKILL_REPO}${RESET}' to install the Nansen AI coding skill.`);
+    log(`Tip: Run '${CYAN}nansen login --api-key <key>${RESET}' to authenticate.`);
+    return;
+  }
+
+  log(`${BOLD}Nansen CLI installed!${RESET}`);
+  log();
+
+  await installSkill();
+  await testQuery();
+
+  log();
+}
+
+main().catch(() => {
+  // Never fail installation due to onboarding errors
+});

package/skills/nansen-wallet-manager/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nansen-wallet-manager
-description: Wallet management — create, list, show, export, send, delete. Use when creating wallets, checking balances, or sending tokens.
+description: Wallet management — create (local or Privy server-side), list, show, export, send, delete. Use when creating wallets, checking balances, or sending tokens.
 metadata:
   openclaw:
     requires:
@@ -30,7 +30,49 @@ NANSEN_API_KEY=<key> nansen login
 nansen research profiler labels --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum
 ```
 
-## Wallet Creation (Two-Step Agent Flow)
+## Wallet Providers
+
+The CLI supports two wallet providers:
+
+| | **Local** (default) | **Privy** (server-side) |
+|---|---|---|
+| Key storage | Encrypted on disk | Server-side via Privy API |
+| Password required | Yes (min 12 chars) | No |
+| Export private keys | Yes (`wallet export`) | No — keys are managed by Privy |
+| Best for | Human users, manual trading | Agents, automated workflows |
+| Flag | `--provider local` (default) | `--provider privy` |
+| Required env vars | `NANSEN_WALLET_PASSWORD` | `PRIVY_APP_ID` + `PRIVY_APP_SECRET` |
+
+## Privy Wallet Creation
+
+Privy wallets are server-side wallets managed by the Privy API. No password is needed — keys never touch the local machine.
+
+### Prerequisites
+
+The following environment variables must be set:
+
+| Var | Purpose |
+|-----|---------|
+| `PRIVY_APP_ID` | Privy application ID |
+| `PRIVY_APP_SECRET` | Privy application secret |
+
+### Create a Privy wallet
+
+```bash
+nansen wallet create --provider privy
+# Or with a custom name:
+nansen wallet create --name agent-wallet --provider privy
+```
+
+### Critical rules for agents (Privy)
+
+- **No password needed** — Privy manages keys server-side
+- **Cannot export keys** — `wallet export` only works for local wallets
+- All other operations (`list`, `show`, `send`, `delete`, `default`) work identically for both providers
+
+## Local Wallet Creation (Two-Step Agent Flow)
+
+> This section covers **local** wallet creation. For Privy server-side wallets, see the [Privy Wallet Creation](#privy-wallet-creation) section above — no password is needed.
 
 Wallet creation requires a password from the **human user**. The agent must NOT generate or store the password itself.
 
@@ -127,6 +169,7 @@ For detailed migration steps (from `~/.nansen/.env`, `.credentials`, or env-var-
 | `--chain` | `evm` or `solana` |
 | `--max` | Send entire balance |
 | `--dry-run` | Preview without broadcasting |
+| `--provider` | Wallet provider: `local` (default, encrypted on disk) or `privy` (server-side via Privy API) |
 | `--human` | Enable interactive prompts (human terminal use only — agents must NOT use this) |
 | `--unsafe-no-password` | Skip encryption (keys stored in plaintext — NOT recommended) |
 
@@ -136,5 +179,8 @@ For detailed migration steps (from `~/.nansen/.env`, `.credentials`, or env-var-
 |-----|---------|
 | `NANSEN_WALLET_PASSWORD` | Wallet encryption password — only needed for initial `wallet create`. After that, the OS keychain handles it. |
 | `NANSEN_API_KEY` | API key (also set via `nansen login --api-key <key>`) |
+| `PRIVY_APP_ID` | Privy application ID (required for `--provider privy`) |
+| `PRIVY_APP_SECRET` | Privy application secret (required for `--provider privy`) |
+| `NANSEN_WALLET_PROVIDER` | Default provider for wallet create — `local` or `privy` |
 | `NANSEN_EVM_RPC` | Custom EVM RPC endpoint |
 | `NANSEN_SOLANA_RPC` | Custom Solana RPC endpoint |

package/src/api.js

@@ -630,7 +630,7 @@ export class NansenAPI {
                   } catch (x402Err) {
                     if (!this.apiKey) {
                       message = 'No API key configured. Two ways to authenticate:\n' +
-                        '  1. API key: nansen login --api-key <key> (get key at https://app.nansen.ai/api)\n' +
+                        '  1. API key: nansen login --api-key <key> (get key at https://app.nansen.ai/auth/agent-setup)\n' +
                         '  2. x402 micropayment: nansen wallet create + fund with USDC (no API key needed)';
                     } else {
                       message = `x402 auto-payment failed: ${x402Err.message}`;

package/src/cli.js

@@ -685,7 +685,7 @@ COMMANDS:
   alerts      list, create, update, toggle, delete
   web         search, fetch
   account     Show API key status, plan, and remaining credits
-  login       Save API key (--api-key <key> or NANSEN_API_KEY env var)
+  login       Save API key (--api-key <key>, --human, 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
@@ -859,7 +859,7 @@ export function buildCommands(deps = {}) {
         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');
+        log('Get your API key at: https://app.nansen.ai/auth/agent-setup');
         return;
       }
 
@@ -879,7 +879,7 @@ export function buildCommands(deps = {}) {
           return;
         }
         log('Nansen CLI Login\n');
-        log('Get your API key at: https://app.nansen.ai/api\n');
+        log('Get your API key at: https://app.nansen.ai/auth/agent-setup\n');
         apiKey = await promptFn('Enter your API key: ', true);
       }
 
@@ -890,7 +890,7 @@ export function buildCommands(deps = {}) {
           resolution: [
             'Run: nansen login --api-key <key>',
             'Or set NANSEN_API_KEY environment variable',
-            'Get your API key at: https://app.nansen.ai/api',
+            'Get your API key at: https://app.nansen.ai/auth/agent-setup',
           ],
         }));
         exit(1);
@@ -912,7 +912,7 @@ export function buildCommands(deps = {}) {
           log(JSON.stringify({
             error: 'INVALID_API_KEY',
             message: 'The API key is not valid.',
-            resolution: ['Check your key at https://app.nansen.ai/api']
+            resolution: ['Check your key at https://app.nansen.ai/auth/agent-setup']
           }));
         } else {
           log(JSON.stringify({