nansen-cli 1.7.0 → 1.9.0

package/README.md

@@ -2,8 +2,7 @@
 
 [![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)
-[![Tests](https://img.shields.io/badge/tests-325%20passing-brightgreen.svg)]()
-[![Coverage](https://img.shields.io/badge/coverage-83%25-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-577%20passing-brightgreen.svg)]()
 
 > **Built by agents, for agents.** We prioritize the best possible AI agent experience.
 
@@ -47,32 +46,63 @@ nansen login
 # ✓ Saved to ~/.nansen/config.json
 ```
 
-**Option 2: Environment variable**
+**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
+
+```bash
+# Check CLI is installed (no API key needed):
+nansen schema | head -1
+
+# Verify API access:
+nansen research token screener --chain solana --limit 1
+```
+
 ## Quick Start
 
 ```bash
 # Get trending tokens on Solana
-nansen token screener --chain solana --timeframe 24h --pretty
+nansen research token screener --chain solana --timeframe 24h --pretty
 
 # Check Smart Money activity
-nansen smart-money netflow --chain solana --pretty
+nansen research smart-money netflow --chain solana --pretty
 
 # Profile a wallet
-nansen profiler balance --address 0x28c6c06298d514db089934071355e5743bf21d60 --chain ethereum --pretty
+nansen research profiler balance --address 0x28c6c06298d514db089934071355e5743bf21d60 --chain ethereum --pretty
 
-# Search for an entity
-nansen profiler search --query "Vitalik Buterin" --pretty
+# Search for tokens/entities
+nansen research search "Vitalik Buterin" --pretty
 ```
 
 ## Commands
 
-### `smart-money` - Smart Money Analytics
+All analytics live under `nansen research`, trading under `nansen trade`, and wallet management under `nansen wallet`.
+
+### `research` - Research & Analytics
+
+```
+nansen research <category> <subcommand> [options]
+```
+
+**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.
 
@@ -85,17 +115,19 @@ Track trading and holding activity of sophisticated market participants.
 | `dcas` | DCA strategies on Jupiter |
 | `historical-holdings` | Historical holdings over time |
 
-**Smart Money Labels:**
-- `Fund` - Institutional investment funds
-- `Smart Trader` - Historically profitable traders
-- `30D Smart Trader` - Top performers (30-day window)
-- `90D Smart Trader` - Top performers (90-day window)
-- `180D Smart Trader` - Top performers (180-day window)
-- `Smart HL Perps Trader` - Profitable Hyperliquid traders
+**Smart Money Labels:** `Fund`, `Smart Trader`, `30D Smart Trader`, `90D Smart Trader`, `180D Smart Trader`, `Smart HL Perps Trader`
+
+#### `research profiler` - Wallet Profiling
 
-### `profiler` - Wallet Profiling
+**ENS Name Resolution:** You can use `.eth` names anywhere an `--address` is accepted:
 
-Detailed information about any blockchain address.
+```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 |
 |------------|-------------|
@@ -111,9 +143,7 @@ Detailed information about any blockchain address.
 | `perp-positions` | Current perpetual positions |
 | `perp-trades` | Perpetual trading history |
 
-### `token` - Token God Mode
-
-Deep analytics for any token.
+#### `research token` - Token God Mode
 
 | Subcommand | Description |
 |------------|-------------|
@@ -126,53 +156,51 @@ Deep analytics for any token.
 | `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 |
 
-### `portfolio` - Portfolio Analytics
-
-| Subcommand | Description |
-|------------|-------------|
-| `defi` | DeFi holdings across protocols |
+#### `research search` / `research perp` / `research portfolio` / `research points`
 
-### `search` - Search
+See `nansen research help` or `nansen schema --pretty` for full details.
 
-Search for tokens and entities across Nansen.
+### `trade` - DEX Trading
 
 ```bash
-nansen search "uniswap" --pretty
-nansen search "uniswap" --type token --chain ethereum
+# 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
 ```
 
-| Option | Description |
-|--------|-------------|
-| `--type` | Filter by result type: `token`, `entity`, or `any` (default) |
-| `--chain` | Filter by chain |
-| `--limit` | Max results, 1-50 (default: 25) |
+### `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
 
-Output JSON schema for agent introspection. No API key required.
+No API key required. Machine-readable command reference for agent introspection.
 
 ```bash
-# Get full schema
-nansen schema --pretty
-
-# Get schema for specific command
-nansen schema smart-money --pretty
+nansen schema --pretty                    # All commands
+nansen schema research --pretty           # Research commands
 ```
 
-Returns command definitions, option types/defaults, supported chains, and smart money labels.
-
-### `cache` - Cache Management
+### Deprecated Flat Commands
 
-Manage the local response cache.
-
-```bash
-# Clear all cached responses
-nansen cache clear
-```
+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
 
@@ -181,10 +209,9 @@ nansen cache clear
 | `--pretty` | Format JSON output for readability |
 | `--table` | Format output as human-readable table |
 | `--fields <list>` | Comma-separated fields to include (reduces response size) |
-| `--cache` | Enable response caching |
-| `--no-cache` | Bypass cache for this request |
+| `--stream` | Output as NDJSON for incremental processing |
+| `--cache` / `--no-cache` | Enable/disable response caching |
 | `--cache-ttl <s>` | Cache TTL in seconds (default: 300) |
-| `--stream` | Output as JSON lines (NDJSON) for incremental processing |
 | `--chain <chain>` | Blockchain to query |
 | `--chains <json>` | Multiple chains as JSON array |
 | `--limit <n>` | Number of results |
@@ -192,96 +219,120 @@ nansen cache clear
 | `--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 |
-| `--order-by <json>` | Sort order as JSON array (advanced) |
 | `--labels <label>` | Smart Money label filter |
 | `--smart-money` | Filter for Smart Money only |
 | `--timeframe <tf>` | Time window (5m, 10m, 1h, 6h, 24h, 7d, 30d) |
 
 ## Supported Chains
 
-`ethereum`, `solana`, `base`, `bnb`, `arbitrum`, `polygon`, `optimism`, `avalanche`, `linea`, `scroll`, `zksync`, `mantle`, `ronin`, `sei`, `plasma`, `sonic`, `unichain`, `monad`, `hyperevm`, `iotaevm`
+`ethereum` `solana` `base` `bnb` `arbitrum` `polygon` `optimism` `avalanche` `linea` `scroll` `zksync` `mantle` `ronin` `sei` `plasma` `sonic` `unichain` `monad` `hyperevm` `iotaevm`
 
-## AI Agent Integration
+> Run `nansen schema` to get the current chain list (source of truth).
 
-This CLI is built specifically for AI agents. Every design decision prioritizes agent usability.
+## Agent-Optimized Patterns
 
-**Getting Started:**
-Direct your users to [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/agent-setup) for seamless authentication. See [AI Agent Access](https://docs.nansen.ai/reference/ai-agent-access) for full documentation.
+### Reduce Token Burn with `--fields`
 
-**Why agents love it:**
-- **Structured Output**: All responses are JSON with consistent schema — no parsing HTML or unstructured text
-- **Predictable Errors**: Errors include status codes and actionable details agents can handle programmatically
-- **Zero Config**: Works with just an API key — no complex setup
-- **Composable**: Commands can be chained with shell pipes
-- **Discoverable**: `help` commands at every level for agent introspection
+```bash
+# ❌ Returns everything (huge JSON, wastes agent context)
+nansen research smart-money netflow --chain solana
 
-```json
-// Success response
-{
-  "success": true,
-  "data": {
-    "results": [...],
-    "pagination": {...}
-  }
-}
-
-// Error response
-{
-  "success": false,
-  "error": "API error message",
-  "code": "UNAUTHORIZED",
-  "status": 401,
-  "details": {...}
-}
+# ✅ Only what you need
+nansen research smart-money netflow --chain solana --fields token_symbol,net_flow_usd,chain --limit 10
 ```
 
-## Examples
+### Use `--stream` for Large Results
+
+```bash
+# NDJSON mode — process line by line, don't buffer giant arrays
+nansen research token dex-trades --chain solana --limit 100 --stream
+```
+
+### x402 Micropayments
+
+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
-# Get trending tokens as a table, sorted by volume
-nansen token screener --chain solana --sort buy_volume:desc --table
+# 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
+```
 
-# Get Smart Money DEX trades from Funds only
-nansen smart-money dex-trades --chain ethereum --labels Fund --table
+## Pagination
 
-# Get token holders with Smart Money filter
-nansen token holders --token So11111111111111111111111111111111111111112 --chain solana --smart-money
+Use `--limit N` to control result count. The CLI always fetches page 1 (there is no `--page` flag).
 
-# Get historical holdings for the past 7 days
-nansen smart-money historical-holdings --chain solana --days 7
+**Detecting the last page:** If results returned < your `--limit`, you've reached the end.
 
-# Get BTC perpetual positions on Hyperliquid
-nansen token perp-positions --symbol BTC --pretty
+## Output Format
 
-# Get top PnL traders for a token, sorted by realized PnL
-nansen token pnl --token JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN --chain solana --days 30 --sort pnl_usd:desc --table
+### Response envelope
 
-# Filter response to specific fields (reduces tokens for AI agents)
-nansen smart-money netflow --chain solana --fields token_symbol,net_flow_usd,chain
+```json
+// Success
+{ "success": true, "data": <raw_api_response> }
 
-# Get schema for agent introspection
-nansen schema --pretty
-nansen schema token --pretty
+// Error
+{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "details": {...} }
 ```
 
-## Development
+### Response shapes vary by endpoint
 
-```bash
-# Run tests (mocked, no API key needed)
-npm test
+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 |
 
-# Run with coverage
-npm run test:coverage
+`--table` and `--stream` handle this automatically. For raw JSON parsing:
 
-# Run against live API
-NANSEN_API_KEY=your-key npm run test:live
+```bash
+nansen research smart-money netflow --chain solana | jq 'keys, .data | keys'
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
+### Error codes
 
-**AI agents:** See [AGENTS.md](AGENTS.md) for the agent quick-start (install, auth, patterns, troubleshooting).
+| 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. |
+| `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). |
+
+## 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)
+```
 
-**AI contributors:** See [CLAUDE.md](CLAUDE.md) for agent-specific guidance on contributing to this repo.
+See [AGENTS.md](AGENTS.md) for contributor guidance (architecture, testing patterns, style guide).
 
 ## API Coverage