nansen-cli 1.8.0 → 1.9.1

package/CLAUDE.md

@@ -1,217 +0,0 @@
-# CLAUDE.md
-
-AI assistant guide for contributing to nansen-cli.
-
-## What This Is
-
-A CLI for the [Nansen API](https://docs.nansen.ai), designed specifically for AI agents. All output is structured JSON. 30 endpoints across Smart Money, Profiler, Token God Mode, and Portfolio.
-
-## Quick Start
-
-```bash
-npm install
-npm test           # Run mocked tests (no API key needed)
-npm run test:live  # Run against live API (needs NANSEN_API_KEY)
-```
-
-## Project Structure
-
-```
-src/
-├── index.js              # Thin CLI entry point (imports cli.js)
-├── cli.js                # CLI logic: parsing, routing, formatting, schema
-├── api.js                # NansenAPI class, all HTTP calls, validation
-└── __tests__/
-    ├── unit.test.js      # Core logic tests (validation, parsing, formatting)
-    ├── api.test.js       # API method tests with mocked fetch
-    ├── cli.test.js       # CLI integration tests (subprocess)
-    ├── cli.internal.test.js  # CLI unit tests (direct imports for coverage)
-    └── coverage.test.js  # Endpoint coverage verification
-```
-
-**Three files, clear separation:**
-- `index.js` = Entry point (thin wrapper)
-- `cli.js` = CLI layer (parsing, routing, output formatting, schema)
-- `api.js` = API layer (HTTP, validation, config)
-
-## Code Conventions
-
-- **ES modules** (`import`/`export`, not `require`)
-- **Async/await** for all API calls
-- **All output is JSON** (for AI agent consumption)
-- **No external dependencies** (just Node.js built-ins + vitest for tests)
-
-## Adding a New Endpoint
-
-1. **Add API method in `src/api.js`:**
-```javascript
-async newEndpoint(params = {}) {
-  const { chain = 'solana', filters = {}, orderBy, pagination } = params;
-  return this.request('/api/v1/endpoint-path', {
-    chain,
-    filters,
-    order_by: orderBy,
-    pagination
-  });
-}
-```
-
-2. **Add CLI handler in `src/index.js`:**
-```javascript
-// In the appropriate command handler (smart-money, profiler, token, portfolio)
-'new-subcommand': () => api.newEndpoint({ chains, filters, orderBy, pagination }),
-```
-
-3. **Add tests:**
-   - `api.test.js` — Mock the fetch, verify request body
-   - `cli.test.js` — Test CLI invocation
-   - `coverage.test.js` — Add to `DOCUMENTED_ENDPOINTS`
-
-4. **Update `README.md`** with docs
-
-## Testing
-
-```bash
-npm test                    # All tests, mocked
-npm run test:watch          # Watch mode
-npm run test:coverage       # With coverage report
-NANSEN_API_KEY=xxx npm run test:live  # Live API tests
-```
-
-**Test philosophy:**
-- Unit tests don't need API key (use mocked fetch)
-- Live tests are opt-in via `NANSEN_LIVE_TEST=1`
-- Coverage test ensures all documented endpoints have implementations
-
-## Common Patterns
-
-### Address Validation
-```javascript
-// Validates EVM (0x...) or Solana (Base58) addresses
-const validation = validateAddress(address, chain);
-if (!validation.valid) throw new Error(validation.error);
-```
-
-### Date Ranges
-```javascript
-// Most endpoints accept days param, converted to date range
-const to = new Date().toISOString().split('T')[0];
-const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
-```
-
-### Retry Behavior
-- **Enabled by default** with 3 attempts
-- Retries on: 429, 500, 502, 503, 504, network errors
-- Exponential backoff with jitter (1s base, 30s max)
-- Respects `retry-after` headers
-- Disable with `--no-retry` or `options.retry = false`
-- Success responses include `_meta.retriedAttempts` if retried
-
-### Response Format
-```javascript
-// Success
-{ "success": true, "data": { ... } }
-
-// Error
-{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "details": { ... } }
-```
-
-### Schema Discovery
-```bash
-nansen schema                    # Full schema (commands, options, types)
-nansen schema smart-money        # Schema for specific command
-```
-Returns JSON with all commands, subcommands, option types/defaults, return fields, supported chains, and smart money labels. No API key required.
-
-### Field Filtering
-```bash
-nansen research smart-money netflow --fields token_symbol,net_flow_usd,chain
-```
-Reduces response size by including only specified fields. Works with nested data structures.
-
-### Error Codes
-Structured error codes for programmatic handling:
-
-| Code | Description |
-|------|-------------|
-| `UNAUTHORIZED` | Invalid or missing API key (401) |
-| `FORBIDDEN` | Valid key but insufficient permissions (403) |
-| `CREDITS_EXHAUSTED` | Insufficient API credits (403) — do not retry |
-| `RATE_LIMITED` | Too many requests (429) |
-| `INVALID_ADDRESS` | Address format validation failed |
-| `INVALID_TOKEN` | Token address validation failed |
-| `INVALID_CHAIN` | Unsupported or invalid chain |
-| `INVALID_PARAMS` | Generic parameter validation error |
-| `MISSING_PARAM` | Required parameter not provided |
-| `UNSUPPORTED_FILTER` | Filter not supported for this token/chain (400) |
-| `NOT_FOUND` | Resource not found (404) |
-| `TOKEN_NOT_FOUND` | Token doesn't exist |
-| `ADDRESS_NOT_FOUND` | Address has no data |
-| `SERVER_ERROR` | Nansen API internal error (500+) |
-| `SERVICE_UNAVAILABLE` | API temporarily down (503) |
-| `NETWORK_ERROR` | Connection failed |
-| `TIMEOUT` | Request timed out |
-| `UNKNOWN` | Unclassified error |
-
-## API Reference
-
-### Chains
-`ethereum`, `solana`, `base`, `bnb`, `arbitrum`, `polygon`, `optimism`, `avalanche`, `linea`, `scroll`, `zksync`, `mantle`, `ronin`, `sei`, `plasma`, `sonic`, `unichain`, `monad`, `hyperevm`, `iotaevm`
-
-### Smart Money Labels
-`Fund`, `Smart Trader`, `30D Smart Trader`, `90D Smart Trader`, `180D Smart Trader`, `Smart HL Perps Trader`
-
-### Endpoints by Category
-
-**Smart Money (6):** netflow, dex-trades, perp-trades, holdings, dcas, historical-holdings
-
-**Profiler (11):** balance, labels, transactions, pnl, search, historical-balances, related-wallets, counterparties, pnl-summary, perp-positions, perp-trades
-
-**Token God Mode (12):** screener, holders, flows, dex-trades, pnl, who-bought-sold, flow-intelligence, transfers, jup-dca, perp-trades, perp-positions, perp-pnl-leaderboard
-
-**Portfolio (1):** defi-holdings
-
-## Gotchas
-
-- **Perp endpoints** work with Hyperliquid (use `--symbol BTC` not `--token`)
-- **JUP DCA** is Solana-only
-- **Beta endpoints** (`/api/beta/...`) may have different pagination
-- **EVM vs Solana addresses** — validation auto-detects based on chain param
-
-## Publishing (npm)
-
-**DO NOT manually run `npm version` or `npm publish`. CI handles everything.**
-
-1. **Push to main** — CI runs tests
-2. **CI creates a "Version Packages" PR** — bumps version + updates CHANGELOG
-3. **Merge the Version PR** — CI auto-publishes to npm
-
-If you mess up: accidentally bumped version manually? `git revert` and add a changeset instead. CI publish failed? Check GitHub Actions logs, likely needs `NPM_TOKEN` secret refresh.
-
-## Changesets
-
-Every PR that changes user-facing behavior **must** include a changeset file. `npm test` will warn if one is missing. The changeset description ends up in CHANGELOG.md (auto-generated by CI), so write it as a user-facing changelog entry.
-
-**Needs a changeset:** new features, bug fixes, breaking changes, changed CLI output, new/modified commands.
-
-**Does NOT need a changeset:** docs-only, test-only, refactors with no behavior change, CI/tooling.
-
-Add a file to `.changeset/` with a descriptive kebab-case name:
-
-```markdown
----
-"nansen-cli": minor
----
-
-Short description of the change (appears in CHANGELOG)
-```
-
-Use `patch` for bug fixes, `minor` for new features, `major` for breaking changes.
-
-## PR Checklist
-
-- [ ] Tests pass (`npm test`)
-- [ ] New endpoints have tests in all 3 test files
-- [ ] README.md updated if adding user-facing features
-- [ ] Changeset added for user-facing changes (see above)
-- [ ] No new dependencies (keep it lightweight)

package/SKILL.md

@@ -1,136 +0,0 @@
----
-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.
-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`.
----
-
-# Nansen CLI
-
-Command-line interface for the [Nansen API](https://docs.nansen.ai) - onchain analytics for crypto investors and AI agents.
-
-## CLI vs Direct API
-
-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.
-
-## Setup
-
-```bash
-# Install globally
-npm install -g nansen-cli
-
-# Authenticate — pick the method that works for your context:
-
-# 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
-
-# Option B: Environment variable (good for CI/scripts)
-export NANSEN_API_KEY=your-api-key
-
-# Option C: Interactive login (burns 1 credit to validate)
-nansen login
-```
-
-Get your API key at [app.nansen.ai/api](https://app.nansen.ai/api).
-
-### Verify Installation
-
-```bash
-# Free check (no API key needed):
-nansen schema | head -1
-
-# Full check (uses 1 credit):
-nansen token screener --chain solana --limit 1
-```
-
-## 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
-```
-
-### Wallet Profiler
-Analyze any wallet:
-```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"
-```
-
-### Token God Mode
-Deep token analytics:
-```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
-```
-
-### Portfolio
-DeFi holdings analysis:
-```bash
-nansen portfolio defi --wallet 0x123...
-```
-
-## Output Formats
-
-- **Default**: JSON (for AI agents)
-- `--pretty`: Formatted JSON
-- `--table`: Human-readable table
-- `--stream`: NDJSON (one record per line)
-- `--fields`: Filter specific fields
-
-## Key Options
-
-| 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 |
-
-## Supported Chains
-
-ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, mantle, ronin, sei, plasma, sonic, monad, hyperevm, iotaevm
-
-## Smart Money Labels
-
-Fund, Smart Trader, 30D Smart Trader, 90D Smart Trader, 180D Smart Trader, Smart HL Perps Trader
-
-## Schema Introspection
-
-Get the full API schema for programmatic use:
-```bash
-nansen schema --pretty
-nansen schema smart-money --pretty
-```
-
-## Troubleshooting
-
-See [AGENTS.md — Troubleshooting](AGENTS.md#troubleshooting) for the full troubleshooting guide, including error codes, known endpoint quirks, and pagination gotchas.
-
-## Examples
-
-```bash
-# Find trending Solana tokens with Smart Money activity
-nansen token screener --chain solana --timeframe 24h --smart-money --pretty
-
-# Check who's accumulating a specific token
-nansen token holders --token So11111111111111111111111111111111111111112 --chain solana --smart-money --limit 20 --pretty
-
-# Profile a whale wallet
-nansen profiler balance --address Gu29tjXrVr9v5n42sX1DNrMiF3BwbrTm379szgB9qXjc --chain solana --pretty
-
-# Track Smart Money flows into memecoins
-nansen smart-money netflow --chain solana --labels "Smart Trader" --pretty
-```

package/TODO.md

@@ -1,42 +0,0 @@
-# TODO
-
-> **Built by agents, for agents.** We prioritize improvements that create the best possible AI agent experience.
-
-## P0 - Trading Agent Support
-
-### Wallet Management
-- [ ] `nansen wallet create` — generate a local wallet (per chain), store key securely on disk
-- [ ] `nansen wallet address` — print the wallet address for funding
-- [ ] `nansen wallet balance` — check wallet balance
-
-### Trading Execution
-- [x] `nansen quote` — get a quote for a DEX swap (chain, tokens, amount)
-- [x] `nansen execute` — sign and submit a trade via Nansen API (takes quote-id)
-- [ ] ⚠️ EVM transaction signing — requires thorough security review before production use
-
-> These commands are required for `nansen-trading-agent` — the autonomous trading sub-agent.
-> Wallet commands should keep the agent self-contained with zero external dependencies.
-
----
-
-## P2 - Nice to Have
-
-### Test Coverage Gaps
-- [ ] Test config priority chain (ENV > ~/.nansen > local) — needs `loadConfig()` exported
-- [ ] Add snapshot tests for `--help` output
-- [ ] Document magic test addresses (e.g. Binance hot wallet)
-- [ ] Test Bitcoin address validation
-- [ ] Test stdin pipe mode for API key input
-
-### Shell Completions
-- [ ] Bash completions
-- [ ] Zsh completions
-- [ ] Fish completions
-
-### Distribution
-- [ ] Homebrew formula (`brew install nansen-cli`)
-- [ ] Docker image
-
----
-
-*Last updated: 2026-02-06*

package/scripts/check-changeset.js

@@ -1,28 +0,0 @@
-#!/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.
-}

package/vitest.e2e.config.js

@@ -1,10 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-    include: ['src/**/*.e2e.test.js'],
-    testTimeout: 120000,
-  },
-});