nansen-cli 1.6.0 → 1.8.0

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.8.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.
+}

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;
@@ -386,6 +391,17 @@ function parseRetryAfter(headerValue) {
   return null;
 }
 
+/**
+ * Build a date range from today back N days
+ * @param {number} days - Number of days back from today
+ * @returns {{from: string, to: string}} Date range with YYYY-MM-DD strings
+ */
+export function buildDateRange(days) {
+  const to = new Date().toISOString().split('T')[0];
+  const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+  return { from, to };
+}
+
 export class NansenAPI {
   constructor(apiKey = config.apiKey, baseUrl = config.baseUrl, options = {}) {
     this.apiKey = apiKey || null;
@@ -489,7 +505,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 {
@@ -585,11 +635,9 @@ export class NansenAPI {
 
   async smartMoneyHistoricalHoldings(params = {}) {
     const { chains = ['solana'], filters = {}, orderBy, pagination, days = 30 } = params;
-    const to = new Date().toISOString().split('T')[0];
-    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
     return this.request('/api/v1/smart-money/historical-holdings', {
       chains,
-      date_range: { from, to },
+      date_range: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
@@ -632,11 +680,7 @@ export class NansenAPI {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    const dateRange = date || (() => {
-      const to = new Date().toISOString().split('T')[0];
-      const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
-      return { from, to };
-    })();
+    const dateRange = date || buildDateRange(days);
     return this.request('/api/v1/profiler/address/transactions', {
       address,
       chain,
@@ -653,13 +697,7 @@ export class NansenAPI {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    // Build date range
-    let dateRange = date;
-    if (!dateRange) {
-      const to = new Date().toISOString().split('T')[0];
-      const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
-      dateRange = { from, to };
-    }
+    const dateRange = date || buildDateRange(days);
     return this.request('/api/v1/profiler/address/pnl', {
       address,
       chain,
@@ -695,12 +733,10 @@ export class NansenAPI {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    const to = new Date().toISOString().split('T')[0];
-    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
     return this.request('/api/v1/profiler/address/historical-balances', {
       address,
       chain,
-      date: { from, to },
+      date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
@@ -727,12 +763,10 @@ export class NansenAPI {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    const to = new Date().toISOString().split('T')[0];
-    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
     return this.request('/api/v1/profiler/address/counterparties', {
       address,
       chain,
-      date: { from, to },
+      date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
@@ -745,12 +779,10 @@ export class NansenAPI {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    const to = new Date().toISOString().split('T')[0];
-    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
     return this.request('/api/v1/profiler/address/pnl-summary', {
       address,
       chain,
-      date: { from, to },
+      date: buildDateRange(days),
       order_by: orderBy,
       pagination
     });
@@ -769,11 +801,9 @@ export class NansenAPI {
 
   async addressPerpTrades(params = {}) {
     const { address, filters = {}, orderBy, pagination, days = 30 } = params;
-    const to = new Date().toISOString().split('T')[0];
-    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
     return this.request('/api/v1/profiler/perp-trades', {
       address,
-      date: { from, to },
+      date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
@@ -815,11 +845,7 @@ export class NansenAPI {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    const dateRange = date || (() => {
-      const to = new Date().toISOString().split('T')[0];
-      const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
-      return { from, to };
-    })();
+    const dateRange = date || buildDateRange(days);
     return this.request('/api/v1/tgm/flows', {
       token_address: tokenAddress,
       chain,
@@ -836,9 +862,6 @@ export class NansenAPI {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    const to = new Date().toISOString().split('T')[0];
-    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
-    
     // Apply smart money filter via filters object
     if (onlySmartMoney) {
       filters.include_smart_money_labels = filters.include_smart_money_labels || 
@@ -848,7 +871,7 @@ export class NansenAPI {
     return this.request('/api/v1/tgm/dex-trades', {
       token_address: tokenAddress,
       chain,
-      date: { from, to },
+      date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
@@ -861,12 +884,10 @@ export class NansenAPI {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    const to = new Date().toISOString().split('T')[0];
-    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
     return this.request('/api/v1/tgm/pnl-leaderboard', {
       token_address: tokenAddress,
       chain,
-      date: { from, to },
+      date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
@@ -879,11 +900,7 @@ export class NansenAPI {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    const dateRange = date || (() => {
-      const to = new Date().toISOString().split('T')[0];
-      const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
-      return { from, to };
-    })();
+    const dateRange = date || buildDateRange(days);
     return this.request('/api/v1/tgm/who-bought-sold', {
       token_address: tokenAddress,
       chain,
@@ -912,12 +929,10 @@ export class NansenAPI {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    const to = new Date().toISOString().split('T')[0];
-    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
     return this.request('/api/v1/tgm/transfers', {
       token_address: tokenAddress,
       chain,
-      date: { from, to },
+      date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
@@ -941,11 +956,9 @@ export class NansenAPI {
 
   async tokenPerpTrades(params = {}) {
     const { tokenSymbol, filters = {}, orderBy, pagination, days = 30 } = params;
-    const to = new Date().toISOString().split('T')[0];
-    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
     return this.request('/api/v1/tgm/perp-trades', {
       token_symbol: tokenSymbol,
-      date: { from, to },
+      date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
@@ -964,11 +977,9 @@ export class NansenAPI {
 
   async tokenPerpPnlLeaderboard(params = {}) {
     const { tokenSymbol, filters = {}, orderBy, pagination, days = 30 } = params;
-    const to = new Date().toISOString().split('T')[0];
-    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
     return this.request('/api/v1/tgm/perp-pnl-leaderboard', {
       token_symbol: tokenSymbol,
-      date: { from, to },
+      date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
@@ -987,6 +998,20 @@ export class NansenAPI {
     });
   }
 
+  async tokenOhlcv(params = {}) {
+    const { tokenAddress, chain = 'solana', timeframe, pagination } = params;
+    if (tokenAddress) {
+      const validation = validateTokenAddress(tokenAddress, chain);
+      if (!validation.valid) throw new NansenError(validation.error, validation.code);
+    }
+    return this.request('/api/v1/tgm/token-ohlcv', {
+      token_address: tokenAddress,
+      chain,
+      timeframe,
+      pagination
+    });
+  }
+
   async tokenInformation(params = {}) {
     const { tokenAddress, chain = 'solana', timeframe = '1d' } = params;
     if (tokenAddress) {
@@ -1004,10 +1029,8 @@ export class NansenAPI {
 
   async perpScreener(params = {}) {
     const { filters = {}, orderBy, pagination, days = 30 } = params;
-    const to = new Date().toISOString().split('T')[0];
-    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
     return this.request('/api/v1/perp-screener', {
-      date: { from, to },
+      date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
@@ -1016,10 +1039,8 @@ export class NansenAPI {
 
   async perpLeaderboard(params = {}) {
     const { filters = {}, orderBy, pagination, days = 30 } = params;
-    const to = new Date().toISOString().split('T')[0];
-    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
     return this.request('/api/v1/perp-leaderboard', {
-      date: { from, to },
+      date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination