nansen-cli 1.25.0 → 1.25.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.25.1
+
+### Patch Changes
+
+- [#367](https://github.com/nansen-ai/nansen-cli/pull/367) [`9fea10a`](https://github.com/nansen-ai/nansen-cli/commit/9fea10a844acbaccf37a348dfd4efd5c32f76a4a) Thanks [@kome12](https://github.com/kome12)! - add --premium-labels flag to tgm/holders, tgm/pnl-leaderboard, tgm/perp-pnl-leaderboard, and perp-leaderboard endpoints
+
 ## 1.25.0
 
 ### Minor Changes

package/package.json

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

package/skills/nansen-trading/SKILL.md

@@ -85,13 +85,15 @@ nansen trade execute --quote "$quote_id"
 
 ## Amounts
 
-By default, `--amount` accepts **integer base units** (lamports, wei, etc). Use `--amount-unit token` to specify human-readable token amounts instead — the CLI resolves decimals locally and sends base units to the API.
+By default, `--amount` accepts **integer base units** (lamports, wei, etc). Use `--amount-unit token` for human-readable token amounts, or `--amount-unit usd` to specify a USD value — the CLI resolves price and decimals automatically.
 
 ```bash
 # Base units (default)
 nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
 # Token units (0.5 SOL = 500000000 lamports, resolved automatically)
 nansen trade quote --chain solana --from SOL --to USDC --amount 0.5 --amount-unit token
+# USD amount ($50 worth of SOL, price resolved via Nansen search API)
+nansen trade quote --chain solana --from SOL --to USDC --amount 50 --amount-unit usd
 ```
 
 | Token | Decimals | 1 token = |
@@ -100,25 +102,43 @@ nansen trade quote --chain solana --from SOL --to USDC --amount 0.5 --amount-uni
 | ETH | 18 | `1000000000000000000` |
 | USDC | 6 | `1000000` |
 
-If the user says "$20 worth of X", you must convert USD → token amount, then either pass base units or use `--amount-unit token`. For example, to buy $20 of SOL at $150/SOL: $20 ÷ $150 = 0.1333 SOL → `--amount 0.1333 --amount-unit token`. Use a price lookup (e.g. `nansen research token info`) to get the current price first.
+If the user says "$20 worth of X", use `--amount-unit usd` directly — no manual conversion needed. The CLI fetches the current price and converts for you.
 
 ## Flags
 
+### `trade quote` flags
+
 | Flag | Purpose |
 |------|---------|
 | `--chain` | Source chain: `solana` or `base` |
 | `--to-chain` | Destination chain for cross-chain swap (omit for same-chain) |
 | `--from` | Source token (symbol or address) |
 | `--to` | Destination token (symbol or address, resolved against destination chain) |
-| `--amount` | Amount in base units (integer), or token units with `--amount-unit token` |
-| `--amount-unit` | Set to `token` to specify amount in token units (e.g. 0.5 SOL) |
+| `--amount` | Amount in base units (integer), or token/USD units with `--amount-unit` |
+| `--amount-unit` | `token` for token units (e.g. 0.5 SOL), `usd` for USD (e.g. 50), `base` = default |
 | `--wallet` | Wallet name (default: default wallet) |
 | `--to-wallet` | Destination wallet address (auto-derived for cross-chain if omitted) |
 | `--slippage` | Slippage tolerance as decimal (e.g. 0.03) |
-| `--quote` | Quote ID for execute |
+| `--auto-slippage` | Enable auto slippage calculation |
+| `--max-auto-slippage` | Max auto slippage when `--auto-slippage` is enabled |
+| `--swap-mode` | `exactIn` (default) or `exactOut` |
+
+### `trade execute` flags
+
+| Flag | Purpose |
+|------|---------|
+| `--quote` | Quote ID from `trade quote` |
+| `--wallet` | Wallet name (default: default wallet) |
+| `--quote-index` | Pin a specific quote by index (0-based) when multiple quotes were returned |
 | `--no-simulate` | Skip pre-broadcast simulation |
-| `--tx-hash` | Source tx hash (for bridge-status) |
+
+### `trade bridge-status` flags
+
+| Flag | Purpose |
+|------|---------|
+| `--tx-hash` | Source tx hash |
 | `--from-chain` | Source chain (for bridge-status) |
+| `--to-chain` | Destination chain (for bridge-status) |
 
 ## Environment Variables
 

package/src/api.js

@@ -971,19 +971,21 @@ export class NansenAPI {
   }
 
   async tokenHolders(params = {}) {
-    const { tokenAddress, chain = 'solana', labelType = 'all_holders', filters = {}, orderBy, pagination } = params;
+    const { tokenAddress, chain = 'solana', labelType = 'all_holders', filters = {}, orderBy, pagination, withLabels } = params;
     if (tokenAddress) {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    return this.request('/api/v1/tgm/holders', {
+    const body = {
       token_address: tokenAddress,
       chain,
       label_type: labelType,
       filters,
       order_by: orderBy,
       pagination
-    });
+    };
+    if (withLabels !== undefined) body.premium_labels = withLabels;
+    return this.request('/api/v1/tgm/holders', body);
   }
 
   async tokenFlows(params = {}) {
@@ -1027,19 +1029,21 @@ export class NansenAPI {
   }
 
   async tokenPnlLeaderboard(params = {}) {
-    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination, days = 30 } = params;
+    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination, days = 30, withLabels } = params;
     if (tokenAddress) {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    return this.request('/api/v1/tgm/pnl-leaderboard', {
+    const body = {
       token_address: tokenAddress,
       chain,
       date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
-    });
+    };
+    if (withLabels !== undefined) body.premium_labels = withLabels;
+    return this.request('/api/v1/tgm/pnl-leaderboard', body);
   }
 
   async tokenWhoBoughtSold(params = {}) {
@@ -1126,14 +1130,16 @@ export class NansenAPI {
   }
 
   async tokenPerpPnlLeaderboard(params = {}) {
-    const { tokenSymbol, filters = {}, orderBy, pagination, days = 30 } = params;
-    return this.request('/api/v1/tgm/perp-pnl-leaderboard', {
+    const { tokenSymbol, filters = {}, orderBy, pagination, days = 30, withLabels } = params;
+    const body = {
       token_symbol: tokenSymbol,
       date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
-    });
+    };
+    if (withLabels !== undefined) body.premium_labels = withLabels;
+    return this.request('/api/v1/tgm/perp-pnl-leaderboard', body);
   }
 
   async tokenIndicators(params = {}) {
@@ -1187,13 +1193,15 @@ export class NansenAPI {
   }
 
   async perpLeaderboard(params = {}) {
-    const { filters = {}, orderBy, pagination, days = 30 } = params;
-    return this.request('/api/v1/perp-leaderboard', {
+    const { filters = {}, orderBy, pagination, days = 30, withLabels } = params;
+    const body = {
       date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
-    });
+    };
+    if (withLabels !== undefined) body.premium_labels = withLabels;
+    return this.request('/api/v1/perp-leaderboard', body);
   }
 
   // ============= Prediction Market Endpoints =============

package/src/cli.js

@@ -30,6 +30,23 @@ export const SCHEMA = { version: VERSION, ...schemaDefinition };
 
 // ============= Pagination =============
 
+/**
+ * Resolve a boolean CLI option that can be passed as either:
+ *   --flag          (flag=true, options key absent)
+ *   --flag true     (options key = 'true')
+ *   --flag false    (options key = 'false')
+ * Returns true/false/undefined (undefined = not supplied).
+ */
+export function resolveBooleanOption(options, flags, key) {
+  if (options[key] !== undefined) {
+    const val = String(options[key]).toLowerCase();
+    if (val === 'true' || val === '1') return true;
+    if (val === 'false' || val === '0') return false;
+  }
+  if (flags[key] !== undefined) return Boolean(flags[key]);
+  return undefined;
+}
+
 export function buildPagination(options) {
   if (!options.limit && !options.page) return undefined;
   return {
@@ -1237,14 +1254,17 @@ export function buildCommands(deps = {}) {
           }
           return result;
         },
-        'holders': () => apiInstance.tokenHolders({ tokenAddress, chain, labelType: onlySmartMoney ? 'smart_money' : 'all_holders', filters, orderBy, pagination }),
+        'holders': () => apiInstance.tokenHolders({ tokenAddress, chain, labelType: onlySmartMoney ? 'smart_money' : 'all_holders', filters, orderBy, pagination, withLabels: resolveBooleanOption(options, flags, 'premium-labels') }),
         'flows': () => {
           const date = parseDateOption(options.date, days);
           const label = options.label;
           return apiInstance.tokenFlows({ tokenAddress, chain, label, filters, orderBy, pagination, days, date });
         },
         'dex-trades': () => apiInstance.tokenDexTrades({ tokenAddress, chain, onlySmartMoney, filters, orderBy, pagination, days }),
-        'pnl': () => apiInstance.tokenPnlLeaderboard({ tokenAddress, chain, filters, orderBy, pagination, days }),
+        'pnl': () => {
+          const withLabels = resolveBooleanOption(options, flags, 'premium-labels');
+          return apiInstance.tokenPnlLeaderboard({ tokenAddress, chain, filters, orderBy, pagination, days, withLabels });
+        },
         'who-bought-sold': () => {
           const date = parseDateOption(options.date, days);
           const buyOrSell = (options['buy-or-sell'] || 'BUY').toUpperCase();
@@ -1260,7 +1280,10 @@ export function buildCommands(deps = {}) {
         'jup-dca': () => apiInstance.tokenJupDca({ tokenAddress, filters, orderBy, pagination }),
         'perp-trades': () => apiInstance.tokenPerpTrades({ tokenSymbol, filters, orderBy, pagination, days }),
         'perp-positions': () => apiInstance.tokenPerpPositions({ tokenSymbol, filters, orderBy, pagination }),
-        'perp-pnl-leaderboard': () => apiInstance.tokenPerpPnlLeaderboard({ tokenSymbol, filters, orderBy, pagination, days }),
+        'perp-pnl-leaderboard': () => {
+          const withLabels = resolveBooleanOption(options, flags, 'premium-labels');
+          return apiInstance.tokenPerpPnlLeaderboard({ tokenSymbol, filters, orderBy, pagination, days, withLabels });
+        },
         'help': () => ({
           commands: ['info', 'ohlcv', 'screener', 'holders', 'flows', 'dex-trades', 'pnl', 'who-bought-sold', 'flow-intelligence', 'transfers', 'jup-dca', 'perp-trades', 'perp-positions', 'perp-pnl-leaderboard'],
           description: 'Token God Mode endpoints',
@@ -1334,7 +1357,10 @@ export function buildCommands(deps = {}) {
 
       const handlers = {
         'screener': () => apiInstance.perpScreener({ filters, orderBy, pagination, days }),
-        'leaderboard': () => apiInstance.perpLeaderboard({ filters, orderBy, pagination, days }),
+        'leaderboard': () => {
+          const withLabels = resolveBooleanOption(options, flags, 'premium-labels');
+          return apiInstance.perpLeaderboard({ filters, orderBy, pagination, days, withLabels });
+        },
         'help': () => ({
           commands: ['screener', 'leaderboard'],
           description: 'Perpetual futures analytics endpoints',

package/src/schema.json

@@ -283,7 +283,13 @@
                 },
                 "label": {
                   "description": "Holder segment to filter flows by",
-                  "enum": ["top_100_holders", "smart_money", "public_figure", "whale", "exchange"],
+                  "enum": [
+                    "top_100_holders",
+                    "smart_money",
+                    "public_figure",
+                    "whale",
+                    "exchange"
+                  ],
                   "default": "top_100_holders"
                 }
               }
@@ -303,7 +309,10 @@
                 },
                 "buy-or-sell": {
                   "description": "Filter by buy or sell side",
-                  "enum": ["BUY", "SELL"],
+                  "enum": [
+                    "BUY",
+                    "SELL"
+                  ],
                   "default": "BUY"
                 }
               }
@@ -347,6 +356,10 @@
                 },
                 "token": {
                   "required": true
+                },
+                "premium-labels": {
+                  "description": "Include premium Nansen labels in the response (true=premium, false=free-tier). When omitted, uses API default.",
+                  "type": "boolean"
                 }
               }
             },
@@ -362,6 +375,10 @@
                 },
                 "days": {
                   "default": 30
+                },
+                "premium-labels": {
+                  "description": "Include premium Nansen labels in the response (true=premium, false=free-tier). When omitted, uses API default.",
+                  "type": "boolean"
                 }
               }
             },
@@ -374,6 +391,10 @@
                 },
                 "days": {
                   "default": 30
+                },
+                "premium-labels": {
+                  "description": "Include premium Nansen labels in the response (true=premium, false=free-tier). When omitted, uses API default.",
+                  "type": "boolean"
                 }
               }
             },
@@ -515,6 +536,10 @@
               "options": {
                 "days": {
                   "default": 30
+                },
+                "premium-labels": {
+                  "description": "Include premium Nansen labels in the response (true=premium, false=free-tier). When omitted, uses API default.",
+                  "type": "boolean"
                 }
               }
             }