nansen-cli 1.6.0 → 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
@@ -192,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
@@ -263,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

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.6.0",
+  "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

@@ -320,6 +320,11 @@ function loadConfig() {
     config = { 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;
@@ -489,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). Sign the paymentRequirements below per https://docs.x402.org and pass the result with --x402-payment-signature <value>.';
+          // 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 {

package/src/cli.js

@@ -4,6 +4,8 @@
  */
 
 import { NansenAPI, NansenError, ErrorCode, saveConfig, deleteConfig, getConfigFile, clearCache, getCacheDir, validateAddress, sleep } from './api.js';
+import { buildWalletCommands } from './wallet.js';
+import { buildTradingCommands } from './trading.js';
 import fs from 'fs';
 import { getUpdateNotification, scheduleUpdateCheck } from './update-check.js';
 import { createRequire } from 'module';
@@ -839,6 +841,9 @@ COMMANDS:
   login          Save your API key (interactive)
   logout         Remove saved API key
   schema         Output JSON schema for all commands (for agent introspection)
+  wallet         Local wallet management (create, list, show, export, default, delete)
+  quote          Get a DEX swap quote (chain, tokens, amount)
+  execute        Sign and broadcast a quoted trade
   cache          Cache management (clear)
   smart-money    Smart Money analytics (netflow, dex-trades, perp-trades, holdings, dcas, historical-holdings)
   profiler       Wallet profiling (balance, labels, transactions, pnl, pnl-summary, search,
@@ -968,10 +973,16 @@ export function buildCommands(deps = {}) {
 
   return {
     'login': async (args, apiInstance, flags, options) => {
-      log('Nansen CLI Login\n');
-      log('Get your API key at: https://app.nansen.ai/api\n');
-      
-      const apiKey = await promptFn('Enter your API key: ', true);
+      // Support non-interactive: nansen login --api-key <key>
+      let apiKey = options['api-key'] || options.apiKey;
+
+      if (!apiKey) {
+        log('Nansen CLI Login\n');
+        log('Get your API key at: https://app.nansen.ai/api\n');
+        log('Tip: For non-interactive use: nansen login --api-key <key>\n');
+        
+        apiKey = await promptFn('Enter your API key: ', true);
+      }
       
       if (!apiKey || apiKey.trim().length === 0) {
         log('\n❌ No API key provided');
@@ -1346,7 +1357,7 @@ export function buildCommands(deps = {}) {
 }
 
 // Commands that don't require API authentication
-export const NO_AUTH_COMMANDS = ['login', 'logout', 'help', 'schema', 'cache'];
+export const NO_AUTH_COMMANDS = ['login', 'logout', 'help', 'schema', 'cache', 'wallet', 'quote', 'execute'];
 
 // Command aliases for convenience
 export const COMMAND_ALIASES = {
@@ -1489,7 +1500,7 @@ export async function runCLI(rawArgs, deps = {}) {
   scheduleUpdateCheck();
   const notify = () => { if (updateNotification) errorOutput(updateNotification); };
 
-  const commands = { ...buildCommands(deps), ...commandOverrides };
+  const commands = { ...buildCommands(deps), ...buildWalletCommands(deps), ...buildTradingCommands(deps), ...commandOverrides };
 
   if (flags.version || flags.v) {
     output(VERSION);
@@ -1522,10 +1533,12 @@ export async function runCLI(rawArgs, deps = {}) {
         return { type: 'command-help', command };
       }
     }
-    // Fallback to main help
-    output(BANNER + HELP);
-    notify();
-    return { type: 'help' };
+    // Commands with handlers (e.g. quote, execute) show their own usage
+    if (command === 'help' || !commands[command]) {
+      output(BANNER + HELP);
+      notify();
+      return { type: 'help' };
+    }
   }
 
   if (!commands[command]) {