nansen-cli 1.5.1 → 1.7.0

package/AGENTS.md

@@ -0,0 +1,222 @@
+# AGENTS.md — Agent Quick Start
+
+> **This file is for AI agents (OpenClaw, Claude Code, Cursor, etc.) that need to query Nansen data on behalf of their human.** If you're a human, see [README.md](README.md).
+
+## CLI vs REST API
+
+**Prefer the [REST API](https://docs.nansen.ai) for most agent use cases** — no install step, no dependency issues.
+
+```bash
+# Direct API call — no CLI needed
+curl -s -X POST https://api.nansen.ai/api/v1/token-screener \
+  -H "apiKey: YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"chain":"solana","pagination":{"page":1,"per_page":5}}' | jq .
+```
+
+Use this CLI guide if the CLI is already installed or your human specifically wants CLI usage. The CLI adds `--pretty`, `--table`, `--fields`, `--stream`, built-in retries, and schema introspection.
+
+## Install & Auth in One Shot
+
+```bash
+# Install
+npm install -g nansen-cli
+
+# Auth — pick ONE method:
+# Method 1: Interactive (human needs to paste key)
+nansen login
+
+# Method 2: Environment variable (no interaction needed)
+export NANSEN_API_KEY=<key>
+
+# Method 3: Config file (write directly — no validation call burned)
+mkdir -p ~/.nansen && echo '{"apiKey":"<key>","baseUrl":"https://api.nansen.ai"}' > ~/.nansen/config.json && chmod 600 ~/.nansen/config.json
+```
+
+**Get an API key:** [app.nansen.ai/api](https://app.nansen.ai/api)
+
+### Auth Priority
+
+1. `NANSEN_API_KEY` env var (highest)
+2. `~/.nansen/config.json` file
+3. Prompt (interactive only)
+
+### Common Auth Pitfall
+
+`nansen login` validates your key by making a real API call (burns 1 credit). If you already know the key is valid, writing `~/.nansen/config.json` directly is cheaper.
+
+## Verify It Works
+
+```bash
+# This is cheap and fast:
+nansen schema | head -1
+# Expected: {"version":"1.x.x","commands":{...}}
+
+# This burns a credit but proves API access:
+nansen token screener --chain solana --limit 1
+```
+
+## Agent-Optimized Patterns
+
+### 1. Always Use `--fields` to Reduce Token Burn
+
+```bash
+# ❌ Returns everything (huge JSON, wastes agent context)
+nansen smart-money netflow --chain solana
+
+# ✅ Only what you need
+nansen smart-money netflow --chain solana --fields token_symbol,net_flow_usd,chain --limit 10
+```
+
+### 2. Use Schema for Self-Discovery
+
+```bash
+# Don't guess commands — introspect:
+nansen schema --pretty                    # All commands
+nansen schema smart-money --pretty        # One command's options & return fields
+```
+
+### 3. Parse Errors Programmatically
+
+Every response has `success: true/false`. Errors include `code` for routing:
+
+| Code | What To Do |
+|------|------------|
+| `CREDITS_EXHAUSTED` | **Stop all calls.** Tell the human. |
+| `RATE_LIMITED` | Wait. Auto-retry handles this. |
+| `UNSUPPORTED_FILTER` | Remove the filter, retry without it. |
+| `UNAUTHORIZED` | Key is wrong. Re-auth. |
+| `INVALID_ADDRESS` | Check address format for the chain. |
+
+### 4. Budget Credits
+
+- Most calls cost 1 credit
+- `profiler labels` + `profiler balance` are expensive — batch 3-4 at a time
+- `schema`, `help`, `cache` are free (no API key needed)
+- If you get `CREDITS_EXHAUSTED`, **stop immediately** — don't retry
+
+### 5. Use `--stream` for Large Results
+
+```bash
+# NDJSON mode — process line by line, don't buffer giant arrays
+nansen token dex-trades --chain solana --limit 100 --stream
+```
+
+## Pagination
+
+The CLI exposes `--limit N` which maps to `{page: 1, per_page: N}` in the API request. **There is no `--page` flag** — the CLI always fetches page 1. To access later pages, use the REST API directly.
+
+```bash
+# CLI: page 1 only, up to N results
+nansen smart-money netflow --chain solana --limit 50
+
+# REST API: full pagination control
+curl -s -X POST https://api.nansen.ai/api/v1/smart-money/netflow \
+  -H "apiKey: $NANSEN_API_KEY" -H "Content-Type: application/json" \
+  -d '{"chains":["solana"],"pagination":{"page":2,"per_page":50}}'
+```
+
+**Pagination key inconsistency:** Profiler endpoints (which use the beta API) take `recordsPerPage` instead of `per_page`. The CLI sends the right key automatically based on the command, but if you're calling the REST API directly, check which key each endpoint expects.
+
+**Detecting the last page:** The raw API response does not include a `total_pages` or `has_more` field in the CLI-visible output. Reliable heuristic: if the number of results returned is less than your `--limit`, you're on the last page.
+
+```bash
+# Request 50, get 23 back → last page
+nansen token holders --token <addr> --chain solana --limit 50
+# Check: .data.data.length (or .data.results.length) < 50 → done
+```
+
+**`profiler perp-positions` has no pagination** — the API ignores the pagination parameter for this endpoint.
+
+## Output Parsing Gotchas
+
+### Response envelope
+
+Every CLI response is wrapped in a standard envelope:
+
+```json
+{ "success": true, "data": <raw_api_response> }
+```
+
+Errors follow a different shape:
+
+```json
+{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "details": {...} }
+```
+
+### Raw API response shapes vary by endpoint
+
+The `data` field inside the envelope is the raw JSON from the Nansen API. Its internal structure differs across endpoints — there is no single canonical key for the results array:
+
+| 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 |
+
+When parsing, check for the array at each level. `--table` and `--stream` handle this automatically, but if you're parsing raw JSON with `jq`, probe the shape first:
+
+```bash
+nansen smart-money netflow --chain solana | jq 'keys, .data | keys'
+```
+
+### `--fields` applies to the entire response tree
+
+`--fields token_symbol,net_flow_usd` strips everything except those keys from the **entire** response, including the `success` and `data` wrapper fields. The result will be a bare object containing only the matched keys found anywhere in the tree.
+
+### Client-side vs server-side filtering
+
+`token screener --search <term>` is **client-side**: the CLI fetches up to 500 results from the server, then filters locally. Set `--limit` higher than your expected result count when using `--search`.
+
+### Fields absent for some chain/token combinations
+
+Some fields are only populated for specific chains or tokens:
+- `smart_money_holders` — absent for tokens without smart money tracking
+- Flow intelligence fields — may all be `0` for illiquid tokens (not an error)
+- Perp endpoints (`--symbol`) only work for Hyperliquid; `--token` is for on-chain tokens
+
+## Chains Quick Reference
+
+`ethereum` `solana` `base` `bnb` `arbitrum` `polygon` `optimism` `avalanche` `linea` `scroll` `mantle` `ronin` `sei` `plasma` `sonic` `monad` `hyperevm` `iotaevm`
+
+> Run `nansen schema` to get the current chain list (source of truth).
+
+## Troubleshooting
+
+### Quick fixes
+
+| Symptom | Fix |
+|---------|-----|
+| `command not found: nansen` | `npm install -g nansen-cli` or `npx nansen-cli` |
+| `UNAUTHORIZED` after login | Check `cat ~/.nansen/config.json` — key may not have saved. Write it directly. |
+| Login hangs or fails | Skip `nansen login`, write config directly (see Install & Auth above) |
+| Huge JSON response | Use `--fields` to select only needed columns |
+| Perp endpoints empty or erroring | Use `--symbol BTC` not `--token`. Perp endpoints are Hyperliquid-only. |
+| JUP DCA returns error | Solana-only endpoint |
+| `UNSUPPORTED_FILTER` on token holders | Not all tokens have smart money data. Remove `--smart-money` and retry. |
+| `CREDITS_EXHAUSTED` | Stop all calls. Check [app.nansen.ai](https://app.nansen.ai). No retry will help. |
+
+### Error codes
+
+| Code | What to do |
+|------|------------|
+| `CREDITS_EXHAUSTED` | **Stop all calls.** Tell the human. Check dashboard. |
+| `RATE_LIMITED` | Wait — auto-retry handles this by default. |
+| `UNSUPPORTED_FILTER` | Remove the filter, retry without it. |
+| `UNAUTHORIZED` | Key is wrong or missing. Re-auth. |
+| `INVALID_ADDRESS` | Check address format matches the chain (EVM: `0x...`, Solana: Base58). |
+
+### Known endpoint quirks
+
+- **`token holders --smart-money`** — Fails with `UNSUPPORTED_FILTER` for tokens without smart money tracking (e.g., WCT on Optimism). Not all tokens have this data. Do not retry.
+- **`token flow-intelligence`** — May return all-zero flows for tokens without significant smart money activity. Normal, not an error.
+- **`profiler labels` and `profiler balance`** consume credits. Budget ~20 calls per session. Batch calls in groups of 3–4.
+- **`profiler perp-positions`** — No pagination support; the API ignores the pagination parameter.
+
+## For OpenClaw / Skill Users
+
+If you installed this as an OpenClaw skill, the `SKILL.md` file has the skill interface. This `AGENTS.md` covers the CLI directly. Both work.

package/README.md

@@ -27,7 +27,20 @@ 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
@@ -123,6 +136,21 @@ Deep analytics for any token.
 |------------|-------------|
 | `defi` | DeFi holdings across protocols |
 
+### `search` - Search
+
+Search for tokens and entities across Nansen.
+
+```bash
+nansen search "uniswap" --pretty
+nansen search "uniswap" --type token --chain ethereum
+```
+
+| Option | Description |
+|--------|-------------|
+| `--type` | Filter by result type: `token`, `entity`, or `any` (default) |
+| `--chain` | Filter by chain |
+| `--limit` | Max results, 1-50 (default: 25) |
+
 ### `schema` - Schema Discovery
 
 Output JSON schema for agent introspection. No API key required.
@@ -177,6 +205,9 @@ nansen cache clear
 
 This CLI is built specifically for AI agents. Every design decision prioritizes agent usability.
 
+**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.
+
 **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
@@ -248,6 +279,8 @@ NANSEN_API_KEY=your-key npm run test:live
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
 
+**AI agents:** See [AGENTS.md](AGENTS.md) for the agent quick-start (install, auth, patterns, troubleshooting).
+
 **AI contributors:** See [CLAUDE.md](CLAUDE.md) for agent-specific guidance on contributing to this repo.
 
 ## API Coverage
@@ -258,7 +291,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
 | Profiler | 11 | 100% |
 | Token God Mode | 12 | 100% |
 | Portfolio | 1 | 100% |
-| **Total** | **30** | **100%** |
+| Search | 1 | 100% |
+| **Total** | **31** | **100%** |
 
 ## License
 

package/SKILL.md

@@ -12,21 +12,40 @@ compatibility: Requires Node.js 18+. Needs NANSEN_API_KEY environment variable o
 
 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 (interactive)
-nansen login
+# 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
 
-# Or set environment variable
+# 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
@@ -82,7 +101,7 @@ nansen portfolio defi --wallet 0x123...
 
 ## Supported Chains
 
-ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, zksync, mantle, ronin, sei, sonic, monad, hyperevm
+ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, mantle, ronin, sei, plasma, sonic, monad, hyperevm, iotaevm
 
 ## Smart Money Labels
 
@@ -96,24 +115,9 @@ nansen schema --pretty
 nansen schema smart-money --pretty
 ```
 
-## Known Endpoint Issues
-
-### Chain/Token-Specific Limitations
-- `token holders --smart-money` — Fails with `UNSUPPORTED_FILTER` for tokens without smart money tracking (e.g., WCT on Optimism). Not all tokens have smart money data. Do not retry.
-- `token flow-intelligence` — May return all-zero flows for tokens without significant smart money activity. This is normal, not an error.
-
-### Credit Management
-- `profiler labels` and `profiler balance` consume credits. Budget ~20 calls per session.
-- `Insufficient credits` (403, code `CREDITS_EXHAUSTED`) is a hard stop — no retry will help.
-- Check your Nansen dashboard for credit balance: [app.nansen.ai](https://app.nansen.ai).
-- Run balance checks in batches of 3-4 to avoid burning credits on rate-limit retries.
+## Troubleshooting
 
-### Error Codes to Watch
-| Code | Meaning | Action |
-|------|---------|--------|
-| `UNSUPPORTED_FILTER` | Filter not available for this token/chain | Remove the filter and retry, or skip this token |
-| `CREDITS_EXHAUSTED` | API credits depleted | Stop all API calls. Check dashboard. |
-| `RATE_LIMITED` | Too many requests (429) | Wait and retry (automatic with default retry) |
+See [AGENTS.md — Troubleshooting](AGENTS.md#troubleshooting) for the full troubleshooting guide, including error codes, known endpoint quirks, and pagination gotchas.
 
 ## Examples
 

package/TODO.md

@@ -2,6 +2,23 @@
 
 > **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",

package/src/api.js

@@ -9,6 +9,10 @@ import { fileURLToPath } from 'url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+const { version: packageVersion } = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+);
+
 // ============= Error Codes =============
 
 /**
@@ -296,36 +300,40 @@ export function validateTokenAddress(tokenAddress, chain = 'solana') {
 }
 
 function loadConfig() {
-  // Priority: 1. Environment variables, 2. ~/.nansen/config.json, 3. Local config.json
-  
-  // Check environment variables first (highest priority)
-  if (process.env.NANSEN_API_KEY) {
-    return {
-      apiKey: process.env.NANSEN_API_KEY,
-      baseUrl: process.env.NANSEN_BASE_URL || 'https://api.nansen.ai'
-    };
-  }
-  
-  // Check ~/.nansen/config.json (from `nansen login`)
+  // Base config from files, then env vars override individual fields
+  let config = null;
+
+  // ~/.nansen/config.json (from `nansen login`)
   if (fs.existsSync(CONFIG_FILE)) {
-    try {
-      return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
-    } catch (e) {
-      // Ignore parse errors, continue to next option
+    try { config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')); } catch (e) {}
+  }
+
+  // Local config.json (for development)
+  if (!config) {
+    const localConfig = path.join(__dirname, '..', 'config.json');
+    if (fs.existsSync(localConfig)) {
+      config = JSON.parse(fs.readFileSync(localConfig, 'utf8'));
     }
   }
-  
-  // Check local config.json (for development)
-  const localConfig = path.join(__dirname, '..', 'config.json');
-  if (fs.existsSync(localConfig)) {
-    return JSON.parse(fs.readFileSync(localConfig, 'utf8'));
+
+  if (!config) {
+    config = { apiKey: null, baseUrl: 'https://api.nansen.ai' };
   }
-  
-  // No config found
-  return {
-    apiKey: null,
-    baseUrl: 'https://api.nansen.ai'
-  };
+
+  // Ensure baseUrl default (config file from older versions may omit it)
+  if (!config.baseUrl) {
+    config.baseUrl = 'https://api.nansen.ai';
+  }
+
+  // Env vars override individual fields
+  if (process.env.NANSEN_API_KEY) {
+    config.apiKey = process.env.NANSEN_API_KEY;
+  }
+  if (process.env.NANSEN_BASE_URL) {
+    config.baseUrl = process.env.NANSEN_BASE_URL;
+  }
+
+  return config;
 }
 
 const config = loadConfig();
@@ -388,10 +396,11 @@ export class NansenAPI {
     this.apiKey = apiKey || null;
     this.baseUrl = baseUrl;
     this.retryOptions = { ...DEFAULT_RETRY_OPTIONS, ...options.retry };
-    this.cacheOptions = { 
+    this.cacheOptions = {
       enabled: options.cache?.enabled ?? false,
       ttl: options.cache?.ttl ?? DEFAULT_CACHE_TTL
     };
+    this.defaultHeaders = options.defaultHeaders || {};
   }
 
   static cleanBody(body) {
@@ -428,7 +437,10 @@ export class NansenAPI {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
+            'X-Client-Type': 'nansen-cli',
+            'X-Client-Version': packageVersion,
             ...(this.apiKey ? { 'apikey': this.apiKey } : {}),
+            ...this.defaultHeaders,
             ...options.headers
           },
           body: JSON.stringify(NansenAPI.cleanBody(body))
@@ -482,7 +494,41 @@ export class NansenAPI {
         } else if (code === ErrorCode.CREDITS_EXHAUSTED) {
           message = message.replace(/\.+$/, '') + '. No retry will help. Check your Nansen dashboard for credit balance.';
         } else if (code === ErrorCode.PAYMENT_REQUIRED) {
-          message = 'Payment required (x402). This endpoint requires on-chain payment.';
+          // Try x402 auto-payment with fallback across payment networks
+          if (!this.defaultHeaders['Payment-Signature']) {
+            try {
+              const { createPaymentSignatures } = await import('./x402.js');
+              for await (const { signature, network } of createPaymentSignatures(response, url)) {
+                const paidResponse = await fetch(url, {
+                  method: 'POST',
+                  headers: {
+                    'Content-Type': 'application/json',
+                    'X-Client-Type': 'nansen-cli',
+                    'X-Client-Version': packageVersion,
+                    'Payment-Signature': signature,
+                    ...this.defaultHeaders,
+                    ...options.headers,
+                  },
+                  body: JSON.stringify(NansenAPI.cleanBody(body)),
+                });
+                if (paidResponse.ok) {
+                  const chain = network.startsWith('solana:') ? 'Solana' : 'Base';
+                  console.error(`[x402] Paid via ${chain} USDC`);
+                  // Check remaining balance and warn if low
+                  try {
+                    const { checkX402Balance } = await import('./x402.js');
+                    const balance = await checkX402Balance(network);
+                    if (balance !== null && balance < 0.25) {
+                      console.error(`[x402] Warning: USDC balance low ($${balance.toFixed(2)}). Fund your wallet to avoid interruptions.`);
+                    }
+                  } catch { /* balance check is best-effort */ }
+                  return await paidResponse.json();
+                }
+                // This payment option was rejected, try next
+              }
+            } catch { /* x402 auto-pay unavailable, fall through */ }
+          }
+          message = 'Payment required. To access this endpoint:\n  • Set an API key: nansen login --api-key <key>  (get one at https://app.nansen.ai/api)\n  • Or pay per call: nansen wallet create, fund with USDC on Base or Solana (from $0.01/call, min $0.05 balance)\n  • Docs: https://docs.x402.org';
           const paymentHeader = response.headers.get('payment-required');
           if (paymentHeader) {
             try {
@@ -668,6 +714,20 @@ export class NansenAPI {
     });
   }
 
+  async generalSearch(params = {}) {
+    const { query, resultType = 'any', chain, limit = 25 } = params;
+    if (!query) {
+      throw new NansenError('Search query is required', ErrorCode.MISSING_PARAM);
+    }
+    const body = {
+      search_query: query,
+      result_type: resultType,
+      limit
+    };
+    if (chain) body.chain = chain;
+    return this.request('/api/v1/search/general', body);
+  }
+
   async addressHistoricalBalances(params = {}) {
     const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30 } = params;
     if (address) {
@@ -954,8 +1014,20 @@ export class NansenAPI {
     });
   }
 
+  async tokenIndicators(params = {}) {
+    const { tokenAddress, chain = 'ethereum' } = params;
+    if (tokenAddress) {
+      const validation = validateTokenAddress(tokenAddress, chain);
+      if (!validation.valid) throw new NansenError(validation.error, validation.code);
+    }
+    return this.request('/api/v1/tgm/indicators', {
+      token_address: tokenAddress,
+      chain
+    });
+  }
+
   async tokenInformation(params = {}) {
-    const { tokenAddress, chain = 'solana', timeframe = '24h' } = params;
+    const { tokenAddress, chain = 'solana', timeframe = '1d' } = params;
     if (tokenAddress) {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);