nansen-cli 1.9.2 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.10.0
+
+### Minor Changes
+
+- [#125](https://github.com/nansen-ai/nansen-cli/pull/125) [`5a5a80a`](https://github.com/nansen-ai/nansen-cli/commit/5a5a80af9c2c5b93efcc707925b004f077e13c36) Thanks [@0xlaveen](https://github.com/0xlaveen)! - Add modular skills/ directory with 7 agent-optimised SKILL.md files (nansen-token, nansen-smart-money, nansen-profiler, nansen-trade, nansen-wallet, nansen-perp, nansen-search) following the linear-cli pattern. Each skill has scoped frontmatter, agent routing descriptions, bash examples, and exit codes. Add skills nudge to `nansen --help` output.
+
+### Patch Changes
+
+- [#122](https://github.com/nansen-ai/nansen-cli/pull/122) [`9a1ada8`](https://github.com/nansen-ai/nansen-cli/commit/9a1ada8543cd6fdbcc10d2d5004fe2e2e1a88928) Thanks [@TimNooren](https://github.com/TimNooren)! - `nansen research <unknown>` and `nansen trade <unknown>` now exit with code 1 and return `{"success":false,...}` instead of silently exiting 0.
+
+- [#138](https://github.com/nansen-ai/nansen-cli/pull/138) [`c61881f`](https://github.com/nansen-ai/nansen-cli/commit/c61881f5455b9fff7fb97841652a72af58ab8e0b) Thanks [@TimNooren](https://github.com/TimNooren)! - Fix `nansen login --help` to show usage instead of erroring. Previously, `--help` was silently ignored on TTY (showing the interactive prompt) and caused an error on non-TTY. Also fixes the post-login suggested command to use the non-deprecated `nansen research token screener` path.
+
+- [#129](https://github.com/nansen-ai/nansen-cli/pull/129) [`eeabf89`](https://github.com/nansen-ai/nansen-cli/commit/eeabf8988dafc7fb1964fd2eef629f03c6a4420a) Thanks [@araa47](https://github.com/araa47)! - Fix `token ohlcv` sending unsupported pagination/limit params that caused 422 errors
+
+- [#139](https://github.com/nansen-ai/nansen-cli/pull/139) [`e86dc68`](https://github.com/nansen-ai/nansen-cli/commit/e86dc6869f524d3dc59da4c7c04cb1ace1b7246b) Thanks [@TimNooren](https://github.com/TimNooren)! - Fix API key prompt masking: each keystroke was showing the real character followed by `*` (e.g. `f*o*o*`) because the readline interface was active alongside raw mode, causing double output. Moving readline creation into the non-hidden branch eliminates the double-echo and also fixes backspace incorrectly clearing the prompt label.
+
+- [#129](https://github.com/nansen-ai/nansen-cli/pull/129) [`eeabf89`](https://github.com/nansen-ai/nansen-cli/commit/eeabf8988dafc7fb1964fd2eef629f03c6a4420a) Thanks [@araa47](https://github.com/araa47)! - Fix `trade quote` crash when no wallet exists — now shows actionable error instead of uncaught exception
+
+- [#126](https://github.com/nansen-ai/nansen-cli/pull/126) [`f3b87e7`](https://github.com/nansen-ai/nansen-cli/commit/f3b87e7491d03d052d5d72fcc991de0c33caf51f) Thanks [@araa47](https://github.com/araa47)! - Remove root SKILL.md so `npx skills add nansen-ai/nansen-cli` correctly discovers all 7 skills in `skills/` instead of treating the repo as a single skill.
+
+## 1.9.3
+
+### Patch Changes
+
+- [#118](https://github.com/nansen-ai/nansen-cli/pull/118) [`0bd4c3c`](https://github.com/nansen-ai/nansen-cli/commit/0bd4c3c1946e575e2c2db5e02d17f266e79752a4) Thanks [@TimNooren](https://github.com/TimNooren)! - Show warning when trade quote price impact exceeds 5%, and show pin command to avoid fallback to worse quotes
+
 ## 1.9.2
 
 ### Patch Changes

package/README.md

@@ -2,226 +2,56 @@
 
 [![npm version](https://img.shields.io/npm/v/nansen-cli.svg)](https://www.npmjs.com/package/nansen-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![CI](https://github.com/nansen-ai/nansen-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/nansen-ai/nansen-cli/actions/workflows/ci.yml)
 
-> **Built by agents, for agents.** We prioritize the best possible AI agent experience.
-
-Command-line interface for the [Nansen API](https://docs.nansen.ai) with structured JSON output, designed for AI agents and automation.
+> **Built by agents, for agents.** Command-line interface for the [Nansen API](https://docs.nansen.ai) with structured JSON output.
 
 ## Installation
 
 ```bash
-# Install globally via npm
 npm install -g nansen-cli
-
-# Or run directly with npx
-npx nansen-cli help
-
-# Or clone and install locally
-git clone https://github.com/nansen-ai/nansen-cli.git
-cd nansen-cli
-npm install
-npm link
+npx skills add nansen-ai/nansen-cli  # load agent skill files
 ```
 
-## Configuration
-
-### For AI Agents (Recommended)
-
-Use the [AI Agent Setup](https://app.nansen.ai/auth/agent-setup) flow:
-
-1. Your agent will ask you to visit: **[app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/agent-setup)**
-2. Sign in with your Nansen account
-3. Copy the message shown
-4. Paste it back to your agent
-
-Your agent saves the key and handles everything else automatically.
-
-### Manual Setup
-
-**Option 1: Interactive login**
-```bash
-nansen login
-# Enter your API key when prompted
-# ✓ Saved to ~/.nansen/config.json
-```
-
-**Option 2: Environment variable (best for agents)**
-```bash
-export NANSEN_API_KEY=your-api-key
-```
-
-**Option 3: Direct config file**
-```bash
-mkdir -p ~/.nansen && echo '{"apiKey":"<key>","baseUrl":"https://api.nansen.ai"}' > ~/.nansen/config.json && chmod 600 ~/.nansen/config.json
-```
-
-Get your API key at [app.nansen.ai/api](https://app.nansen.ai/api).
-
-### Auth Priority
-
-1. `NANSEN_API_KEY` env var (highest)
-2. `~/.nansen/config.json` file
-3. Interactive prompt
-
-### Verify It Works
+## Auth
 
 ```bash
-# Check CLI is installed (no API key needed):
-nansen schema | head -1
-
-# Verify API access:
-nansen research token screener --chain solana --limit 1
+nansen login              # interactive — saves to ~/.nansen/config.json
+export NANSEN_API_KEY=... # or env var (highest priority)
 ```
 
-## Quick Start
-
-```bash
-# Get trending tokens on Solana
-nansen research token screener --chain solana --timeframe 24h --pretty
-
-# Check Smart Money activity
-nansen research smart-money netflow --chain solana --pretty
-
-# Profile a wallet
-nansen research profiler balance --address 0x28c6c06298d514db089934071355e5743bf21d60 --chain ethereum --pretty
-
-# Search for tokens/entities
-nansen research search "Vitalik Buterin" --pretty
-```
+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.
 
 ## Commands
 
-All analytics live under `nansen research`, trading under `nansen trade`, and wallet management under `nansen wallet`.
-
-### `research` - Research & Analytics
-
 ```
 nansen research <category> <subcommand> [options]
+nansen trade <subcommand> [options]
+nansen wallet <subcommand> [options]
+nansen schema [command] [--pretty]    # full command reference (no API key needed)
 ```
 
-**Category aliases:** `sm` (smart-money), `tgm` (token), `prof` (profiler), `port` (portfolio)
-
-#### `research smart-money` - Smart Money Analytics
-
-Track trading and holding activity of sophisticated market participants.
+**Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `search`, `perp`, `points`
 
-| Subcommand | Description |
-|------------|-------------|
-| `netflow` | Net capital flows (inflows vs outflows) |
-| `dex-trades` | Real-time DEX trading activity |
-| `perp-trades` | Perpetual trading on Hyperliquid |
-| `holdings` | Aggregated token balances |
-| `dcas` | DCA strategies on Jupiter |
-| `historical-holdings` | Historical holdings over time |
+**Trade:** `quote`, `execute` — DEX swaps via LiFi/Jupiter.
 
-**Smart Money Labels:** `Fund`, `Smart Trader`, `30D Smart Trader`, `90D Smart Trader`, `180D Smart Trader`, `Smart HL Perps Trader`
+**Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send` — local keypairs (EVM + Solana).
 
-#### `research profiler` - Wallet Profiling
+Run `nansen schema --pretty` for the full subcommand and field reference.
 
-**ENS Name Resolution:** You can use `.eth` names anywhere an `--address` is accepted:
-
-```bash
-nansen research profiler balance --address vitalik.eth
-nansen research profiler labels --address nansen.eth --chain ethereum
-nansen research profiler transactions --address vitalik.eth --table
-```
-
-ENS names are automatically resolved to `0x` addresses via public APIs (with onchain RPC fallback). Works on all EVM chains. The resolved name and address are included as `_ens` metadata in JSON output.
-
-| Subcommand | Description |
-|------------|-------------|
-| `balance` | Current token holdings |
-| `labels` | Behavioral and entity labels |
-| `transactions` | Transaction history |
-| `pnl` | PnL and trade performance |
-| `search` | Search for entities by name |
-| `historical-balances` | Historical balances over time |
-| `related-wallets` | Find wallets related to an address |
-| `counterparties` | Top counterparties by volume |
-| `pnl-summary` | Summarized PnL metrics |
-| `perp-positions` | Current perpetual positions |
-| `perp-trades` | Perpetual trading history |
-
-#### `research token` - Token God Mode
-
-| Subcommand | Description |
-|------------|-------------|
-| `screener` | Discover and filter tokens |
-| `holders` | Token holder analysis |
-| `flows` | Token flow metrics |
-| `dex-trades` | DEX trading activity |
-| `pnl` | PnL leaderboard |
-| `who-bought-sold` | Recent buyers and sellers |
-| `flow-intelligence` | Detailed flow intelligence by label |
-| `transfers` | Token transfer history |
-| `jup-dca` | Jupiter DCA orders for token |
-| `ohlcv` | OHLCV candle data for a token |
-| `perp-trades` | Perp trades by token symbol |
-| `perp-positions` | Open perp positions by token symbol |
-| `perp-pnl-leaderboard` | Perp PnL leaderboard by token |
-
-#### `research search` / `research perp` / `research portfolio` / `research points`
-
-See `nansen research help` or `nansen schema --pretty` for full details.
-
-### `trade` - DEX Trading
-
-```bash
-# Get a swap quote
-nansen trade quote --from USDC --to SOL --amount 10 --chain solana
-
-# Execute the swap
-nansen trade execute --from USDC --to SOL --amount 10 --chain solana
-```
-
-### `wallet` - Local Wallet Management
-
-| Subcommand | Description |
-|------------|-------------|
-| `create` | Create a new wallet (EVM + Solana keypair) |
-| `list` | List all wallets |
-| `show` | Show wallet addresses |
-| `export` | Export private keys |
-| `default` | Set default wallet |
-| `delete` | Delete a wallet |
-| `send` | Send tokens (native or ERC-20/SPL) |
-
-Wallets are passwordless by default (keys stored like SSH keys). Set `NANSEN_WALLET_PASSWORD` env var for encryption at rest.
-
-### `schema` - Schema Discovery
-
-No API key required. Machine-readable command reference for agent introspection.
-
-```bash
-nansen schema --pretty                    # All commands
-nansen schema research --pretty           # Research commands
-```
-
-### Deprecated Flat Commands
-
-The old flat commands (`nansen smart-money`, `nansen token`, `nansen profiler`, `nansen search`, `nansen perp`, `nansen portfolio`, `nansen points`, `nansen quote`, `nansen execute`) still work but print a deprecation warning to stderr. Use the new `research` and `trade` namespaces instead.
-
-## Options
+## Key Options
 
 | Option | Description |
 |--------|-------------|
-| `--pretty` | Format JSON output for readability |
-| `--table` | Format output as human-readable table |
-| `--fields <list>` | Comma-separated fields to include (reduces response size) |
-| `--stream` | Output as NDJSON for incremental processing |
-| `--cache` / `--no-cache` | Enable/disable response caching |
-| `--cache-ttl <s>` | Cache TTL in seconds (default: 300) |
 | `--chain <chain>` | Blockchain to query |
-| `--chains <json>` | Multiple chains as JSON array |
-| `--limit <n>` | Number of results |
-| `--days <n>` | Date range in days (default: 30) |
-| `--sort <field:dir>` | Sort results (e.g., `--sort value_usd:desc`) |
-| `--symbol <sym>` | Token symbol for perp endpoints (e.g., BTC, ETH) |
-| `--filters <json>` | Filter criteria as JSON |
+| `--limit <n>` | Result count |
+| `--timeframe <tf>` | Time window: `5m` `1h` `6h` `24h` `7d` `30d` |
+| `--fields <list>` | Comma-separated fields (reduces response size) |
+| `--sort <field:dir>` | Sort results, e.g. `--sort value_usd:desc` |
+| `--pretty` | Human-readable JSON |
+| `--table` | Table format |
+| `--stream` | NDJSON output for large results |
 | `--labels <label>` | Smart Money label filter |
-| `--smart-money` | Filter for Smart Money only |
-| `--timeframe <tf>` | Time window (5m, 10m, 1h, 6h, 24h, 7d, 30d) |
+| `--smart-money` | Filter for Smart Money addresses only |
 
 ## Supported Chains
 
@@ -229,121 +59,51 @@ The old flat commands (`nansen smart-money`, `nansen token`, `nansen profiler`,
 
 > Run `nansen schema` to get the current chain list (source of truth).
 
-## Agent-Optimized Patterns
-
-### Reduce Token Burn with `--fields`
-
-```bash
-# ❌ Returns everything (huge JSON, wastes agent context)
-nansen research smart-money netflow --chain solana
-
-# ✅ Only what you need
-nansen research smart-money netflow --chain solana --fields token_symbol,net_flow_usd,chain --limit 10
-```
-
-### Use `--stream` for Large Results
+## Agent Tips
 
+**Reduce token burn with `--fields`:**
 ```bash
-# NDJSON mode — process line by line, don't buffer giant arrays
-nansen research token dex-trades --chain solana --limit 100 --stream
+nansen research smart-money netflow --chain solana --fields token_symbol,net_flow_usd --limit 10
 ```
 
-### x402 Micropayments
+**Use `--stream` for large results** — outputs NDJSON instead of buffering a giant array.
 
-When the API returns a 402 Payment Required, the CLI automatically handles payment if a funded wallet exists:
-
-1. CLI detects 402 response with payment requirements
-2. Signs a USDC payment ($0.05/call) using your wallet
-3. Retries the request with the payment signature
-4. Falls back from EVM to Solana if first network has insufficient funds
-
-```bash
-# Fund your wallet, then API calls auto-pay
-nansen wallet create
-# Send USDC to the displayed address
-nansen research smart-money netflow --chain solana  # auto-pays if no API key
-```
-
-## Pagination
-
-Use `--limit N` to control result count. The CLI always fetches page 1 (there is no `--page` flag).
-
-**Detecting the last page:** If results returned < your `--limit`, you've reached the end.
+**ENS names** work anywhere `--address` is accepted: `--address vitalik.eth`
 
 ## Output Format
 
-### Response envelope
-
 ```json
-// Success
-{ "success": true, "data": <raw_api_response> }
-
-// Error
-{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "details": {...} }
+{ "success": true,  "data": <api_response> }
+{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401 }
 ```
 
-### Response shapes vary by endpoint
-
-The `data` field structure differs across endpoints:
-
-| Shape | Example endpoints |
-|-------|------------------|
-| `data.data` (array) | token screener |
-| `data.results` (array) | entity search |
-| `data.data.results` (array) | most profiler endpoints |
-| `data.netflows` | smart-money netflow |
-| `data.trades` | smart-money dex-trades |
-| `data.holdings` | smart-money holdings |
-| `data.holders` | token holders |
-
-`--table` and `--stream` handle this automatically. For raw JSON parsing:
-
-```bash
-nansen research smart-money netflow --chain solana | jq 'keys, .data | keys'
-```
-
-### Error codes
+**Critical error codes:**
 
 | Code | Action |
 |------|--------|
-| `CREDITS_EXHAUSTED` | Stop all API calls immediately — do not retry. Check your plan at [app.nansen.ai](https://app.nansen.ai). |
-| `RATE_LIMITED` | Auto-retry handles this. |
+| `CREDITS_EXHAUSTED` | Stop all API calls immediately. Check [app.nansen.ai](https://app.nansen.ai). |
+| `UNAUTHORIZED` | Wrong or missing key. Re-auth. |
+| `RATE_LIMITED` | Auto-retried by CLI. |
 | `UNSUPPORTED_FILTER` | Remove the filter and retry. |
-| `UNAUTHORIZED` | Key is wrong or missing. Re-auth. |
-| `INVALID_ADDRESS` | Check address format for the chain. |
 
 ## Troubleshooting
 
 | Symptom | Fix |
 |---------|-----|
-| `command not found: nansen` | `npm install -g nansen-cli` or `npx nansen-cli` |
-| `UNAUTHORIZED` after login | Check `cat ~/.nansen/config.json`. Write directly if needed. |
-| Login hangs | Skip `nansen login`, write config directly. |
-| Huge JSON response | Use `--fields` to select only needed columns. |
-| Perp endpoints empty | Use `--symbol BTC` not `--token`. Perps are Hyperliquid-only. |
-| `UNSUPPORTED_FILTER` on token holders | Not all tokens have smart money data. Remove `--smart-money`. |
-| `CREDITS_EXHAUSTED` | Check your plan at [app.nansen.ai](https://app.nansen.ai). |
+| `command not found` | `npm install -g nansen-cli` |
+| `UNAUTHORIZED` after login | `cat ~/.nansen/config.json` or set `NANSEN_API_KEY` |
+| Empty perp results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |
+| `UNSUPPORTED_FILTER` on token holders | Remove `--smart-money` — not all tokens have that data. |
+| Huge JSON response | Use `--fields` to select columns. |
 
 ## Development
 
 ```bash
-npm test              # Run tests (mocked, no API key needed)
-npm run test:coverage # With coverage
-npm run test:live     # Against live API (needs NANSEN_API_KEY)
+npm test              # mocked tests, no API key needed
+npm run test:live     # live API (needs NANSEN_API_KEY)
 ```
 
-See [AGENTS.md](AGENTS.md) for contributor guidance (architecture, testing patterns, style guide).
-
-## API Coverage
-
-| Category | Endpoints | Coverage |
-|----------|-----------|----------|
-| Smart Money | 6 | 100% |
-| Profiler | 11 | 100% |
-| Token God Mode | 12 | 100% |
-| Portfolio | 1 | 100% |
-| Search | 1 | 100% |
-| **Total** | **31** | **100%** |
+See [AGENTS.md](AGENTS.md) for architecture and contributor guidance.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",
@@ -18,7 +18,9 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:live": "NANSEN_LIVE_TEST=1 vitest run",
-    "test:swap": "vitest run --config vitest.e2e.config.js",
+    "test:trade": "vitest run --config vitest.e2e.config.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "changeset": "changeset",
     "changeset:version": "changeset version",
     "changeset:publish": "changeset publish"
@@ -52,7 +54,10 @@
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.1",
     "@changesets/cli": "^2.29.4",
+    "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.2",
+    "globals": "^17.4.0",
     "vitest": "^4.0.18"
   }
 }

package/src/api.js

@@ -194,9 +194,9 @@ export function getCachedResponse(endpoint, body, ttlSeconds = DEFAULT_CACHE_TTL
     }
     
     return { ...cached.data, _meta: { ...cached.data._meta, fromCache: true, cacheAge: Math.round(age) } };
-  } catch (e) {
+  } catch (_e) {
     // Invalid cache file, delete it
-    try { fs.unlinkSync(cacheFile); } catch {}
+    try { fs.unlinkSync(cacheFile); } catch { /* ignore */ }
     return null;
   }
 }
@@ -305,7 +305,7 @@ function loadConfig() {
 
   // ~/.nansen/config.json (from `nansen login`)
   if (fs.existsSync(CONFIG_FILE)) {
-    try { config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')); } catch (e) {}
+    try { config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')); } catch (_e) { /* ignore */ }
   }
 
   // Local config.json (for development)
@@ -476,7 +476,7 @@ export class NansenAPI {
       let data;
       try {
         data = await response.json();
-      } catch (err) {
+      } catch (_err) {
         // Non-JSON response (rare, usually server errors)
         const error = new NansenError(
           `Invalid response from API (status ${response.status})`,
@@ -1039,7 +1039,7 @@ export class NansenAPI {
   }
 
   async tokenOhlcv(params = {}) {
-    const { tokenAddress, chain = 'solana', timeframe, pagination } = params;
+    const { tokenAddress, chain = 'solana', timeframe } = params;
     if (tokenAddress) {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
@@ -1048,7 +1048,6 @@ export class NansenAPI {
       token_address: tokenAddress,
       chain,
       timeframe,
-      pagination
     });
   }
 

package/src/cli.js

@@ -88,7 +88,7 @@ export const SCHEMA = {
           description: 'Token God Mode - deep analytics for any token',
           subcommands: {
             'indicators': { description: 'Risk and reward indicators for a token (Nansen Score)', options: { token: { type: 'string', required: true, description: 'Token address' }, chain: { type: 'string', default: 'ethereum' } }, returns: ['token_info[market_cap_usd, market_cap_group, is_stablecoin]', 'risk_indicators[indicator_type, score, signal, signal_percentile, last_trigger_on]', 'reward_indicators[indicator_type, score, signal, signal_percentile, last_trigger_on]'] },
-            'ohlcv': { description: 'OHLCV candle data for a token', options: { token: { type: 'string', required: true, description: 'Token address' }, chain: { type: 'string', default: 'solana' }, timeframe: { type: 'string', default: '1h', enum: ['1m', '5m', '15m', '30m', '1h', '2h', '4h', '1d', '1w', '1M'], description: 'Candle timeframe (e.g., 1h, 4h, 1d)' }, limit: { type: 'number' } }, returns: ['timestamp', 'open', 'high', 'low', 'close', 'volume'] },
+            'ohlcv': { description: 'OHLCV candle data for a token', options: { token: { type: 'string', required: true, description: 'Token address' }, chain: { type: 'string', default: 'solana' }, timeframe: { type: 'string', default: '1h', enum: ['1m', '5m', '15m', '30m', '1h', '2h', '4h', '1d', '1w', '1M'], description: 'Candle timeframe (e.g., 1h, 4h, 1d)' } }, returns: ['timestamp', 'open', 'high', 'low', 'close', 'volume'] },
             'info': { description: 'Get detailed information for a specific token', options: { token: { type: 'string', required: true, description: 'Token address' }, chain: { type: 'string', default: 'solana' }, timeframe: { type: 'string', default: '1d', enum: ['5m', '1h', '6h', '12h', '1d', '7d'] } }, returns: ['token_address', 'token_symbol', 'token_name', 'chain', 'price_usd', 'volume_usd', 'market_cap', 'holder_count', 'liquidity_usd'] },
             'screener': { description: 'Discover and filter tokens', options: { chain: { type: 'string', default: 'solana' }, chains: { type: 'array' }, timeframe: { type: 'string', default: '24h', enum: ['5m', '10m', '1h', '6h', '24h', '7d', '30d'] }, 'smart-money': { type: 'boolean', description: 'Filter for Smart Money only' }, search: { type: 'string', description: 'Filter results by token symbol or name (client-side)' }, limit: { type: 'number' }, sort: { type: 'string' } }, returns: ['token_address', 'token_symbol', 'token_name', 'chain', 'price_usd', 'volume_usd', 'market_cap', 'holder_count', 'smart_money_holders'] },
             'holders': { description: 'Token holder analysis', options: { token: { type: 'string', required: true }, chain: { type: 'string', default: 'solana' }, 'smart-money': { type: 'boolean' }, limit: { type: 'number' } }, returns: ['address', 'address_label', 'token_amount', 'total_outflow', 'total_inflow', 'balance_change_24h', 'balance_change_7d', 'balance_change_30d', 'ownership_percentage', 'value_usd'] },
@@ -220,7 +220,52 @@ export function parseFields(fieldsOption) {
   return fieldsOption.split(',').map(f => f.trim()).filter(f => f.length > 0);
 }
 
-// Parse command line arguments
+/**
+ * Produce a compact schema listing commands with params* notation.
+ * Use `nansen schema --full` for the verbose version.
+ */
+export function compactSchema(schema) {
+  function compactOptions(opts) {
+    if (!opts) return '';
+    return Object.entries(opts)
+      .map(([name, o]) => `${name}${o.required ? '*' : ''}`)
+      .join(', ');
+  }
+
+  function compactCmd(prefix, cmd) {
+    const entries = [];
+    if (cmd.subcommands) {
+      for (const [name, sub] of Object.entries(cmd.subcommands)) {
+        const path = prefix ? `${prefix} ${name}` : name;
+        if (sub.subcommands) {
+          entries.push(...compactCmd(path, sub));
+        } else {
+          const params = compactOptions(sub.options);
+          entries.push({ command: path, description: sub.description, params, returns: sub.returns });
+        }
+      }
+    } else {
+      const params = compactOptions(cmd.options);
+      entries.push({ command: prefix, description: cmd.description, params, returns: cmd.returns });
+    }
+    return entries;
+  }
+
+  const commands = [];
+  for (const [name, cmd] of Object.entries(schema.commands)) {
+    commands.push(...compactCmd(name, cmd));
+  }
+
+  return {
+    version: schema.version,
+    params_legend: '* = required',
+    commands,
+    globalOptions: Object.keys(schema.globalOptions).join(', '),
+    chains: schema.chains,
+    smartMoneyLabels: schema.smartMoneyLabels
+  };
+}
+
 /**
  * Compare two semver strings. Returns 1 if a > b, -1 if a < b, 0 if equal.
  */
@@ -244,7 +289,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') {
+      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full') {
         result.flags[key] = true;
       } else if (next && !next.startsWith('-')) {
         // Try to parse as JSON first (for objects/arrays/booleans),
@@ -635,7 +680,7 @@ export async function traceCounterparties(api, params = {}) {
           queue.push({ addr: cpAddr, hop: hop + 1 });
         }
       }
-    } catch (err) {
+    } catch {
       // Skip addresses that fail (404, etc) but continue the traversal
     }
 
@@ -706,91 +751,41 @@ export async function compareWallets(api, params = {}) {
   };
 }
 
-// ASCII Art Banner
-export const BANNER = `
- ███╗   ██╗ █████╗ ███╗   ██╗███████╗███████╗███╗   ██╗
- ████╗  ██║██╔══██╗████╗  ██║██╔════╝██╔════╝████╗  ██║
- ██╔██╗ ██║███████║██╔██╗ ██║███████╗█████╗  ██╔██╗ ██║
- ██║╚██╗██║██╔══██║██║╚██╗██║╚════██║██╔══╝  ██║╚██╗██║
- ██║ ╚████║██║  ██║██║ ╚████║███████║███████╗██║ ╚████║
- ╚═╝  ╚═══╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝╚═╝  ╚═══╝
-                   Surface The Signal
-`;
+export const BANNER = '';
 
-// Help text
-export const HELP = `
-Nansen CLI - Command-line interface for Nansen API
-Designed for AI agents with structured JSON output.
+export const HELP = `Nansen CLI v${VERSION} — structured JSON output for AI agents.
 
-USAGE:
-  nansen <command> [subcommand] [options]
+USAGE: nansen <command> [subcommand] [options]
 
 COMMANDS:
-  research       Research & analytics (smart-money, profiler, token, search, perp, portfolio, points)
-  trade          DEX trading (quote, execute)
-  wallet         Local wallet management (create, list, show, export, default, delete)
-  login/logout   API key management
-  schema         Output JSON schema for all commands (for agent introspection)
-  cache          Cache management (clear)
-  changelog      Show what's new (use --since <version> to filter)
-  help           Show this help message
-
-GLOBAL OPTIONS:
-  --pretty       Format JSON output for readability
-  --table        Format output as human-readable table
-  --fields       Comma-separated list of fields to include (e.g., --fields address,value_usd)
-  --chain        Blockchain to query (ethereum, solana, base, etc.)
-  --chains       Multiple chains as JSON array
-  --limit        Number of results (shorthand for pagination)
-  --filters      JSON object with filters
-  --sort         Sort by field (e.g., --sort value_usd:desc)
-  --order-by     JSON array with sort order (advanced)
-  --days         Date range in days (default: 30 for most endpoints)
-  --symbol       Token symbol (for perp endpoints)
-  --no-retry     Disable automatic retry on rate limits/errors
-  --retries <n>  Max retry attempts (default: 3)
-  --x402-payment-signature <sig>  Pre-signed x402 payment signature header
-  --cache        Enable response caching (default: off)
-  --no-cache     Disable cache for this request
-  --cache-ttl <s> Cache TTL in seconds (default: 300)
-  --stream       Output as JSON lines (NDJSON) for incremental processing
-  --format csv   Output as CSV with header row
+  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)
+  logout      Remove saved API key
+  schema      JSON schema for all commands (use "nansen schema <cmd>" for one)
+  cache       clear
+  changelog   --since <version> to filter
+
+OPTIONS: --chain --limit --sort field:dir --fields a,b --days N --filters '{}'
+FORMAT:  --pretty --table --format csv --stream (NDJSON)
+RETRY:   --no-retry --retries N --cache --cache-ttl N
 
 EXAMPLES:
-  # Get Smart Money netflow on Solana
   nansen research smart-money netflow --chain solana
-
-  # Get top tokens by Smart Money activity
-  nansen research token screener --chain solana --timeframe 24h --pretty
-
-  # Get wallet balance
-  nansen research profiler balance --address 0x123... --chain ethereum
-
-  # Search for tokens/entities
-  nansen research search "Vitalik"
-
-  # Get a DEX swap quote
+  nansen research token screener --chain solana --timeframe 24h
+  nansen research profiler balance --address 0x... --chain ethereum
   nansen trade quote --chain ethereum --from ETH --to USDC --amount 1
 
-SMART MONEY LABELS:
-  Fund, Smart Trader, 30D Smart Trader, 90D Smart Trader, 
-  180D Smart Trader, Smart HL Perps Trader
+Chains: ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, mantle, ronin, sei, plasma, sonic, monad, hyperevm, iotaevm
+Labels: Fund, Smart Trader, 30D/90D/180D Smart Trader, Smart HL Perps Trader
 
-SUPPORTED CHAINS:
-  ethereum, solana, base, bnb, arbitrum, polygon, optimism,
-  avalanche, linea, scroll, mantle, ronin, sei,
-  plasma, sonic, monad, hyperevm, iotaevm
-
-For more info: https://docs.nansen.ai
+Docs: https://docs.nansen.ai
+Skills: npx skills add nansen-ai/nansen-cli (agent-optimised docs per command group)
 `;
 
 // Helper to prompt for input (exported for mocking)
 export async function prompt(question, hidden = false) {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-  
   return new Promise((resolve) => {
     if (hidden && process.stdout.isTTY) {
       process.stdout.write(question);
@@ -805,7 +800,6 @@ export async function prompt(question, hidden = false) {
           process.stdin.pause();
           process.stdin.removeListener('data', onData);
           process.stdout.write('\n');
-          rl.close();
           resolve(input);
         } else if (char === '\u0003') {
           // Ctrl+C
@@ -824,6 +818,10 @@ export async function prompt(question, hidden = false) {
       
       process.stdin.on('data', onData);
     } else {
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
       rl.question(question, (answer) => {
         rl.close();
         resolve(answer);
@@ -836,11 +834,11 @@ export async function prompt(question, hidden = false) {
 export function buildCommands(deps = {}) {
   // Allow dependency injection for testing
   const {
-    api = null,
+    api: _api = null,
     promptFn = prompt,
     log = console.log,
-    errorOutput = console.error,
-    NansenAPIClass = NansenAPI,
+    errorOutput: _errorOutput = console.error,
+    NansenAPIClass: _NansenAPIClass = NansenAPI,
     saveConfigFn = saveConfig,
     deleteConfigFn = deleteConfig,
     getConfigFileFn = getConfigFile,
@@ -850,6 +848,18 @@ export function buildCommands(deps = {}) {
 
   const cmds = {
     'login': async (args, apiInstance, flags, options) => {
+      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('OPTIONS:');
+        log('  --api-key <key>   Your Nansen API key');
+        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;
 
@@ -885,10 +895,10 @@ export function buildCommands(deps = {}) {
 
       log(`✓ Saved to ${getConfigFileFn()}\n`);
       log('You can now use the Nansen CLI. Try:');
-      log('  nansen token screener --chain solana --pretty');
+      log('  nansen research token screener --chain solana --pretty');
     },
 
-    'logout': async (args, apiInstance, flags, options) => {
+    'logout': async (_args, _apiInstance, _flags, _options) => {
       const deleted = deleteConfigFn();
       if (deleted) {
         log(`✓ Removed ${getConfigFileFn()}`);
@@ -897,11 +907,11 @@ export function buildCommands(deps = {}) {
       }
     },
 
-    'help': async (args, apiInstance, flags, options) => {
+    'help': async (_args, _apiInstance, _flags, _options) => {
       log(HELP);
     },
 
-    'changelog': async (args, apiInstance, flags, options) => {
+    'changelog': async (_args, _apiInstance, _flags, _options) => {
       const changelogPath = new URL('../CHANGELOG.md', import.meta.url).pathname;
       let content;
       try {
@@ -910,7 +920,7 @@ export function buildCommands(deps = {}) {
         log('CHANGELOG.md not found. Visit https://github.com/nansen-ai/nansen-cli/blob/main/CHANGELOG.md');
         return;
       }
-      const since = options.since;
+      const since = _options.since;
       if (since) {
         // Show only entries from the given version onwards
         const lines = content.split('\n');
@@ -936,8 +946,7 @@ export function buildCommands(deps = {}) {
       }
     },
 
-    'schema': async (args, apiInstance, flags, options) => {
-      // Return schema for agent introspection
+    'schema': async (args, _apiInstance, flags, _options) => {
       const subcommand = args[0];
       const schemaEntry = subcommand && (SCHEMA.commands[subcommand] || SCHEMA.commands.research.subcommands[subcommand]);
 
@@ -951,11 +960,14 @@ export function buildCommands(deps = {}) {
         };
       }
 
-      // Return full schema
-      return SCHEMA;
+      if (flags.full) {
+        return SCHEMA;
+      }
+
+      return compactSchema(SCHEMA);
     },
 
-    'cache': async (args, apiInstance, flags, options) => {
+    'cache': async (args, _apiInstance, _flags, _options) => {
       const subcommand = args[0] || 'help';
       
       const handlers = {
@@ -1139,7 +1151,7 @@ export function buildCommands(deps = {}) {
 
       const handlers = {
         'indicators': () => apiInstance.tokenIndicators({ tokenAddress, chain }),
-        'ohlcv': () => apiInstance.tokenOhlcv({ tokenAddress, chain, timeframe: options.timeframe || '1d', pagination }),
+        'ohlcv': () => apiInstance.tokenOhlcv({ tokenAddress, chain, timeframe: options.timeframe || '1d' }),
         'info': () => apiInstance.tokenInformation({ tokenAddress, chain, timeframe: options.timeframe }),
         'screener': async () => {
           const search = options.search;
@@ -1299,7 +1311,7 @@ export function buildCommands(deps = {}) {
     }
     const category = RESEARCH_CATEGORY_ALIASES[rawCategory] || rawCategory;
     if (!RESEARCH_CATEGORIES.has(category)) {
-      return { error: `Unknown research category: ${rawCategory}`, available: [...RESEARCH_CATEGORIES] };
+      throw new NansenError(`Unknown research category: ${rawCategory}. Available: ${[...RESEARCH_CATEGORIES].join(', ')}`, ErrorCode.UNKNOWN);
     }
     return cmds[category](args.slice(1), apiInstance, flags, options);
   };
@@ -1335,10 +1347,7 @@ SYMBOLS:
       return;
     }
     if (!tradingCmds[sub]) {
-      log(`Unknown trade subcommand: ${sub}`);
-      log(`Available: quote, execute`);
-      log(`Run 'nansen trade help' for usage.`);
-      return;
+      throw new NansenError(`Unknown trade subcommand: ${sub}. Available: quote, execute`, ErrorCode.UNKNOWN);
     }
     return tradingCmds[sub](args.slice(1), apiInstance, flags, options);
   };
@@ -1351,9 +1360,6 @@ export const DEPRECATED_TO_RESEARCH = new Set(['smart-money', 'profiler', 'token
 // Subcommands that moved under 'trade'
 export const DEPRECATED_TO_TRADE = new Set(['quote', 'execute']);
 
-// Commands that don't require API authentication
-export const NO_AUTH_COMMANDS = ['login', 'logout', 'help', 'schema', 'cache', 'wallet', 'trade', 'quote', 'execute', 'changelog'];
-
 // Command aliases: top-level shortcuts that resolve before routing
 export const COMMAND_ALIASES = {
   'tgm': 'token',           // Token God Mode
@@ -1372,7 +1378,6 @@ export const RESEARCH_CATEGORY_ALIASES = {
 
 // Generate help text for a specific subcommand using SCHEMA
 export function generateSubcommandHelp(command, subcommand) {
-  // Look up in top-level commands, then fall back to research subcommands
   const cmdSchema = SCHEMA.commands[command] || SCHEMA.commands.research.subcommands[command];
   if (!cmdSchema) return null;
 
@@ -1380,100 +1385,36 @@ export function generateSubcommandHelp(command, subcommand) {
   if (!subSchema) return null;
 
   const lines = [];
-  lines.push(`\n${command} ${subcommand} - ${subSchema.description || 'No description'}\n`);
-  
-  // Usage
-  const requiredOpts = [];
-  const optionalOpts = [];
-  
+  lines.push(`${command} ${subcommand} — ${subSchema.description || 'No description'}`);
+
   if (subSchema.options) {
-    for (const [name, opt] of Object.entries(subSchema.options)) {
-      if (opt.required) {
-        requiredOpts.push(name);
-      } else {
-        optionalOpts.push(name);
-      }
-    }
-  }
-  
-  let usage = `USAGE:\n  nansen ${command} ${subcommand}`;
-  if (requiredOpts.length) {
-    usage += ' ' + requiredOpts.map(o => `--${o} <value>`).join(' ');
-  }
-  if (optionalOpts.length) {
-    usage += ' [options]';
-  }
-  lines.push(usage);
-  
-  // Required options
-  if (requiredOpts.length) {
-    lines.push('\nREQUIRED:');
-    for (const name of requiredOpts) {
-      const opt = subSchema.options[name];
-      const desc = opt.description || `${opt.type}`;
-      lines.push(`  --${name.padEnd(16)} ${desc}`);
-    }
-  }
-  
-  // Optional options
-  if (optionalOpts.length) {
-    lines.push('\nOPTIONS:');
-    for (const name of optionalOpts) {
-      const opt = subSchema.options[name];
-      const defaultStr = opt.default !== undefined ? ` (default: ${opt.default})` : '';
-      const desc = (opt.description || opt.type) + defaultStr;
-      lines.push(`  --${name.padEnd(16)} ${desc}`);
-    }
+    const params = Object.entries(subSchema.options).map(([name, opt]) => {
+      const parts = [`--${name}`];
+      if (opt.required) parts[0] += '*';
+      if (opt.default !== undefined) parts.push(`(${opt.default})`);
+      if (opt.enum) parts.push(`[${opt.enum.join('|')}]`);
+      return parts.join(' ');
+    });
+    lines.push(`Params (* required): ${params.join(', ')}`);
   }
-  
-  // Return fields
-  if (subSchema.returns && subSchema.returns.length) {
-    lines.push('\nRETURNS:');
-    lines.push(`  ${subSchema.returns.join(', ')}`);
+
+  if (subSchema.returns?.length) {
+    lines.push(`Returns: ${subSchema.returns.join(', ')}`);
   }
-  
-  // Examples
-  lines.push('\nEXAMPLES:');
+
+  const exampleValues = { address: '0x...', token: '0x...', query: '"term"', symbol: 'BTC', date: '2024-01-01' };
   const chain = subSchema.options?.chain?.default || 'solana';
-  
-  // Example values for common required options
-  const exampleValues = {
-    address: '0x123...',
-    token: '0x123...',
-    query: '"search term"',
-    symbol: 'BTC',
-    date: '2024-01-01'
-  };
-  
-  // Build example based on required options
-  let example = `  nansen ${command} ${subcommand}`;
-  for (const name of requiredOpts) {
-    const value = exampleValues[name] || '<value>';
-    example += ` --${name} ${value}`;
+  let example = `nansen ${command} ${subcommand}`;
+  if (subSchema.options) {
+    for (const [name, opt] of Object.entries(subSchema.options)) {
+      if (opt.required) example += ` --${name} ${exampleValues[name] || '<val>'}`;
+    }
   }
-  if (subSchema.options?.chain && !requiredOpts.includes('chain')) {
+  if (subSchema.options?.chain && !subSchema.options.chain.required) {
     example += ` --chain ${chain}`;
   }
-  example += ' --pretty';
-  lines.push(example);
-  
-  // Add a filtered example if filters are supported
-  if (subSchema.options?.filters || subSchema.options?.labels) {
-    let filterExample = `  nansen ${command} ${subcommand}`;
-    for (const name of requiredOpts) {
-      const value = exampleValues[name] || '<value>';
-      filterExample += ` --${name} ${value}`;
-    }
-    if (subSchema.options?.chain && !requiredOpts.includes('chain')) {
-      filterExample += ` --chain ${chain}`;
-    }
-    if (subSchema.options?.labels) {
-      filterExample += ' --labels "Smart Trader"';
-    }
-    filterExample += ' --limit 10 --table';
-    lines.push(filterExample);
-  }
-  
+  lines.push(`Example: ${example}`);
+
   return lines.join('\n');
 }
 
@@ -1542,13 +1483,10 @@ export async function runCLI(rawArgs, deps = {}) {
         const researchCat = SCHEMA.commands.research.subcommands[category];
         if (researchCat) {
           const catSchema = researchCat;
-          const lines = [`\nresearch ${category} - ${catSchema.description}\n`];
+          const lines = [`research ${category} — ${catSchema.description}`];
           if (catSchema.subcommands) {
-            lines.push('SUBCOMMANDS:');
-            for (const [sub, subSchema] of Object.entries(catSchema.subcommands)) {
-              lines.push(`  ${sub.padEnd(20)} ${subSchema.description || ''}`);
-            }
-            lines.push(`\nFor detailed help: nansen research ${category} <subcommand> --help`);
+            lines.push('Subcommands: ' + Object.keys(catSchema.subcommands).join(', '));
+            lines.push(`Use: nansen research ${category} <subcommand> --help`);
           }
           output(lines.join('\n'));
           notify();
@@ -1577,13 +1515,10 @@ export async function runCLI(rawArgs, deps = {}) {
       const cmdSchemaLookup = SCHEMA.commands[command] || SCHEMA.commands.research.subcommands[command];
       if (command && cmdSchemaLookup) {
         const cmdSchema = cmdSchemaLookup;
-        const lines = [`\n${command} - ${cmdSchema.description}\n`];
+        const lines = [`${command} — ${cmdSchema.description}`];
         if (cmdSchema.subcommands) {
-          lines.push('SUBCOMMANDS:');
-          for (const [sub, subSchema] of Object.entries(cmdSchema.subcommands)) {
-            lines.push(`  ${sub.padEnd(20)} ${subSchema.description || ''}`);
-          }
-          lines.push(`\nFor detailed help: nansen ${command} <subcommand> --help`);
+          lines.push('Subcommands: ' + Object.keys(cmdSchema.subcommands).join(', '));
+          lines.push(`Use: nansen ${command} <subcommand> --help`);
         }
         output(lines.join('\n'));
         notify();
@@ -1610,48 +1545,46 @@ export async function runCLI(rawArgs, deps = {}) {
     return { type: 'error', data: errorData };
   }
 
-  // Commands that don't require API authentication
-  if (NO_AUTH_COMMANDS.includes(command)) {
-    const result = await commands[command](subArgs, null, flags, options);
-    
-    // Schema command returns data that should be output
-    if (command === 'schema' && result) {
-      const formatted = formatOutput(result, { pretty, table: false });
-      output(formatted.text);
-      notify();
-      return { type: 'schema', data: result };
-    }
-
-    notify();
-    return { type: 'no-auth', command };
-  }
-
   try {
     // Configure retry options
-    const retryOptions = flags['no-retry'] 
-      ? { maxRetries: 0 } 
+    const retryOptions = flags['no-retry']
+      ? { maxRetries: 0 }
       : { maxRetries: options.retries !== undefined ? (Number.isNaN(parseInt(options.retries, 10)) ? 3 : parseInt(options.retries, 10)) : 3 };
-    
+
     // Configure cache options
     const cacheTtl = options['cache-ttl'] !== undefined ? parseInt(options['cache-ttl'], 10) : 300;
     const cacheOptions = {
       enabled: flags['cache'] && !flags['no-cache'],
       ttl: Number.isNaN(cacheTtl) ? 300 : cacheTtl
     };
-    
+
     const defaultHeaders = {};
     if (options['x402-payment-signature']) {
       defaultHeaders['Payment-Signature'] = options['x402-payment-signature'];
     }
     const api = new NansenAPIClass(undefined, undefined, { retry: retryOptions, cache: cacheOptions, defaultHeaders });
     let result = await commands[command](subArgs, api, flags, options);
-    
+
+    // Commands that handle their own output return undefined
+    if (result === undefined) {
+      notify();
+      return { type: 'no-output', command };
+    }
+
+    // Schema returns data directly (not wrapped in { success, data })
+    if (command === 'schema') {
+      const formatted = formatOutput(result, { pretty, table: false });
+      output(formatted.text);
+      notify();
+      return { type: 'schema', data: result };
+    }
+
     // Apply field filtering if --fields is specified
     const fields = parseFields(options.fields);
     if (fields) {
       result = filterFields(result, fields);
     }
-    
+
     // Output in requested format
     if (stream) {
       // Stream mode: output each record as a JSON line (NDJSON)

package/src/trading.js

@@ -742,7 +742,7 @@ export function validateBaseUnitAmount(amount) {
   return null;
 }
 
-function formatQuote(quote, index) {
+export function formatQuote(quote, index) {
   const lines = [];
   const label = index !== undefined ? `  Quote #${index + 1}` : '  Best Quote';
   lines.push(`${label} (${quote.aggregator || 'unknown'})`);
@@ -750,10 +750,21 @@ function formatQuote(quote, index) {
   lines.push(`    Output:       ${quote.outAmount} → ${quote.outputMint?.slice(0, 12)}...`);
   if (quote.inUsdValue)  lines.push(`    In USD:       $${quote.inUsdValue}`);
   if (quote.outUsdValue) lines.push(`    Out USD:      $${quote.outUsdValue}`);
-  if (quote.priceImpactPct) lines.push(`    Price Impact: ${quote.priceImpactPct}%`);
+  if (quote.priceImpactPct) {
+    const impactAbs = Math.abs(parseFloat(quote.priceImpactPct));
+    if (impactAbs <= 5) {
+      lines.push(`    Price Impact: ${impactAbs}%`);
+    }
+  }
   if (quote.tradingFeeInUsd) lines.push(`    Trading Fee:  $${quote.tradingFeeInUsd}`);
   if (quote.networkFeeInUsd) lines.push(`    Network Fee:  $${quote.networkFeeInUsd}`);
   if (quote.approvalAddress && !isNativeToken(quote.inputMint)) lines.push(`    ⚠ Requires token approval to: ${quote.approvalAddress}`);
+  if (quote.priceImpactPct) {
+    const impactAbs = Math.abs(parseFloat(quote.priceImpactPct));
+    if (impactAbs > 5) {
+      lines.push(`    ⚠ Price impact is ${impactAbs}%! You may lose significant value.`);
+    }
+  }
   return lines.join('\n');
 }
 
@@ -833,11 +844,15 @@ EXAMPLES:
           const wallet = showWallet(walletName);
           walletAddress = chainType === 'solana' ? wallet.solana : wallet.evm;
         } else {
-          walletAddress = getDefaultAddress(chainType);
+          try {
+            walletAddress = getDefaultAddress(chainType);
+          } catch {
+            // No wallet configured — fall through to the check below
+          }
         }
 
         if (!walletAddress) {
-          errorOutput('No wallet found. Create one with: nansen wallet create');
+          errorOutput('No wallet found. A wallet address is required for quotes because the trading API builds a transaction specific to the sender.\nCreate one with: nansen wallet create');
           exit(1);
           return;
         }
@@ -877,6 +892,9 @@ EXAMPLES:
         const quoteId = saveQuote(response, chain, isWalletConnect ? 'walletconnect' : 'local');
         errorOutput(`\n  Quote ID: ${quoteId}`);
         errorOutput(`  Execute:  nansen trade execute --quote ${quoteId}`);
+        if (response.quotes.length > 1) {
+          errorOutput(`  Pin #1:  nansen trade execute --quote ${quoteId} --quote-index 0`);
+        }
 
         if (response.quotes[0]?.approvalAddress && !isNativeToken(response.quotes[0]?.inputMint)) {
           errorOutput(`\n  Warning: This token swap requires an ERC-20 approval step.`);

package/src/transfer.js

@@ -6,7 +6,7 @@
 
 import crypto from 'crypto';
 import { base58Encode, exportWallet, getWalletConfig, verifyPassword } from './wallet.js';
-import { keccak256, signSecp256k1, rlpEncode, bigIntToMinBuf } from './crypto.js';
+import { keccak256, signSecp256k1, rlpEncode } from './crypto.js';
 import { getWalletConnectAddress, sendTransactionViaWalletConnect } from './walletconnect-trading.js';
 import { EVM_CHAIN_IDS } from './chain-ids.js';
 
@@ -217,7 +217,6 @@ async function buildEvmTransaction({ to, amount, token, privateKey, chain, max =
       const safeReserve = l2GasCost * 3n;
       if (ethBalance <= safeReserve) throw new Error(`Insufficient balance: ${ethBalance} wei (need > ${safeReserve} for gas + L1 fees)`);
       txValue = ethBalance - safeReserve;
-      amount = txValue;
       stderr(`  Max send: ${formatAmount(txValue, 18)} ETH (reserved ${formatAmount(safeReserve, 18)} for gas)`);
     } else {
       txValue = amount;
@@ -375,7 +374,7 @@ async function buildSolanaTransaction({ to, amount, amountStr, token, privateKey
       }
     } catch (e) {
       if (e.message.includes('Insufficient')) throw e;
-      throw new Error(`Source token account not found. Do you hold this token?`);
+      throw new Error(`Source token account not found. Do you hold this token?`, { cause: e });
     }
 
     // TransferChecked instruction data: [12, amount u64 LE, decimals u8]
@@ -568,7 +567,7 @@ async function validateErc20Token(rpcUrl, tokenAddress) {
     return decimals;
   } catch (e) {
     if (e.message.includes('not a valid')) throw e;
-    throw new Error(`Contract ${tokenAddress} does not implement ERC-20 decimals() — may not be a valid token`);
+    throw new Error(`Contract ${tokenAddress} does not implement ERC-20 decimals() — may not be a valid token`, { cause: e });
   }
 }
 
@@ -626,7 +625,7 @@ export async function sendTokens({ to, amount, chain, token = null, wallet = nul
     } else if (max && token) {
       // Max SPL: full token balance
       const rpcUrl = CHAIN_RPCS.solana;
-      const { tokenProgram, decimals } = await getTokenInfo(rpcUrl, token);
+      const { tokenProgram, decimals: _decimals } = await getTokenInfo(rpcUrl, token);
       const sourceATA = deriveATA(walletData.solana.address, token, tokenProgram);
       const sourceAtaAddr = base58Encode(sourceATA);
       const ataInfo = await rpcCall(rpcUrl, 'getTokenAccountBalance', [sourceAtaAddr]);
@@ -721,7 +720,7 @@ async function sendTokensViaWalletConnect({ to, amount, chain, token, max, dryRu
   const wcAddress = await getWalletConnectAddress();
   if (!wcAddress) throw new Error('No WalletConnect session active. Run: walletconnect connect');
 
-  let txTo, txValue, txData, decimals = 18;
+  let txTo, txValue, txData;
 
   if (token) {
     // Validate ERC-20 contract
@@ -730,7 +729,7 @@ async function sendTokensViaWalletConnect({ to, amount, chain, token, max, dryRu
       throw new Error(`Address ${token} is not a contract — not a valid ERC-20 token`);
     }
     const decResult = await rpcCall(rpcUrl, 'eth_call', [{ to: token, data: '0x313ce567' }, 'latest']);
-    decimals = parseInt(decResult, 16);
+    const decimals = parseInt(decResult, 16);
 
     if (max) {
       // Max ERC-20: full token balance
@@ -809,14 +808,11 @@ async function sendTokensViaWalletConnect({ to, amount, chain, token, max, dryRu
     chainId,
   });
 
-  let txHash;
-  if (wcResult.txHash) {
-    txHash = wcResult.txHash;
-  } else if (wcResult.signedTransaction) {
-    txHash = await broadcastTransaction(wcResult.signedTransaction, chain);
-  } else {
+  const txHash = await (async () => {
+    if (wcResult.txHash) return wcResult.txHash;
+    if (wcResult.signedTransaction) return broadcastTransaction(wcResult.signedTransaction, chain);
     throw new Error('No transaction hash or signed transaction returned from WalletConnect');
-  }
+  })();
 
   // Wait for confirmation
   const confirmation = await waitForEvmConfirmation(rpcUrl, txHash);

package/src/wallet.js

@@ -26,7 +26,7 @@ const SCRYPT_P = 1;
 const SCRYPT_KEYLEN = 32;
 const SALT_LEN = 16;
 const IV_LEN = 12;
-const AUTH_TAG_LEN = 16;
+const _AUTH_TAG_LEN = 16;
 
 import { keccak256 } from './crypto.js';
 
@@ -481,7 +481,7 @@ export function getDefaultAddress(chainType = 'evm') {
  * Build wallet command handlers for integration into CLI.
  */
 export function buildWalletCommands(deps = {}) {
-  const { log = console.log, promptFn, exit = process.exit } = deps;
+  const { log = console.log, promptFn: _promptFn, exit = process.exit } = deps;
 
   return {
     'wallet': async (args, apiInstance, flags, options) => {

package/src/walletconnect-exec.js

@@ -11,7 +11,7 @@ import { execFile } from 'child_process';
  */
 export function wcExec(cmd, args, timeoutMs = 10000) {
   return new Promise((resolve, reject) => {
-    execFile(cmd, args, { timeout: timeoutMs }, (err, stdout, stderr) => {
+    execFile(cmd, args, { timeout: timeoutMs }, (err, stdout, _stderr) => {
       if (err) {
         reject(new Error(err.message));
         return;

package/src/x402-svm.js

@@ -30,11 +30,11 @@ export function base58Encode(buf) {
 // ============= Constants =============
 
 const TOKEN_PROGRAM = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
-const TOKEN_2022_PROGRAM = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';
+const _TOKEN_2022_PROGRAM = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';
 const COMPUTE_BUDGET_PROGRAM = 'ComputeBudget111111111111111111111111111111';
 const MEMO_PROGRAM = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr';
 const ATA_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
-const SYSTEM_PROGRAM = '11111111111111111111111111111111';
+const _SYSTEM_PROGRAM = '11111111111111111111111111111111';
 
 const DEFAULT_COMPUTE_UNIT_LIMIT = 20000;
 const DEFAULT_COMPUTE_UNIT_PRICE_MICROLAMPORTS = 1;
@@ -186,7 +186,7 @@ function modInverse(a, mod) {
  * Build a Solana MessageV0 from accounts and instructions.
  * Simplified builder for x402 payment transactions.
  */
-function buildMessageV0({ feePayer, instructions, recentBlockhash, accounts }) {
+function buildMessageV0({ feePayer, instructions, recentBlockhash, accounts: _accounts }) {
   // All unique accounts in order: feePayer first, then signers, then rest
   const accountMap = new Map();
   const feePayerKey = feePayer;

package/src/x402.js

@@ -154,7 +154,7 @@ export async function createPaymentSignature(response, url, options = {}) {
  */
 export async function checkX402Balance(network) {
   try {
-    const { listWallets, exportWallet } = await import('./wallet.js');
+    const { listWallets, exportWallet: _exportWallet } = await import('./wallet.js');
     const wallets = listWallets();
     if (!wallets.defaultWallet) return null;