nansen-cli 1.36.0 → 1.36.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.36.2
+
+### Patch Changes
+
+- [#479](https://github.com/nansen-ai/nansen-cli/pull/479) [`e2590ed`](https://github.com/nansen-ai/nansen-cli/commit/e2590ed5caf0461b43f6e726ec62d87f70d391fd) Thanks [@gulshngill](https://github.com/gulshngill)! - Surface richer API response metadata: the `X-Nansen-Credits-Cost` header now drives credit reporting (a concise `Credits: N (this call)` stderr line after each data command, falling back to the cached spec estimate when the header is absent), `requestId` is hoisted to the top level of the JSON error envelope (including `nansen agent` failures, which previously dropped it), and error codes now come from the API's stable `code` field when present — known codes map onto the existing error code enum, unknown ones pass through verbatim instead of being flattened. stdout JSON is unchanged; all new reporting goes to stderr.
+
+## 1.36.1
+
+### Patch Changes
+
+- [#476](https://github.com/nansen-ai/nansen-cli/pull/476) [`f480a49`](https://github.com/nansen-ai/nansen-cli/commit/f480a492a2ea142894a49f7a6e551d38e8aa4312) Thanks [@kome12](https://github.com/kome12)! - Add troubleshooting guidance for stale global installs.
+
 ## 1.36.0
 
 ### Minor Changes

package/README.md

@@ -209,7 +209,7 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
 
 ```json
 { "success": true,  "data": <api_response> }
-{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "details": { ... } }
+{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "requestId": "...", "details": { ... } }
 ```
 
 **Critical error codes:**
@@ -226,8 +226,8 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
 
 | Field | Meaning |
 |-------|---------|
-| `requestId` | Identifies this call end to end. Quote it in any support report. Opaque — do not parse it. |
-| `credits` | `used`, `remaining` |
+| `requestId` | Identifies this call end to end. Quote it in any support report. Opaque — do not parse it. Also hoisted to the top level of the error envelope. |
+| `credits` | `used`, `remaining`, `cost` (the authoritative charge for this call) |
 | `rateLimit` | `limit`, `remaining`, `resetSeconds` |
 
 Any field may be absent or `null`, meaning unknown — never assume zero. A low-balance warning goes to **stderr**, so stdout stays pure JSON.
@@ -237,6 +237,7 @@ Any field may be absent or `null`, meaning unknown — never assume zero. A low-
 | Symptom | Fix |
 |---------|-----|
 | `command not found` | `npm install -g nansen-cli` |
+| Global install reports an older version | `npm i -g nansen-cli@latest --registry=https://registry.npmjs.org/ --prefer-online`, then check `which -a nansen` for stale binaries |
 | `UNAUTHORIZED` after login | `cat ~/.nansen/config.json` or set `NANSEN_API_KEY` |
 | Empty perp _research_ results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |
 | `perp` _trading_ prints the usage banner | Trading needs `--coin BTC` (`--symbol` also works); see the Perpetuals section. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.36.0",
+  "version": "1.36.2",
   "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
   "main": "src/index.js",
   "type": "module",

package/src/api.js

@@ -116,12 +116,43 @@ export class NansenError extends Error {
 }
 
 /**
- * Map HTTP status codes to error codes
+ * Stable snake_case codes the server sends in error bodies, mapped to the
+ * ErrorCode values downstream consumers already key on.
+ */
+const SERVER_CODE_MAP = {
+  rate_limit_exceeded: ErrorCode.RATE_LIMITED,
+  insufficient_credits: ErrorCode.CREDITS_EXHAUSTED,
+  payment_required: ErrorCode.PAYMENT_REQUIRED,
+  unauthorized: ErrorCode.UNAUTHORIZED,
+  forbidden: ErrorCode.FORBIDDEN,
+  not_found: ErrorCode.NOT_FOUND,
+  unsupported_filter: ErrorCode.UNSUPPORTED_FILTER,
+  validation_error: ErrorCode.INVALID_PARAMS,
+  invalid_params: ErrorCode.INVALID_PARAMS,
+};
+
+/**
+ * Map an error response to an error code.
+ *
+ * Order matters: a 402 is always PAYMENT_REQUIRED (the x402 auto-payment flow
+ * keys on it, whatever the body says); then a stable `code` field from the
+ * server body wins over prose matching — known codes map onto the ErrorCode
+ * enum, unknown ones pass through verbatim so new server codes are tolerated,
+ * never flattened; bodies without a code fall back to status + prose.
  */
 export function statusToErrorCode(status, data = {}) {
+  if (status === 402) return ErrorCode.PAYMENT_REQUIRED;
+
+  const rawCode = [data?.code, data?.detail?.code]
+    .find(value => typeof value === 'string' && value.trim() !== '');
+  if (rawCode !== undefined) {
+    const serverCode = rawCode.trim();
+    return SERVER_CODE_MAP[serverCode] ?? serverCode;
+  }
+
   const message = data?.message || data?.error || '';
   const messageLower = message.toLowerCase();
-  
+
   switch (status) {
     case 400:
     case 422:
@@ -484,6 +515,8 @@ export class NansenAPI {
      * low-credit warning wants.
      */
     this.lastResponseMeta = null;
+    /** API path of the most recent request(), for pairing lastResponseMeta with a cost estimate. */
+    this.lastEndpoint = null;
   }
 
   static cleanBody(body) {
@@ -547,6 +580,7 @@ export class NansenAPI {
   }
 
   async request(endpoint, body = {}, options = {}) {
+    this.lastEndpoint = endpoint;
     const url = `${this.baseUrl}${endpoint}`;
     const { maxRetries, baseDelayMs, maxDelayMs, retryOnStatus } = this.retryOptions;
     const shouldRetry = options.retry !== false; // Allow disabling retry per-request

package/src/cli.js

@@ -15,7 +15,7 @@ import { buildResearchCommands, RESEARCH_HISTORICAL_SUBCOMMANDS } from './comman
 import { resolveAddress, isEnsName } from './ens.js';
 import fs from 'fs';
 import { getUpdateNotification, getUpgradeNotice, scheduleUpdateCheck } from './update-check.js';
-import { refreshCostMapIfStale, getCostForEndpoint } from './cost-cache.js';
+import { refreshCostMapIfStale, getCostForEndpoint, creditsCharged } from './cost-cache.js';
 import { creditWarning, noticeWarnings } from './response-meta.js';
 import { trackCommandSucceeded, trackCommandFailed } from './telemetry.js';
 import { createRequire } from 'module';
@@ -390,6 +390,10 @@ export function formatError(error) {
     code: error.code || 'UNKNOWN',
     status: error.status || null,
   };
+  // Hoisted so the id survives even if details is omitted or later pruned.
+  if (details?.requestId) {
+    result.requestId = details.requestId;
+  }
   if (details != null && !(typeof details === 'object' && !Array.isArray(details) && Object.keys(details).length === 0)) {
     result.details = details;
   }
@@ -1983,6 +1987,15 @@ export async function runCLI(rawArgs, deps = {}) {
     if (lowCredits) errorOutput(lowCredits);
     for (const notice of noticeWarnings(api.lastResponseMeta)) errorOutput(notice);
 
+    // What this call cost — authoritative header when the API sent one, else
+    // the cached spec estimate. stderr only, so stdout JSON stays pure.
+    const charged = creditsCharged(api.lastResponseMeta, api.lastEndpoint);
+    if (charged?.source === 'header') {
+      errorOutput(`Credits: ${charged.cost} (this call)`);
+    } else if (charged?.source === 'estimate') {
+      errorOutput(`Credits: ~${charged.estimate.free} free / ${charged.estimate.pro} pro (estimated)`);
+    }
+
     // Commands that handle their own output return undefined
     if (result === undefined) {
       await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });

package/src/commands/agent.js

@@ -6,6 +6,7 @@
 import crypto from 'crypto';
 import { NansenError, ErrorCode, statusToErrorCode, telemetryHeaders, packageVersion } from '../api.js';
 import { getCostForEndpoint } from '../cost-cache.js';
+import { readResponseMeta } from '../response-meta.js';
 
 /**
  * Build standard request headers, matching apiInstance.request() conventions.
@@ -25,7 +26,7 @@ function buildHeaders(apiInstance) {
  * Throw a NansenError with the same structure as apiInstance.request() errors.
  * Includes `details` field for consistency with other commands.
  */
-function throwApiError(message, status, serverDetail) {
+function throwApiError(message, status, serverDetail, errData = null, requestId = null) {
   // Match the friendly wrapper messages from apiInstance.request()
   let friendlyMessage = message;
   if (status === 401) {
@@ -36,9 +37,14 @@ function throwApiError(message, status, serverDetail) {
 
   throw new NansenError(
     friendlyMessage,
-    statusToErrorCode(status),
+    statusToErrorCode(status, errData || {}),
     status,
-    { detail: serverDetail || message, attempt: 1, retryAfterMs: null },
+    {
+      detail: serverDetail || message,
+      attempt: 1,
+      retryAfterMs: null,
+      ...(requestId && { requestId }),
+    },
   );
 }
 
@@ -273,16 +279,20 @@ EXAMPLES:
       if (!response.ok) {
         clearTimeout(timer);
         let serverDetail;
+        let errData = null;
         if (response.headers.get('content-type')?.includes('application/json')) {
           try {
-            const errData = await response.json();
+            errData = await response.json();
             serverDetail = errData.detail || errData.message;
           } catch { /* ignore parse failure */ }
         }
+        const meta = readResponseMeta(response);
         throwApiError(
           serverDetail || `Agent returned ${response.status}`,
           response.status,
           serverDetail,
+          errData,
+          meta?.requestId,
         );
       }
 

package/src/cost-cache.js

@@ -27,6 +27,21 @@ export function getCostForEndpoint(endpoint) {
   }
 }
 
+/**
+ * What did (or would) this call cost?
+ *
+ * Prefers the authoritative cost response header, then the spec-derived
+ * estimate for the endpoint, else null.
+ * Returns { cost, source: 'header' } or { estimate: { free, pro }, source: 'estimate' }.
+ */
+export function creditsCharged(meta, endpoint) {
+  const charged = meta?.credits?.cost;
+  if (charged != null) return { cost: charged, source: 'header' };
+  const estimate = endpoint ? getCostForEndpoint(endpoint) : null;
+  if (estimate != null) return { estimate, source: 'estimate' };
+  return null;
+}
+
 /**
  * Fetches the OpenAPI spec and writes the cost map to disk if the cache is
  * missing or older than 24h. Awaited inline — only blocks on cold/stale cache.

package/src/response-meta.js

@@ -19,6 +19,7 @@
 /** Header names, as documented in the API reference. */
 const CREDITS_USED = 'x-nansen-credits-used';
 const CREDITS_REMAINING = 'x-nansen-credits-remaining';
+const CREDITS_COST = 'x-nansen-credits-cost';
 const RATE_LIMIT = 'x-ratelimit-limit';
 const RATE_REMAINING = 'x-ratelimit-remaining';
 const RATE_RESET = 'x-ratelimit-reset';
@@ -34,8 +35,8 @@ const REQUEST_ID = 'x-request-id';
 function intHeader(response, name) {
   const raw = stringHeader(response, name);
   if (raw === null) return null;
-  const value = Number.parseInt(raw, 10);
-  return Number.isInteger(value) && value >= 0 ? value : null;
+  const value = Number(raw);
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
 }
 
 /**
@@ -57,6 +58,7 @@ function stringHeader(response, name) {
 export function readResponseMeta(response) {
   const used = intHeader(response, CREDITS_USED);
   const remaining = intHeader(response, CREDITS_REMAINING);
+  const cost = intHeader(response, CREDITS_COST);
   const limit = intHeader(response, RATE_LIMIT);
   const rateRemaining = intHeader(response, RATE_REMAINING);
   const resetSeconds = intHeader(response, RATE_RESET);
@@ -71,8 +73,10 @@ export function readResponseMeta(response) {
     // never parse it or assume a format.
     meta.requestId = requestId;
   }
-  if (used !== null || remaining !== null) {
-    meta.credits = { used, remaining };
+  if (used !== null || remaining !== null || cost !== null) {
+    // cost is the server's authoritative pre-flight price for this call;
+    // used is what was actually deducted. They can disagree (e.g. free rails).
+    meta.credits = { used, remaining, cost };
   }
   if (limit !== null || rateRemaining !== null || resetSeconds !== null) {
     // resetSeconds is a delta in seconds — how long the tripped window needs to
@@ -111,13 +115,15 @@ export function noticeWarnings(meta) {
 export function creditWarning(meta) {
   const credits = meta?.credits;
   if (!credits) return null;
-  const { used, remaining } = credits;
+  const { used, remaining, cost } = credits;
   if (remaining === null) return null;
   if (remaining === 0) {
     return '⚠️  Out of API credits. Top up at https://app.nansen.ai/api';
   }
-  if (used !== null && used > 0 && remaining < used) {
-    return `⚠️  ${remaining} API credit${remaining === 1 ? '' : 's'} left — less than this call cost (${used}). Top up at https://app.nansen.ai/api`;
+  // The cost header is the authoritative charge; used is the fallback.
+  const charged = cost ?? used;
+  if (charged !== null && charged > 0 && remaining < charged) {
+    return `⚠️  ${remaining} API credit${remaining === 1 ? '' : 's'} left — less than this call cost (${charged}). Top up at https://app.nansen.ai/api`;
   }
   return null;
 }