nansen-cli 1.16.1 → 1.18.0

package/src/api.js

@@ -7,9 +7,15 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { EVM_CHAINS } from './chain-ids.js';
+import { getAnonymousId, TELEMETRY_DISABLED } from './telemetry.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+function telemetryHeaders() {
+  if (TELEMETRY_DISABLED) return {};
+  return { 'X-Anonymous-Id': getAnonymousId() };
+}
+
 const { version: packageVersion } = JSON.parse(
   fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
 );
@@ -418,6 +424,53 @@ export class NansenAPI {
     );
   }
 
+  /**
+   * Retry a POST request with a payment signature.
+   * Returns parsed JSON if the paid request succeeds, or null if still rejected.
+   * Logs the payment and warns about low balance when walletLabel and network are given.
+   *
+   * @param {string} signature - Payment-Signature header value
+   * @param {string|null} walletLabel - Display label for logging, e.g. "local wallet alice"
+   * @param {string|null} network - x402 network string for balance check, e.g. "eip155:8453"
+   * @param {string} url - Request URL
+   * @param {object} body - Request body (will be cleaned)
+   * @param {object} [options={}] - Request options (may include .headers)
+   * @returns {Promise<object|null>} Parsed JSON on success, null if rejected
+   *
+   * TODO: full fix — extract the entire x402 provider dispatch from request() into
+   * an attemptX402Payment() method so adding a new payment provider only requires
+   * touching that one method, not hunting inside the retry loop.
+   */
+  async _x402Retry(signature, walletLabel, network, url, body, options = {}) {
+    const paidResponse = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Client-Type': 'nansen-cli',
+        'X-Client-Version': packageVersion,
+        ...telemetryHeaders(),
+        'Payment-Signature': signature,
+        ...this.defaultHeaders,
+        ...options.headers,
+      },
+      body: JSON.stringify(NansenAPI.cleanBody(body)),
+    });
+    if (!paidResponse.ok) return null;
+    if (walletLabel) {
+      console.error(`[x402] Paid via ${walletLabel}${network ? ` (${network})` : ''}`);
+    }
+    if (network) {
+      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();
+  }
+
   async request(endpoint, body = {}, options = {}) {
     const url = `${this.baseUrl}${endpoint}`;
     const { maxRetries, baseDelayMs, maxDelayMs, retryOnStatus } = this.retryOptions;
@@ -439,17 +492,20 @@ export class NansenAPI {
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       let response;
       try {
+        const method = options.method || 'POST';
+        const isGet = method === 'GET';
         response = await fetch(url, {
-          method: 'POST',
+          method,
           headers: {
-            'Content-Type': 'application/json',
+            ...(!isGet && { 'Content-Type': 'application/json' }),
             'X-Client-Type': 'nansen-cli',
             'X-Client-Version': packageVersion,
+            ...telemetryHeaders(),
             ...(this.apiKey ? { 'apikey': this.apiKey } : {}),
             ...this.defaultHeaders,
             ...options.headers
           },
-          body: JSON.stringify(NansenAPI.cleanBody(body))
+          ...(!isGet && method !== 'DELETE' && { body: JSON.stringify(NansenAPI.cleanBody(body)) })
         });
       } catch (err) {
         // Network-level errors - retry these too
@@ -490,12 +546,20 @@ export class NansenAPI {
       }
 
       if (!response.ok) {
-        let message = data.message || data.error || `API error: ${response.status}`;
+        let message = data.message || data.error
+          || (typeof data.detail === 'string' ? data.detail : data.detail?.message)
+          || `API error: ${response.status}`;
+        // nansen-api proxy stringifies nested error dicts via Python str(), producing
+        // "{'message': 'actual error', ...}". Extract the inner message if present.
+        const nestedMatch = typeof message === 'string' && message.match(/['"]message['"]\s*:\s*['"](.*?)['"]/);
+        if (nestedMatch) message = nestedMatch[1];
         const code = statusToErrorCode(response.status, data);
         const retryAfterMs = parseRetryAfter(response.headers.get('retry-after'));
 
         // Enhance messages for specific error codes
-        if (code === ErrorCode.UNSUPPORTED_FILTER) {
+        if (code === ErrorCode.UNAUTHORIZED) {
+          message = this.apiKey ? message : 'Not logged in. Run: nansen login';
+        } else if (code === ErrorCode.UNSUPPORTED_FILTER) {
           message = message.replace(/\.+$/, '') + '. This filter is not supported for this token/chain combination. Do not retry.';
         } else if (code === ErrorCode.CREDITS_EXHAUSTED) {
           message = message.replace(/\.+$/, '') + '. No retry will help. Check your Nansen dashboard for credit balance.';
@@ -524,29 +588,8 @@ export class NansenAPI {
               try {
                 const { createPrivyPaymentSignatures } = await import('./privy.js');
                 for await (const { signature, network } of createPrivyPaymentSignatures(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) {
-                    console.error(`[x402] Paid via Privy wallet ${defaultWalletName} (${network})`);
-                    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();
-                  }
+                  const result = await this._x402Retry(signature, `Privy wallet ${defaultWalletName}`, network, url, body, options);
+                  if (result !== null) return result;
                 }
               } catch (privyErr) {
                 message = `x402 Privy payment failed: ${privyErr.message}`;
@@ -557,30 +600,8 @@ export class NansenAPI {
               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) {
-                    console.error(`[x402] Paid via local wallet ${defaultWalletName} (${network})`);
-                    // 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();
-                  }
+                  const result = await this._x402Retry(signature, `local wallet ${defaultWalletName}`, network, url, body, options);
+                  if (result !== null) return result;
                   // This payment option was rejected, try next
                 }
               } catch { /* local wallet unavailable, try WalletConnect */ }
@@ -604,21 +625,8 @@ export class NansenAPI {
                   try {
                     const { handleX402Payment } = await import('./walletconnect-x402.js');
                     const paymentSignature = await handleX402Payment(paymentRequirements);
-                    const paidResponse = await fetch(url, {
-                      method: 'POST',
-                      headers: {
-                        'Content-Type': 'application/json',
-                        'X-Client-Type': 'nansen-cli',
-                        'X-Client-Version': packageVersion,
-                        'Payment-Signature': paymentSignature,
-                        ...this.defaultHeaders,
-                        ...options.headers,
-                      },
-                      body: JSON.stringify(NansenAPI.cleanBody(body)),
-                    });
-                    if (paidResponse.ok) {
-                      return await paidResponse.json();
-                    }
+                    const result = await this._x402Retry(paymentSignature, 'WalletConnect', null, url, body, options);
+                    if (result !== null) return result;
                   } catch (x402Err) {
                     if (!this.apiKey) {
                       message = 'No API key configured. Two ways to authenticate:\n' +
@@ -674,6 +682,12 @@ export class NansenAPI {
     throw lastError;
   }
 
+  // ============= Account Endpoint =============
+
+  async getAccount() {
+    return this.request('/api/v1/account', {}, { method: 'GET', cache: false });
+  }
+
   // ============= Smart Money Endpoints =============
   
   async smartMoneyNetflow(params = {}) {
@@ -821,6 +835,31 @@ export class NansenAPI {
     return this.request('/api/v1/search/general', body);
   }
 
+  async webSearch(params = {}) {
+    const { queries, numResults = 10 } = params;
+    if (!queries || queries.length === 0) {
+      throw new NansenError('At least one query is required', ErrorCode.MISSING_PARAM);
+    }
+    return this.request('/api/v1/search/web-search', {
+      queries,
+      num_results: numResults,
+    }, { cache: false });
+  }
+
+  async webFetch(params = {}) {
+    const { urls, question } = params;
+    if (!urls || urls.length === 0) {
+      throw new NansenError('At least one URL is required', ErrorCode.MISSING_PARAM);
+    }
+    if (!question) {
+      throw new NansenError('A question is required', ErrorCode.MISSING_PARAM);
+    }
+    return this.request('/api/v1/search/web-fetch', {
+      urls,
+      question,
+    }, { cache: false });
+  }
+
   async addressHistoricalBalances(params = {}) {
     const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30 } = params;
     if (address) {
@@ -1145,7 +1184,7 @@ export class NansenAPI {
 
   async pmOhlcv(params = {}) {
     const { marketId, sort, pagination } = params;
-    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/ohlcv', {
       market_id: marketId,
       sort,
@@ -1155,7 +1194,7 @@ export class NansenAPI {
 
   async pmOrderbook(params = {}) {
     const { marketId, pagination } = params;
-    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/orderbook', {
       market_id: marketId,
       pagination
@@ -1164,7 +1203,7 @@ export class NansenAPI {
 
   async pmTopHolders(params = {}) {
     const { marketId, sort, pagination } = params;
-    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/top-holders', {
       market_id: marketId,
       sort,
@@ -1174,7 +1213,7 @@ export class NansenAPI {
 
   async pmTradesByMarket(params = {}) {
     const { marketId, pagination } = params;
-    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/trades-by-market', {
       market_id: marketId,
       pagination
@@ -1214,7 +1253,7 @@ export class NansenAPI {
 
   async pmPnlByMarket(params = {}) {
     const { marketId, pagination } = params;
-    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/pnl-by-market', {
       market_id: marketId,
       pagination
@@ -1234,7 +1273,7 @@ export class NansenAPI {
 
   async pmPositionDetail(params = {}) {
     const { marketId, pagination } = params;
-    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/position-detail', {
       market_id: marketId,
       pagination
@@ -1266,6 +1305,38 @@ export class NansenAPI {
       wallet_address: walletAddress
     });
   }
+
+  // ============= Smart Alert Endpoints =============
+
+  async alertsList(params = {}) {
+    const defined = Object.fromEntries(Object.entries(params).filter(([, v]) => v !== undefined));
+    const qs = Object.keys(defined).length > 0 ? '?' + new URLSearchParams(defined).toString() : '';
+    return this.request(`/api/v1/smart-alert/list${qs}`, {}, { method: 'GET' });
+  }
+
+  async alertsCreate(params = {}) {
+    return this.request('/api/v1/smart-alert', params);
+  }
+
+  async alertsUpdate(params = {}) {
+    return this.request('/api/v1/smart-alert', params, { method: 'PATCH' });
+  }
+
+  async alertsToggle(params = {}) {
+    return this.request('/api/v1/smart-alert/toggle', params, { method: 'PATCH' });
+  }
+
+  async alertsGet(id) {
+    // TODO: replace with GET /api/v1/smart-alert/{id} once a get-by-id endpoint exists.
+    // Fetching the full list does not scale for users with many alerts.
+    const result = await this.alertsList();
+    const alerts = Array.isArray(result) ? result : result?.alerts ?? result?.data ?? [];
+    return alerts.find(a => a.id === id) ?? null;
+  }
+
+  async alertsDelete(alertId) {
+    return this.request(`/api/v1/smart-alert/${encodeURIComponent(alertId)}`, {}, { method: 'DELETE' });
+  }
 }
 
 export default NansenAPI;