nansen-cli 1.7.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.7.0",
+  "version": "1.9.0",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",
@@ -9,10 +9,12 @@
   },
   "scripts": {
     "start": "node src/index.js",
+    "pretest": "node scripts/check-changeset.js",
     "test": "vitest run",
     "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",
     "changeset": "changeset",
     "changeset:version": "changeset version",
     "changeset:publish": "changeset publish"

package/scripts/check-changeset.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+/**
+ * Non-blocking check: warns if the current branch has no new changeset file
+ * compared to main. Runs as a pretest hook so agents and humans see a reminder.
+ * Always exits 0 — this is a nudge, not a gate.
+ */
+
+import { execSync } from "child_process";
+
+try {
+  const branch = execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8" }).trim();
+  if (branch === "main") process.exit(0);
+
+  const newChangesets = execSync(
+    "git diff main --name-only --diff-filter=A -- .changeset/*.md",
+    { encoding: "utf8" }
+  ).trim();
+
+  if (!newChangesets) {
+    console.error(
+      "\x1b[33m[changeset] No new changeset file found on this branch. " +
+      "If this PR changes user-facing behavior, add one: npx changeset\x1b[0m"
+    );
+  }
+} catch {
+  // Not a git repo, main doesn't exist, etc. — skip silently.
+}