nansen-cli 1.27.0 → 1.28.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.28.0
+
+### Minor Changes
+
+- [#417](https://github.com/nansen-ai/nansen-cli/pull/417) [`ae6079f`](https://github.com/nansen-ai/nansen-cli/commit/ae6079f12d06d11fe357237b84387fcaffcfd387) Thanks [@0xlaveen](https://github.com/0xlaveen)! - Add `trade limit-order` commands (create, list, cancel, update) for Jupiter Limit Order V2 on Solana. Supports local, Privy, and WalletConnect wallets.
+
+- [#413](https://github.com/nansen-ai/nansen-cli/pull/413) [`94bd349`](https://github.com/nansen-ai/nansen-cli/commit/94bd349bdf9a0a3f3389975144281306eea0e4ca) Thanks [@jake-kennis](https://github.com/jake-kennis)! - Add `top-tokens` subcommand to discover top-scoring tokens by Nansen Score. Calls the public endpoint (`/api/v1/nansen-score/top-tokens`) with optional `--market-cap` filter.
+
+## 1.27.1
+
+### Patch Changes
+
+- [#408](https://github.com/nansen-ai/nansen-cli/pull/408) [`d1e9787`](https://github.com/nansen-ai/nansen-cli/commit/d1e97871b897153a9e1cd587897ff2f4bbed6c88) Thanks [@0xlaveen](https://github.com/0xlaveen)! - Add cross-chain notes to trade help text and document --to-chain constraints in schema.json.
+
 ## 1.27.0
 
 ### Minor Changes

package/package.json

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

package/skills/nansen-token-screener/SKILL.md

@@ -45,10 +45,64 @@ nansen research token indicators --token $TOKEN --chain $CHAIN
 # Flow intelligence — only use for promising tokens from screener/indicators above
 nansen research token flow-intelligence --token $TOKEN --chain $CHAIN
 # → net_flow_usd per label: smart_trader, whale, exchange, fresh_wallets, public_figure
+
+# Nansen Score Top Tokens — "what should I buy?" (public endpoint, any authenticated API key)
+# Use this FIRST for discovery, then drill into individual tokens with `indicators` above
+nansen research token top-tokens --limit 25
+nansen research token top-tokens --market-cap largecap --limit 10
+# → chain, token_address, token_symbol, performance_score, risk_score,
+#   per-indicator contributions, market_cap_group, latest_date, last_trigger_on
 ```
 
 Screener timeframes: `5m`, `10m`, `1h`, `6h`, `24h`, `7d`, `30d`
 
 Indicators: score is "bullish"/"bearish"/"neutral". signal_percentile > 70 = historically significant. Some tokens return empty indicators — not an error.
 
+## Top tokens — Nansen Score field reference
+
+Results are pre-filtered to `performance_score >= 15` server-side and returned sorted by:
+1. `performance_score` DESC
+2. `market_cap_group` priority (largecap → midcap → lowcap)
+3. `risk_score` DESC
+4. 24h volume DESC
+
+So row 0 is always the strongest candidate for the filter you applied — no client-side ranking needed.
+
+Market cap buckets (used in both the sort priority and the `--market-cap` filter):
+- `lowcap`: market cap < $100M
+- `midcap`: market cap $100M – $1B
+- `largecap`: market cap > $1B
+
+Every contribution is **ternary** — exactly one of `{negative, 0, positive}` per field. No partial values. Zero means "indicator didn't apply to this token" (out of scope), not "indicator was neutral".
+
+**Performance Score (Alpha — "likely to outperform BTC over 7–30d")**
+Range: `-60 to +75` (arithmetic bounds; live max is closer to `+45` since no single token hits every positive indicator simultaneously). Buy threshold: `>= 15`. Sum of the five `*_performance` fields below.
+| Field | Contribution | Trigger | What the underlying indicator measures |
+|---|---|---|---|
+| `price_momentum_performance` | +30 / 0 | upstream score `bullish` → +30 | Price momentum, scored against separate thresholds for large-cap vs. low/mid-cap tokens. |
+| `chain_fees_performance` | +30 / 0 | `bullish` (30-day fee growth > +1%) → +30 | 30-day spending momentum on network fees (geometric mean of daily returns). **Only tracked for a handful of L1 native tokens (e.g. ETH, TRX, AVAX, RON); always 0 for every other token.** |
+| `trading_range_performance` | +15 / 0 | `bullish` (price breaks above resistance in an uptrend) → +15 | 14-day price trend combined with position vs. nearest support/resistance. In practice fires mostly on established tokens that have well-defined levels — can fire at any market cap, but is rare for new / low-liquidity tokens. |
+| `chain_tvl_performance` | 0 / -35 | `bearish` (composite TVL growth < 0) → -35 | TVL momentum composite signal. Only non-zero for chains / L2s whose TVL is tracked. No positive path exists — the field only deducts. |
+| `protocol_fees_performance` | 0 / -25 | `bearish` (14-day fee growth < -3%) → -25 | 14-day protocol fee momentum. Only non-zero for tokens backed by protocols with measurable fee revenue. No positive path — deduction only. |
+
+**Risk Score (Safety — "filters falling knives / dangerous setups")**
+Range: `-60 to +80` (arithmetic bounds). Safety threshold: `> 0` (positive = safer, negative = riskier). Sum of the four `*_risk` fields below. For every risk field: upstream score `low` → positive contribution, `high` → negative contribution, `medium`/missing → 0.
+| Field | Contribution | What the underlying indicator measures |
+|---|---|---|
+| `btc_reflexivity_risk` | +40 / -20 | Rolling 5-event median ratio of token drop to BTC drop on days BTC falls >3%. Ratio ≤ 1 → `low` → **+40** (token holds up as well as or better than BTC on drawdowns). Ratio > 1 → `high` → **-20** (token drops harder than BTC). Skipped for stablecoins and tokens with <$1M 24h volume. |
+| `liquidity_risk` | +20 / -20 | Ratio of on-chain liquidity to market cap (`total_liquidity_usd / market_cap_usd`). Higher ratio → `low` → **+20** (deep books relative to cap). Very thin ratio → `high` → **-20**. |
+| `concentration_risk` | +10 / -10 | Top-10 holder concentration as a fraction of supply. `< 0.12` → `low` → **+10** (well-distributed). `> 0.55` → `high` → **-10** (whale-concentrated). |
+| `inflation_risk` | +10 / -10 | EMA of daily token supply inflation rate. Negative / near-zero → `low` → **+10** (stable or deflationary supply). Strongly positive → `high` → **-10** (high dilution). Only evaluated for tokens >= $100M market cap. |
+
+Other response fields:
+- `market_cap_group`: `lowcap` / `midcap` / `largecap` — see thresholds above.
+- `latest_date`: ISO datetime of the most recent indicator refresh for this token.
+- `last_trigger_on`: ISO datetime of the most recent trigger across contributing indicators (MAX aggregate — individual indicators may be days-to-months stale even when this looks fresh). Use `indicators` on a specific token to audit per-indicator ages.
+
+**Stablecoins rank high but aren't picks.** USDC, USDT, DAI, FDUSD and similar score well on chain_fees + liquidity indicators but aren't what "what should I buy" means. Filter them out of the shortlist using the canonical whitelist at `nansen-dbt-ch-tokens/seeds/stablecoins_for_indicator.csv` before drilling into `indicators`.
+
+Typical workflow: start with `top-tokens` for a shortlist → drop stablecoins → run `indicators` on the top 3–5 to inspect individual signals and their signal_percentile → `flow-intelligence` only on the finalists to confirm SM conviction.
+
+Field meanings and contribution mappings above are sourced from `nansen-dbt-ch-tokens/models/indicators/api_nansen_score_indicators_all_tokens_latest.sql` and per-indicator model yml files. Sign conventions and live value ranges were validated against production ClickHouse data.
+
 Flow intelligence is credit-heavy. Use it to confirm SM conviction on tokens that already look promising from screener + indicators, not as a first pass on every token.

package/src/api.js

@@ -1203,6 +1203,13 @@ export class NansenAPI {
     });
   }
 
+  async topTokens(params = {}) {
+    const { marketCapGroup, limit = 25 } = params;
+    const body = { limit };
+    if (marketCapGroup) body.market_cap_group = marketCapGroup;
+    return this.request('/api/v1/nansen-score/top-tokens', body);
+  }
+
   // ============= Perp Endpoints =============
 
   async perpScreener(params = {}) {

package/src/cli.js

@@ -6,6 +6,7 @@
 import { NansenAPI, NansenError, CommandError, ErrorCode, saveConfig, deleteConfig, getConfigFile, clearCache, getCacheDir, validateAddress, normalizeAddress, sleep } from './api.js';
 import { buildWalletCommands } from './wallet.js';
 import { buildTradingCommands } from './trading.js';
+import { buildLimitOrderCommands } from './limit-order.js';
 import { formatAlertsTable, buildAlertsCommands } from './commands/alerts.js';
 import { buildAgentCommands } from './commands/agent.js';
 import { resolveAddress, isEnsName } from './ens.js';
@@ -1276,8 +1277,13 @@ export function buildCommands(deps = {}) {
           const withLabels = resolveBooleanOption(options, flags, 'premium-labels');
           return apiInstance.tokenPerpPnlLeaderboard({ tokenSymbol, filters, orderBy, pagination, days, withLabels });
         },
+        'top-tokens': () => {
+          const marketCapGroup = options['market-cap'] || options['market-cap-group'];
+          const limit = options.limit ? parseInt(options.limit) : undefined;
+          return apiInstance.topTokens({ marketCapGroup, limit });
+        },
         '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'],
+          commands: ['info', 'ohlcv', 'screener', 'holders', 'flows', 'dex-trades', 'pnl', 'who-bought-sold', 'flow-intelligence', 'transfers', 'jup-dca', 'perp-trades', 'perp-positions', 'perp-pnl-leaderboard', 'top-tokens'],
           description: 'Token God Mode endpoints',
           example: 'nansen token screener --chain solana --timeframe 24h --smart-money --include-stablecoins false'
         })
@@ -1474,8 +1480,9 @@ export function buildCommands(deps = {}) {
     return cmds[category](args.slice(1), apiInstance, flags, options);
   };
 
-  // 'trade' delegates to quote/execute from buildTradingCommands
+  // 'trade' delegates to quote/execute from buildTradingCommands and limit-order from buildLimitOrderCommands
   const tradingCmds = buildTradingCommands(deps);
+  const limitOrderCmds = buildLimitOrderCommands(deps);
   cmds['trade'] = async (args, apiInstance, flags, options) => {
     const sub = args[0];
     if (!sub || sub === 'help') {
@@ -1485,12 +1492,14 @@ SUBCOMMANDS:
   quote          Get a swap quote (price, route, fees)
   execute        Sign and broadcast a quoted swap
   bridge-status  Check cross-chain bridge transaction status
+  limit-order    Limit order management (Solana only)
 
 USAGE:
   nansen trade quote --chain <chain> --from <token> --to <token> --amount <units> [--wallet <name>]
   nansen trade quote --chain <chain> --to-chain <chain> --from <token> --to <token> --amount <units>
   nansen trade execute --quote <quoteId> [--wallet <name>]
   nansen trade bridge-status --tx-hash <hash> --from-chain <chain> --to-chain <chain>
+  nansen trade limit-order <create|list|cancel|update> [options]
 
 EXAMPLES:
   nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
@@ -1498,18 +1507,53 @@ EXAMPLES:
   nansen trade quote --chain base --to-chain solana --from USDC --to USDC --amount 1000000
   nansen trade execute --quote 1708900000000-abc123
   nansen trade bridge-status --tx-hash 0xabc... --from-chain base --to-chain solana
+  nansen trade limit-order create --from SOL --to USDC --amount 1000000000 --trigger-mint SOL --trigger-condition below --trigger-price 80
+  nansen trade limit-order list
 
 WALLET:
-  --wallet <name>   Use a named wallet, or "walletconnect" / "wc" for WalletConnect (EVM only).
+  --wallet <name>   Use a named wallet, or "walletconnect" / "wc" for WalletConnect.
                     Defaults to the default local wallet if omitted.
 
 SYMBOLS:
   Common tokens resolve automatically: SOL, ETH, USDC, USDT, WETH
-  Raw addresses are also accepted.`);
+  Raw addresses are also accepted.
+
+CROSS-CHAIN NOTES (when using --to-chain):
+  Supported combos:
+    native → native (ETH <-> SOL) — requires $5+ per trade
+    USDC → USDC (both directions)
+    USDC → native (USDC → ETH or SOL)
+    native → USDC (ETH/SOL → USDC)
+    non-native → non-native — not supported (use USDC as intermediate)
+  Bridge provider: Li.Fi
+  Typical bridge time: 1-5 minutes`);
       return;
     }
+    if (sub === 'limit-order') {
+      const loSub = args[1];
+      if (!loSub || loSub === 'help') {
+        log(`nansen trade limit-order — Limit order commands (Solana only)
+
+SUBCOMMANDS:
+  create    Place a new limit order
+  list      List your limit orders
+  cancel    Cancel an open order
+  update    Update trigger price or slippage
+
+USAGE:
+  nansen trade limit-order create --from <token> --to <token> --amount <units> --trigger-mint <token> --trigger-condition <above|below> --trigger-price <usd>
+  nansen trade limit-order list [--state <active|past>]
+  nansen trade limit-order cancel --order <orderId>
+  nansen trade limit-order update --order <orderId> --trigger-price <usd>`);
+        return;
+      }
+      if (!limitOrderCmds[loSub]) {
+        throw new NansenError(`Unknown limit-order subcommand: ${loSub}. Available: create, list, cancel, update`, ErrorCode.UNKNOWN);
+      }
+      return limitOrderCmds[loSub](args.slice(2), apiInstance, flags, options);
+    }
     if (!tradingCmds[sub]) {
-      throw new NansenError(`Unknown trade subcommand: ${sub}. Available: quote, execute, bridge-status`, ErrorCode.UNKNOWN);
+      throw new NansenError(`Unknown trade subcommand: ${sub}. Available: quote, execute, bridge-status, limit-order`, ErrorCode.UNKNOWN);
     }
     return tradingCmds[sub](args.slice(1), apiInstance, flags, options);
   };

package/src/keychain.js

@@ -227,3 +227,4 @@ export function deleteCredentialsFile() {
 export function resolvePassword() {
   return retrievePassword().password;
 }
+