nansen-cli 1.8.0 → 1.9.0

package/SKILL.md

@@ -1,136 +1,230 @@
 ---
 name: nansen-cli
-description: Query the Nansen API for onchain analytics - Smart Money flows, wallet profiling, token analysis, and DeFi portfolio data. Use when analyzing crypto wallets, tracking smart money activity, or researching tokens.
+description: Nansen CLI for onchain analytics, smart money tracking, DEX trading, and perp markets.
 license: MIT
 metadata:
   author: nansen-ai
-  version: "1.3.0"
-compatibility: Requires Node.js 18+. Needs NANSEN_API_KEY environment variable or run `nansen login`.
+  version: "1.8.0"
+  repository: https://github.com/nansen-ai/nansen-cli
+compatibility: Node.js 18+. Works with Claude Code, Codex, Cursor, Windsurf, and any terminal-native agent.
 ---
 
 # Nansen CLI
 
-Command-line interface for the [Nansen API](https://docs.nansen.ai) - onchain analytics for crypto investors and AI agents.
+Onchain analytics and DEX trading for AI agents.
 
-## CLI vs Direct API
+## Quick Reference
 
-If your agent has HTTP access (curl, fetch), you can skip the CLI and hit the [Nansen REST API](https://docs.nansen.ai) directly with `apiKey` header auth. The CLI is most useful for terminal-native agents (Claude Code, Codex, Cursor) that benefit from `--pretty`, `--table`, `--fields`, built-in retries, and schema introspection.
+```bash
+# Search for any token, wallet, or entity
+nansen research search "jupiter" --type token
+
+# Token price (OHLCV)
+nansen research token ohlcv --token <addr> --chain solana --timeframe 1h --limit 24
+
+# Smart Money — what are the pros buying?
+nansen research smart-money netflow --chain solana --limit 10
+
+# Token screener — trending tokens
+nansen research token screener --chain solana --timeframe 24h --smart-money --limit 20
+
+# Trade — quote then execute
+nansen trade quote --chain solana --from <from_token_address> --to <to_token_address> --amount <base_units>
+nansen trade execute --quote <quote-id>
+
+# Create a wallet
+nansen wallet create                                      # interactive
+NANSEN_WALLET_PASSWORD="pass" nansen wallet create        # non-interactive
+
+# Discover all commands, options, and return fields
+nansen schema
+```
 
 ## Setup
 
 ```bash
-# Install globally
 npm install -g nansen-cli
+```
 
-# Authenticate — pick the method that works for your context:
+### Auth (pick one)
 
-# Option A: Non-interactive (best for agents — no prompts, no wasted credits)
-mkdir -p ~/.nansen && echo '{"apiKey":"YOUR_KEY","baseUrl":"https://api.nansen.ai"}' > ~/.nansen/config.json && chmod 600 ~/.nansen/config.json
+**x402 Pay-Per-Call (no API key needed):**
 
-# Option B: Environment variable (good for CI/scripts)
-export NANSEN_API_KEY=your-api-key
+```bash
+nansen wallet create    # Generates EVM + Solana keypair
+# Fund the EVM address with USDC on Base (~$0.50 minimum)
+export NANSEN_WALLET_PASSWORD="your-password"  # Skip interactive prompt
+# Done — CLI auto-pays $0.01-$0.05 per call
+```
+
+**API Key:**
 
-# Option C: Interactive login (burns 1 credit to validate)
-nansen login
+```bash
+export NANSEN_API_KEY=your-api-key
+# Or: nansen login --api-key YOUR_KEY
 ```
 
-Get your API key at [app.nansen.ai/api](https://app.nansen.ai/api).
+Get a key at [app.nansen.ai/api](https://app.nansen.ai/api).
 
-### Verify Installation
+## Smart Money
 
 ```bash
-# Free check (no API key needed):
-nansen schema | head -1
+nansen research smart-money netflow --chain solana --limit 10
+nansen research smart-money dex-trades --chain solana --labels "Smart Trader" --limit 20
+nansen research smart-money holdings --chain solana --limit 10
+nansen research smart-money perp-trades --limit 10            # no --chain (Hyperliquid only)
+nansen research smart-money dcas --limit 10                   # no --chain (Jupiter/Solana only)
+nansen research smart-money historical-holdings --chain solana --token-address <addr>
+```
 
-# Full check (uses 1 credit):
-nansen token screener --chain solana --limit 1
+Labels: `Fund`, `Smart Trader`, `30D Smart Trader`, `90D Smart Trader`, `180D Smart Trader`, `Smart HL Perps Trader`
+
+## Token Analytics
+
+`--chain` required. Use `--token` for the token address.
+
+```bash
+nansen research token screener --chain solana --timeframe 24h --smart-money --limit 20
+nansen research token info --token <addr> --chain solana
+nansen research token indicators --token <addr> --chain solana
+nansen research token ohlcv --token <addr> --chain solana --timeframe 1h --limit 24
+nansen research token holders --token <addr> --chain solana --smart-money
+nansen research token flows --token <addr> --chain solana --days 7
+nansen research token flow-intelligence --token <addr> --chain solana
+nansen research token who-bought-sold --token <addr> --chain solana
+nansen research token dex-trades --token <addr> --chain solana --limit 20
+nansen research token pnl --token <addr> --chain solana --sort total_pnl_usd:desc
+nansen research token transfers --token <addr> --chain solana --enrich
+nansen research token jup-dca --token <addr>                  # no --chain
+nansen research token perp-trades --symbol ETH --days 7       # no --chain, uses --symbol
+nansen research token perp-positions --symbol BTC              # no --chain
+nansen research token perp-pnl-leaderboard --symbol SOL        # no --chain
 ```
 
-## Commands
+Native tokens (SOL, ETH) are not supported on most token endpoints — use specific token addresses.
+
+## Wallet Profiler
+
+`--chain` and `--address` required for most commands.
 
-### Smart Money
-Track sophisticated market participants:
 ```bash
-nansen smart-money netflow --chain solana --pretty
-nansen smart-money dex-trades --chain solana --labels "Smart Trader"
-nansen smart-money holdings --chain solana
+nansen research profiler balance --address <addr> --chain solana
+nansen research profiler labels --address <addr> --chain ethereum
+nansen research profiler pnl --address <addr> --chain ethereum --days 30
+nansen research profiler pnl-summary --address <addr> --chain ethereum
+nansen research profiler transactions --address <addr> --chain ethereum --limit 20
+nansen research profiler historical-balances --address <addr> --chain solana --days 30
+nansen research profiler related-wallets --address <addr> --chain ethereum
+nansen research profiler counterparties --address <addr> --chain ethereum
+nansen research profiler perp-positions --address <addr>       # no --chain
+nansen research profiler perp-trades --address <addr>          # no --chain
+nansen research profiler search --query "Vitalik"              # no --chain
+nansen research profiler batch --addresses "0xabc,0xdef" --chain ethereum --include labels,balance,pnl
+nansen research profiler trace --address <addr> --chain ethereum --depth 2 --width 10  # ⚠️ makes N×width API calls
+nansen research profiler compare --addresses "0xabc,0xdef" --chain ethereum
 ```
 
-### Wallet Profiler
-Analyze any wallet:
+## Search
+
 ```bash
-nansen profiler balance --address 0x123... --chain ethereum
-nansen profiler labels --address 0x123... --chain ethereum
-nansen profiler pnl --address 0x123... --chain ethereum
-nansen profiler search --query "Vitalik"
+nansen research search "jupiter" --type token
+nansen research search "Vitalik" --type entity --limit 5
+nansen research search "0xd8dA..."                             # by address
 ```
 
-### Token God Mode
-Deep token analytics:
+## Perps (Hyperliquid)
+
 ```bash
-nansen token screener --chain solana --timeframe 24h
-nansen token holders --token <address> --chain solana --smart-money
-nansen token flows --token <address> --chain solana
-nansen token pnl --token <address> --chain solana
+nansen research perp screener --sort volume_usd:desc --limit 20
+nansen research perp leaderboard --days 7 --limit 20
 ```
 
-### Portfolio
-DeFi holdings analysis:
+## Portfolio
+
 ```bash
-nansen portfolio defi --wallet 0x123...
+nansen research portfolio defi --wallet <addr>
+nansen research points leaderboard --tier green --limit 20
 ```
 
-## Output Formats
+## Trading
 
-- **Default**: JSON (for AI agents)
-- `--pretty`: Formatted JSON
-- `--table`: Human-readable table
-- `--stream`: NDJSON (one record per line)
-- `--fields`: Filter specific fields
+Two-step: quote then execute.
 
-## Key Options
+```bash
+# Get quotes from multiple aggregators (Jupiter, OKX, LiFi)
+nansen trade quote --chain solana \
+  --from <from_token_address> \
+  --to <to_token_address> \
+  --amount <base_units>
+
+# Execute the best quote
+nansen trade execute --quote <quote-id>
+```
 
-| Option | Description |
-|--------|-------------|
-| `--chain` | Blockchain (solana, ethereum, base, etc.) |
-| `--chains` | Multiple chains as JSON array |
-| `--limit` | Number of results |
-| `--days` | Date range in days |
-| `--sort` | Sort field (e.g., `value_usd:desc`) |
-| `--smart-money` | Filter for Smart Money only |
+> ⚠️ Always inspect the quote response (price, slippage, expiry) before executing.
+> Quotes expire — if you wait too long, execute will fail. Get a fresh quote and retry.
+> Trades are irreversible once executed on-chain.
 
-## Supported Chains
+**⚠️ Amounts are in base units (not human-readable):**
 
-ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, mantle, ronin, sei, plasma, sonic, monad, hyperevm, iotaevm
+| Token | Decimals | 1 unit = |
+|-------|----------|----------|
+| SOL | 9 | 1000000000 lamports |
+| ETH | 18 | 1000000000000000000 wei |
+| USDC | 6 | 1000000 |
 
-## Smart Money Labels
+Symbol shortcuts (SOL, ETH) don't work yet — use full addresses.
 
-Fund, Smart Trader, 30D Smart Trader, 90D Smart Trader, 180D Smart Trader, Smart HL Perps Trader
+### Common Addresses
 
-## Schema Introspection
+**Solana:** SOL `So11111111111111111111111111111111111111112` · USDC `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` · JUP `JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN`
+
+**Base:** ETH `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` · USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` · DEGEN `0x4ed4e862860bed51a9570b96d89af5e1b0efefed`
+
+## Wallet Management
 
-Get the full API schema for programmatic use:
 ```bash
-nansen schema --pretty
-nansen schema smart-money --pretty
+nansen wallet create          # Create EVM + Solana keypair
+nansen wallet list            # List wallets
+nansen wallet send --to <addr> --amount 1.5 --chain evm    # Send native
+nansen wallet send --to <addr> --chain evm --max            # Send entire balance
 ```
 
-## Troubleshooting
+## Common Options
 
-See [AGENTS.md — Troubleshooting](AGENTS.md#troubleshooting) for the full troubleshooting guide, including error codes, known endpoint quirks, and pagination gotchas.
+| Option | Description |
+|--------|-------------|
+| `--chain` | Required for most commands. See [Supported Chains](#supported-chains) |
+| `--token` | Token address (aliases: `--mint`, `--token-address`) |
+| `--address` | Wallet address |
+| `--limit` | Results per page (default 10) |
+| `--days` | Lookback period in days (default 30) |
+| `--sort` | Sort field:direction (e.g. `value_usd:desc`) |
+| `--smart-money` | Filter to smart money wallets only |
+| `--pretty` | Formatted JSON output |
+| `--table` | ASCII table output |
+| `--stream` | NDJSON (one record per line) |
+| `--fields a,b` | Return only specific fields |
+| `--cache` | Cache responses (300s TTL). **Do not use with `trade` commands** — stale prices/quotes can cause bad trades |
+
+## Schema Introspection
 
-## Examples
+> **Stuck?** Run `nansen schema` or `nansen schema <command>` to discover all available commands, options, and return fields.
 
 ```bash
-# Find trending Solana tokens with Smart Money activity
-nansen token screener --chain solana --timeframe 24h --smart-money --pretty
+nansen schema                 # Full JSON schema — all commands, options, return fields
+```
 
-# Check who's accumulating a specific token
-nansen token holders --token So11111111111111111111111111111111111111112 --chain solana --smart-money --limit 20 --pretty
+## Supported Chains
 
-# Profile a whale wallet
-nansen profiler balance --address Gu29tjXrVr9v5n42sX1DNrMiF3BwbrTm379szgB9qXjc --chain solana --pretty
+**Research:** `solana`, `ethereum`, `base`, `bnb`, `arbitrum`, `polygon`, `optimism`, `avalanche`, `linea`, `scroll`, `mantle`, `ronin`, `sei`, `plasma`, `sonic`, `monad`, `hyperevm`, `iotaevm`
 
-# Track Smart Money flows into memecoins
-nansen smart-money netflow --chain solana --labels "Smart Trader" --pretty
-```
+**Trading & x402:** `solana`, `base`
+
+## Gotchas
+
+- Native tokens (SOL, ETH) don't work on most token endpoints — use wrapped addresses
+- Perp commands don't take `--chain` (Hyperliquid only)
+- `--amount` is always in base units, not human-readable
+- Profiler `trace` makes N×width API calls — can burn credits fast
+- x402 auth needs USDC on Base, not Solana

package/package.json

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

package/src/api.js

@@ -505,8 +505,11 @@ export class NansenAPI {
         } else if (code === ErrorCode.CREDITS_EXHAUSTED) {
           message = message.replace(/\.+$/, '') + '. No retry will help. Check your Nansen dashboard for credit balance.';
         } else if (code === ErrorCode.PAYMENT_REQUIRED) {
-          // Try x402 auto-payment with fallback across payment networks
-          if (!this.defaultHeaders['Payment-Signature']) {
+          // Try x402 auto-payment: local wallet (with network fallback), then WalletConnect
+          const hasManualSignature = !!(this.defaultHeaders['Payment-Signature'] || options.headers?.['Payment-Signature']);
+
+          if (!hasManualSignature) {
+            // 1. Try local wallet with fallback across payment networks
             try {
               const { createPaymentSignatures } = await import('./x402.js');
               for await (const { signature, network } of createPaymentSignatures(response, url)) {
@@ -537,17 +540,54 @@ export class NansenAPI {
                 }
                 // This payment option was rejected, try next
               }
-            } catch { /* x402 auto-pay unavailable, fall through */ }
-          }
-          message = 'Payment required. To access this endpoint:\n  • Set an API key: nansen login --api-key <key>  (get one at https://app.nansen.ai/api)\n  • Or pay per call: nansen wallet create, fund with USDC on Base or Solana (from $0.01/call, min $0.05 balance)\n  • Docs: https://docs.x402.org';
-          const paymentHeader = response.headers.get('payment-required');
-          if (paymentHeader) {
-            try {
-              data.paymentRequirements = JSON.parse(atob(paymentHeader));
-            } catch {
-              data.paymentRequiredRaw = paymentHeader;
+            } catch { /* local wallet unavailable, try WalletConnect */ }
+
+            // 2. Fall back to WalletConnect (walletconnect-x402.js)
+            // (local wallet returns early on success above, so we always reach here if it failed)
+            {
+              let paymentRequirements;
+              const paymentHeader = response.headers.get('payment-required');
+              if (paymentHeader) {
+                try {
+                  paymentRequirements = JSON.parse(atob(paymentHeader));
+                } catch {
+                  data.paymentRequiredRaw = paymentHeader;
+                }
+              }
+              if (!paymentRequirements && data.paymentRequirements) {
+                paymentRequirements = data.paymentRequirements;
+              }
+
+              if (paymentRequirements) {
+                try {
+                  const { handleX402Payment } = await import('./walletconnect-x402.js');
+                  const paymentSignature = await handleX402Payment(paymentRequirements);
+                  const paidResponse = await fetch(url, {
+                    method: 'POST',
+                    headers: {
+                      'Content-Type': 'application/json',
+                      'X-Client-Type': 'nansen-cli',
+                      'X-Client-Version': packageVersion,
+                      'Payment-Signature': paymentSignature,
+                      ...this.defaultHeaders,
+                      ...options.headers,
+                    },
+                    body: JSON.stringify(NansenAPI.cleanBody(body)),
+                  });
+                  if (paidResponse.ok) {
+                    return await paidResponse.json();
+                  }
+                } catch (x402Err) {
+                  message = `x402 auto-payment failed: ${x402Err.message}`;
+                }
+                data.paymentRequirements = paymentRequirements;
+              }
             }
           }
+
+          if (!message || message === data.message) {
+            message = 'Payment required (x402). Sign the paymentRequirements below per https://docs.x402.org and pass the result with --x402-payment-signature <value>.';
+          }
         }
 
         lastError = new NansenError(message, code, response.status, {

package/src/chain-ids.js

@@ -0,0 +1,19 @@
+/**
+ * Canonical EVM chain name → numeric chain ID mapping.
+ *
+ * Single source of truth — import from here instead of defining inline.
+ */
+
+export const EVM_CHAIN_IDS = {
+  ethereum: 1,
+  base: 8453,
+  optimism: 10,
+  arbitrum: 42161,
+  polygon: 137,
+  avalanche: 43114,
+  bnb: 56,
+  linea: 59144,
+  scroll: 534352,
+  zksync: 324,
+  mantle: 5000,
+};

package/src/cli.js

@@ -144,14 +144,15 @@ export const SCHEMA = {
             chain: { type: 'string', default: 'ethereum', description: 'Blockchain' },
             from: { type: 'string', required: true, description: 'Token to sell (address or symbol)' },
             to: { type: 'string', required: true, description: 'Token to buy (address or symbol)' },
-            amount: { type: 'string', required: true, description: 'Amount to swap' }
+            amount: { type: 'string', required: true, description: 'Amount to swap' },
+            wallet: { type: 'string', description: 'Wallet name, or "walletconnect"/"wc" for WalletConnect (EVM only)' }
           }
         },
         'execute': {
           description: 'Sign and broadcast a quoted trade',
           options: {
             chain: { type: 'string', default: 'ethereum', description: 'Blockchain' },
-            wallet: { type: 'string', description: 'Wallet name or address' }
+            wallet: { type: 'string', description: 'Wallet name, or "walletconnect"/"wc" for WalletConnect (EVM only)' }
           }
         }
       }
@@ -838,6 +839,7 @@ export function buildCommands(deps = {}) {
     api = null,
     promptFn = prompt,
     log = console.log,
+    errorOutput = console.error,
     NansenAPIClass = NansenAPI,
     saveConfigFn = saveConfig,
     deleteConfigFn = deleteConfig,
@@ -905,7 +907,7 @@ export function buildCommands(deps = {}) {
       try {
         content = fs.readFileSync(changelogPath, 'utf8');
       } catch {
-        errorOutput('CHANGELOG.md not found. Visit https://github.com/nansen-ai/nansen-cli/blob/main/CHANGELOG.md');
+        log('CHANGELOG.md not found. Visit https://github.com/nansen-ai/nansen-cli/blob/main/CHANGELOG.md');
         return;
       }
       const since = options.since;
@@ -1307,14 +1309,31 @@ export function buildCommands(deps = {}) {
   cmds['trade'] = async (args, apiInstance, flags, options) => {
     const sub = args[0];
     if (!sub || sub === 'help') {
-      return {
-        commands: ['quote', 'execute'],
-        description: 'DEX trading commands',
-        example: 'nansen trade quote --chain ethereum --from ETH --to USDC --amount 1'
-      };
+      log(`nansen trade — DEX trading commands
+
+SUBCOMMANDS:
+  quote       Get a swap quote (price, route, fees)
+  execute     Sign and broadcast a quoted swap
+
+USAGE:
+  nansen trade quote --chain <chain> --from <token> --to <token> --amount <units>
+  nansen trade execute --quote <quoteId>
+
+EXAMPLES:
+  nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
+  nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
+  nansen trade execute --quote 1708900000000-abc123
+
+SYMBOLS:
+  Common tokens resolve automatically: SOL, ETH, BNB, USDC, USDT, WETH, WBNB
+  Raw addresses are also accepted.`);
+      return;
     }
     if (!tradingCmds[sub]) {
-      return { error: `Unknown trade subcommand: ${sub}`, available: ['quote', 'execute'] };
+      log(`Unknown trade subcommand: ${sub}`);
+      log(`Available: quote, execute`);
+      log(`Run 'nansen trade help' for usage.`);
+      return;
     }
     return tradingCmds[sub](args.slice(1), apiInstance, flags, options);
   };