nansen-cli 1.6.0 → 1.8.0

package/AGENTS.md

@@ -0,0 +1,176 @@
+# AGENTS.md — Contributor Guide
+
+Guidance for AI coding agents (Claude Code, Codex, Copilot, etc.) working on this repository. If you're an agent **using** the CLI, see [README.md](README.md).
+
+## Architecture
+
+```
+src/
+├── index.js          # Entry point (shebang, calls runCLI)
+├── cli.js            # Command router, arg parsing, schema, help text
+├── api.js            # NansenAPI client (REST, retry, cache, x402 auto-pay)
+├── wallet.js         # Wallet CRUD (create/list/show/export/delete/send)
+├── trading.js        # Quote + execute swaps (OKX router via API)
+├── transfer.js       # Token/native transfers (EVM + Solana)
+├── x402.js           # x402 payment orchestration (picks network, signs)
+├── x402-evm.js       # EVM payment signing (EIP-3009 transferWithAuthorization)
+├── x402-svm.js       # Solana payment signing (SPL transfer)
+├── crypto.js         # Key encryption/decryption (AES-256-GCM or plaintext)
+└── update-check.js   # Version upgrade notice
+```
+
+### Command routing
+
+`src/index.js` → `runCLI()` in `src/cli.js`
+
+Commands are built by three functions, merged in `runCLI()`:
+- `buildCommands()` in cli.js — analytics commands (smart-money, profiler, token, etc.)
+- `buildWalletCommands()` in wallet.js — wallet subcommands
+- `buildTradingCommands()` in trading.js — quote/execute
+
+Commands listed in `NO_AUTH_COMMANDS` skip API initialization. Everything else instantiates `NansenAPI` with retry, cache, and x402 config.
+
+### Data flow: trade
+
+```
+CLI args → api.js GET /defi/quote → quote response
+         → wallet.js decrypt key → trading.js sign tx → api.js POST /defi/execute → broadcast
+```
+
+### Data flow: x402 auto-pay
+
+```
+api.js (any call) → 402 response with payment requirements
+→ x402.js rankRequirements() → picks cheapest network (EVM first)
+→ x402-evm.js or x402-svm.js → sign USDC payment
+→ api.js retries original request with Payment-Signature header
+```
+
+If EVM payment fails (insufficient funds), the async generator yields a Solana signature as fallback.
+
+### Output convention
+
+Core functions return data objects. The CLI layer formats via `formatOutput()`. Never `console.log` in core functions — use the `log` dependency injection for CLI output.
+
+## Development
+
+```bash
+npm install           # Install dependencies
+npm test              # Run tests (vitest)
+npm run test:watch    # Watch mode
+npm run test:coverage # With coverage
+```
+
+### Running locally
+
+```bash
+node src/index.js <command> [options]
+
+# Examples
+node src/index.js wallet create my-wallet
+node src/index.js smart-money --chain solana --limit 5
+```
+
+## Testing
+
+- **Framework:** Vitest
+- **Test files:** `src/__tests__/*.test.js`
+- **Current:** 577 tests across 13 test files
+- **All new code must have tests**
+- **Mock all RPC/API calls** — never hit real networks in tests
+
+### Test structure
+
+```js
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+global.fetch = vi.fn();
+
+describe('featureName', () => {
+  beforeEach(() => {
+    fetch.mockReset();
+  });
+
+  it('should do the thing', async () => {
+    fetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ jsonrpc: '2.0', result: '0x...', id: 1 })
+    });
+    // test logic
+  });
+});
+```
+
+### Required RPC mocks by code path
+
+**EVM transfers:** `eth_getBalance`, `eth_gasPrice`, `eth_maxPriorityFeePerGas`, `eth_getTransactionCount`, `eth_estimateGas`, `eth_getCode`, `eth_sendRawTransaction`, `eth_getTransactionReceipt`
+
+**Solana transfers:** `getBalance`, `getLatestBlockhash`, `sendTransaction`, `getSignatureStatuses`
+
+**SPL token transfers** (additionally): `getTokenAccountsByOwner`, `getAccountInfo`
+
+**Wallet operations:** No RPC mocks needed (file I/O only). Mock `fs` if testing file paths.
+
+**API calls:** Mock `fetch` to return `{ ok: true, json: () => ({...}) }` or `{ ok: false, status: 402, headers: new Headers({...}) }` for x402 paths.
+
+## Style Guide
+
+- **ESM only** (`import`/`export`). No TypeScript, no transpilation.
+- **No interactive prompts in core functions.** Use env vars: `NANSEN_WALLET_PASSWORD`, `NANSEN_API_KEY`.
+- **Error handling:** `throw new Error('descriptive message')` in core. CLI catches and formats.
+- **Actionable error messages** — tell the user what to do:
+  - ❌ `"Authentication failed"`
+  - ✅ `"Not logged in. Run: nansen login"`
+- **BigInt for token amounts.** Never use floating point. Parse to BigInt with decimals.
+- **Chain branching:** Use `chain === 'solana'` checks, not inheritance/polymorphism.
+- **Minimal dependencies.** Prefer Node.js built-in APIs (crypto, fs, path, http).
+
+## PR Checklist
+
+- [ ] `npm test` passes (all tests)
+- [ ] New code paths have test coverage
+- [ ] No hardcoded secrets, API keys, or private keys
+- [ ] No `console.log` in core functions (use `log` dep injection)
+- [ ] Error messages are actionable (tell user what to do)
+- [ ] CLI help text updated if adding/changing commands
+- [ ] RPC mocks cover all methods in the code path
+- [ ] Wallet flows work both with and without `NANSEN_WALLET_PASSWORD`
+- [ ] Changeset added if changing user-facing behavior (add a `.changeset/<name>.md` file — `npm test` will warn if missing)
+
+## Chains & Networks
+
+**EVM:** Ethereum (chain ID 1), Base (8453). `CHAIN_IDS` in transfer.js only maps these two — other EVM chains will fail for transfers.
+
+**Solana:** mainnet-beta. Supports native SOL, standard SPL tokens, and Token-2022 (Token Extensions).
+
+**RPC endpoints:** Hardcoded in `CHAIN_RPCS` (transfer.js). Nansen API handles RPC for trading.
+
+## Key Constants
+
+| Constant | Value |
+|----------|-------|
+| USDC (Base) | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+| USDC (Solana) | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
+| x402 payment | $0.05 USDC per API call |
+| Gas buffer | API provides `quote.gas` with 1.5x multiplier — use directly |
+
+## Endpoint Quirks
+
+These are internal details agents should know when writing or debugging tests:
+
+- **`token holders --smart-money`** — Returns `UNSUPPORTED_FILTER` for tokens without smart money tracking. Not all tokens have this data.
+- **`token flow-intelligence`** — May return all-zero flows for illiquid tokens. Normal, not an error.
+- **`token screener --search`** — Client-side filtering. The CLI fetches up to 500 results, then filters locally.
+- **`--fields`** — Applies to the entire response tree, including the `success`/`data` wrapper.
+- **Profiler beta endpoints** use `recordsPerPage` instead of `per_page`. The CLI handles this automatically.
+- **`profiler perp-positions`** — No pagination support; the API ignores the pagination parameter.
+
+## Known Gotchas
+
+1. **EIP-7702 delegated accounts** on Base have contract code. Always use `eth_estimateGas`, never hardcode 21000 gas.
+2. **Solana SPL account ordering:** Writable accounts (destATA) must precede readonly (mint) in the transaction message.
+3. **`getSignatureStatuses`** over `confirmTransaction` — the latter is deprecated and unreliable on public RPCs.
+4. **`--max` native SOL:** Reserve 5000 lamports for fee. On EVM L2s, reserve 3x estimated gas for L1 data posting fees.
+5. **Token-2022:** Use `TOKEN_2022_PROGRAM_ID` and `TransferCheckedInstruction` (not plain `Transfer`).
+6. **CreateATA path:** When recipient doesn't have a token account, the sender creates it. This path in transfer.js has limited test coverage — add tests if modifying.
+7. **`CHAIN_IDS` is incomplete:** Only ethereum and base are mapped. Adding new EVM chain support requires updating this map.

package/CLAUDE.md

@@ -125,7 +125,7 @@ Returns JSON with all commands, subcommands, option types/defaults, return field
 
 ### Field Filtering
 ```bash
-nansen smart-money netflow --fields token_symbol,net_flow_usd,chain
+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.
 
@@ -180,41 +180,38 @@ Structured error codes for programmatic handling:
 
 ## Publishing (npm)
 
-**⚠️ DO NOT manually run `npm version` or `npm publish`. CI handles everything.**
+**DO NOT manually run `npm version` or `npm publish`. CI handles everything.**
 
-### How it works:
+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
 
-1. **Add a changeset** for user-facing changes:
-   ```bash
-   npx changeset
-   # Or manually create .changeset/<name>.md
-   ```
+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.
 
-2. **Push to main** — CI runs tests
+## Changesets
 
-3. **CI creates a "Version Packages" PR** — This bumps version + updates CHANGELOG
+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.
 
-4. **Merge the Version PR** — CI auto-publishes to npm
+**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:
 
-### Changeset format:
 ```markdown
 ---
 "nansen-cli": minor
 ---
 
-Description of changes (appears in CHANGELOG)
+Short description of the change (appears in CHANGELOG)
 ```
 
-Choose: `patch` (bug fixes), `minor` (new features), `major` (breaking changes)
-
-### 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
+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
-- [ ] CHANGELOG.md updated for releases
+- [ ] Changeset added for user-facing changes (see above)
 - [ ] No new dependencies (keep it lightweight)

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.
 
@@ -27,39 +26,83 @@ npm link
 
 ## Configuration
 
-**Option 1: Interactive login (recommended)**
+### 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**
+**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.
 
@@ -72,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:
+
+```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
+```
 
-Detailed information about any blockchain address.
+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 |
 |------------|-------------|
@@ -98,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 |
 |------------|-------------|
@@ -113,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
 
@@ -168,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 |
@@ -179,91 +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
 
-**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
+### Reduce Token Burn with `--fields`
 
-```json
-// Success response
-{
-  "success": true,
-  "data": {
-    "results": [...],
-    "pagination": {...}
-  }
-}
-
-// Error response
-{
-  "success": false,
-  "error": "API error message",
-  "code": "UNAUTHORIZED",
-  "status": 401,
-  "details": {...}
-}
+```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
+
+```bash
+# NDJSON mode — process line by line, don't buffer giant arrays
+nansen research token dex-trades --chain solana --limit 100 --stream
 ```
 
-## Examples
+### 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:
 
-# Run with coverage
-npm run test:coverage
+| 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 against live API
-NANSEN_API_KEY=your-key npm run test:live
+`--table` and `--stream` handle this automatically. For raw JSON parsing:
+
+```bash
+nansen research smart-money netflow --chain solana | jq 'keys, .data | keys'
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
+### 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. |
+| `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