nansen-cli 1.27.1 → 1.28.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.27.1",
+  "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,9 +1507,11 @@ 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:
@@ -1518,8 +1529,31 @@ CROSS-CHAIN NOTES (when using --to-chain):
   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;
 }
+

package/src/limit-order.js

@@ -0,0 +1,873 @@
+/**
+ * Nansen CLI - Limit Order Commands (Jupiter Trigger V2)
+ *
+ * Supports create, list, cancel, and update of limit orders on Solana.
+ * Uses challenge-response JWT auth with disk caching.
+ * Zero external dependencies — uses Node.js built-in crypto only.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { base58Encode, exportWallet, getWalletConfig, showWallet } from './wallet.js';
+import { signEd25519, base58Decode, parseAmount, getTokenInfo } from './transfer.js';
+import { signSolanaTransaction, resolveTokenAddress } from './trading.js';
+import { validateTokenAddress } from './api.js';
+import { getWalletConnectAddress, sendSolanaTransactionViaWalletConnect, signSolanaMessageViaWalletConnect } from './walletconnect-trading.js';
+import { retrievePassword } from './keychain.js';
+import { CHAIN_RPCS } from './rpc-urls.js';
+
+// ============= Constants =============
+
+const TRADING_API_URL = process.env.NANSEN_TRADING_API_URL || 'https://trading-api.nansen.ai';
+const LO_PREFIX = '/limit-order/v2';
+const SOLSCAN_TX_URL = 'https://solscan.io/tx/';
+
+// ============= JWT Auth & Caching (Local File) =============
+
+function getAuthFilePath() {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  return path.join(home, '.nansen', 'limit-order-auth.json');
+}
+
+/**
+ * Save a JWT token to ~/.nansen/limit-order-auth.json.
+ * Keyed by wallet pubkey so switching wallets invalidates correctly.
+ */
+export function saveCachedToken(walletPubkey, token) {
+  try {
+    const filePath = getAuthFilePath();
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { mode: 0o700, recursive: true });
+    }
+    const data = JSON.stringify({
+      walletPubkey,
+      token,
+      // 23-hour TTL provides 1-hour safety margin against server's 24-hour JWT
+      expiresAt: Date.now() + 23 * 3600 * 1000,
+    });
+    fs.writeFileSync(filePath, data, { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load a cached JWT token from ~/.nansen/limit-order-auth.json.
+ * Returns the token string if valid and not expired, null otherwise.
+ */
+export function loadCachedToken(walletPubkey) {
+  try {
+    const filePath = getAuthFilePath();
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const data = JSON.parse(raw);
+    if (data.walletPubkey !== walletPubkey) return null;
+    // 5-minute buffer before expiry to avoid mid-request failures
+    if (data.expiresAt <= Date.now() + 300_000) return null;
+    return data.token;
+  } catch {
+    return null;
+  }
+}
+
+// ============= API Client =============
+
+/**
+ * Make an authenticated request to the limit order V2 API.
+ */
+async function loFetch(method, endpoint, { token, body, query } = {}) {
+  const url = new URL(`${LO_PREFIX}${endpoint}`, TRADING_API_URL);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+
+  const headers = {
+    'Accept': 'application/json',
+    'Content-Type': 'application/json',
+  };
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+  if (process.env.NANSEN_API_KEY) {
+    headers['X-API-Key'] = process.env.NANSEN_API_KEY;
+  }
+
+  const opts = { method, headers };
+  if (body !== undefined) {
+    opts.body = JSON.stringify(body);
+  }
+
+  const res = await fetch(url.toString(), opts);
+  const text = await res.text();
+
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw Object.assign(
+      new Error(`Limit order API returned non-JSON response (status ${res.status})`),
+      { code: 'NON_JSON_RESPONSE', status: res.status, details: text.slice(0, 200) }
+    );
+  }
+
+  if (!res.ok) {
+    const code = parsed.code || 'LIMIT_ORDER_ERROR';
+    const msg = parsed.message || `Limit order request failed with status ${res.status}`;
+    throw Object.assign(new Error(msg), { code, status: res.status, details: parsed.details });
+  }
+
+  return parsed;
+}
+
+// --- Auth endpoints (no JWT required) ---
+
+export async function getChallenge(walletPubkey) {
+  return loFetch('POST', '/auth/challenge', { body: { walletPubkey } });
+}
+
+export async function verifyChallenge(walletPubkey, signatureBase58) {
+  return loFetch('POST', '/auth/verify', { body: { walletPubkey, signature: signatureBase58 } });
+}
+
+// --- Vault endpoints ---
+
+export async function getVault(token, userPubkey) {
+  return loFetch('GET', '/vault', { token, query: { userPubkey } });
+}
+
+export async function registerVault(token) {
+  return loFetch('POST', '/vault/register', { token, body: {} });
+}
+
+// --- Order lifecycle endpoints ---
+
+export async function craftDeposit(token, { inputMint, outputMint, userAddress, amount }) {
+  return loFetch('POST', '/deposit/craft', {
+    token,
+    body: { inputMint, outputMint, userAddress, amount },
+  });
+}
+
+export async function createOrder(token, params) {
+  return loFetch('POST', '/create', { token, body: params });
+}
+
+export async function listOrders(token, userPubkey, filters = {}) {
+  return loFetch('GET', '/orders', {
+    token,
+    query: { userPubkey, ...filters },
+  });
+}
+
+export async function updateOrder(token, orderId, params) {
+  return loFetch('PATCH', `/orders/${orderId}`, { token, body: params });
+}
+
+export async function cancelOrderRequest(token, orderId) {
+  return loFetch('POST', `/cancel/${orderId}`, { token, body: {} });
+}
+
+export async function confirmCancelOrder(token, orderId, { signedTransaction, cancelRequestId }) {
+  return loFetch('POST', `/cancel/${orderId}/confirm`, {
+    token,
+    body: { signedTransaction, cancelRequestId },
+  });
+}
+
+// ============= Message Signing =============
+
+/**
+ * Sign a message with a Solana wallet.
+ * Returns raw signature bytes as a Buffer.
+ *
+ * @param {Buffer} message - Raw message bytes
+ * @param {'local'|'privy'|'walletconnect'} walletType
+ * @param {object} walletInfo - Type-specific signing info
+ * @returns {Promise<Buffer>} Raw Ed25519 signature (64 bytes)
+ */
+export async function signSolanaMessage(message, walletType, walletInfo) {
+  if (walletType === 'local') {
+    // Extract seed (first 32 bytes of the 64-byte keypair hex)
+    const seed = Buffer.from(walletInfo.privateKeyHex.slice(0, 64), 'hex');
+    return signEd25519(message, seed);
+  }
+
+  if (walletType === 'privy') {
+    const result = await walletInfo.privyClient.signSolanaMessage(
+      walletInfo.walletId,
+      message,
+    );
+    const sigBase64 = result.data?.signature || result.signature;
+    return Buffer.from(sigBase64, 'base64');
+  }
+
+  if (walletType === 'walletconnect') {
+    const result = await signSolanaMessageViaWalletConnect(message);
+    // WC returns base58-encoded signature
+    return Buffer.from(base58Decode(result.signature));
+  }
+
+  throw new Error(`Unsupported wallet type: ${walletType}`);
+}
+
+// ============= Authentication Flow =============
+
+/**
+ * Authenticate with the limit order API and return a JWT.
+ * Uses disk cache to avoid re-signing for every CLI invocation.
+ *
+ * @param {string} walletPubkey - Solana wallet address
+ * @param {'local'|'privy'|'walletconnect'} walletType
+ * @param {object} walletInfo - Signing info
+ * @param {function} log - Logger
+ * @returns {Promise<string>} JWT token
+ */
+export async function authenticate(walletPubkey, walletType, walletInfo, log = () => {}) {
+  const cached = loadCachedToken(walletPubkey);
+  if (cached) {
+    return cached;
+  }
+
+  log('  Authenticating with limit order API...');
+  const { challenge } = await getChallenge(walletPubkey);
+  const messageBuffer = Buffer.from(challenge, 'utf8');
+
+  log('  Signing challenge...');
+  const signatureBytes = await signSolanaMessage(messageBuffer, walletType, walletInfo);
+  const signatureBase58 = base58Encode(signatureBytes);
+
+  const { token } = await verifyChallenge(walletPubkey, signatureBase58);
+  saveCachedToken(walletPubkey, token);
+
+  return token;
+}
+
+// ============= Wallet Resolution =============
+
+/**
+ * Resolve a Solana wallet for limit orders.
+ * Follows the same 3-way dispatch as trading.js: WalletConnect / named / default.
+ *
+ * @returns {{ pubkey, walletType, walletInfo, privyWalletIds }}
+ */
+export async function resolveSolanaWallet(walletName, deps = {}) {
+  const { log = console.log, exit = process.exit } = deps;
+
+  const isWalletConnect = walletName === 'walletconnect' || walletName === 'wc';
+
+  if (isWalletConnect) {
+    const address = await getWalletConnectAddress('solana');
+    if (!address) {
+      log('No WalletConnect session active. Run: walletconnect connect');
+      exit(1);
+      return null;
+    }
+    return { pubkey: address, walletType: 'walletconnect', walletInfo: {}, privyWalletIds: null };
+  }
+
+  let wallet;
+  if (walletName) {
+    wallet = showWallet(walletName);
+  } else {
+    try {
+      const config = getWalletConfig();
+      if (config.defaultWallet) {
+        wallet = showWallet(config.defaultWallet);
+      }
+    } catch {
+      // No wallet configured
+    }
+  }
+
+  if (!wallet || !wallet.solana) {
+    log('No Solana wallet found. Create one with: nansen wallet create');
+    exit(1);
+    return null;
+  }
+
+  if (wallet.provider === 'privy') {
+    const { PrivyClient } = await import('./privy.js');
+    const privyClient = new PrivyClient(process.env.PRIVY_APP_ID, process.env.PRIVY_APP_SECRET);
+    return {
+      pubkey: wallet.solana,
+      walletType: 'privy',
+      walletInfo: { privyClient, walletId: wallet.privyWalletIds?.solana },
+      privyWalletIds: wallet.privyWalletIds,
+    };
+  }
+
+  // Local wallet — need password for signing
+  return {
+    pubkey: wallet.solana,
+    walletType: 'local',
+    walletInfo: {}, // privateKeyHex populated lazily when signing is needed
+    walletName: wallet.name,
+    privyWalletIds: null,
+  };
+}
+
+/**
+ * Get the private key hex for a local wallet, prompting for password if needed.
+ */
+function getLocalWalletPrivateKey(walletName) {
+  const config = getWalletConfig();
+  let password = null;
+  if (config.passwordHash) {
+    const result = retrievePassword();
+    password = result.password;
+    if (!password) {
+      throw new Error('Wallet is encrypted and no password was found. Set NANSEN_WALLET_PASSWORD env var.');
+    }
+  }
+  const effectiveName = walletName || config.defaultWallet;
+  const exported = exportWallet(effectiveName, password);
+  return exported.solana.privateKey;
+}
+
+// ============= Transaction Signing =============
+
+/**
+ * Sign a Solana transaction (base64) using the appropriate wallet type.
+ * Returns base64-encoded signed transaction.
+ */
+export async function signTransaction(txBase64, walletType, walletInfo) {
+  if (walletType === 'local') {
+    return signSolanaTransaction(txBase64, walletInfo.privateKeyHex);
+  }
+
+  if (walletType === 'privy') {
+    const result = await walletInfo.privyClient.signSolanaTransaction(
+      walletInfo.walletId,
+      txBase64,
+    );
+    return result.data?.signed_transaction || result.signed_transaction;
+  }
+
+  if (walletType === 'walletconnect') {
+    // WC expects base58 for Solana transactions
+    const txBytes = Buffer.from(txBase64, 'base64');
+    const txBase58 = base58Encode(txBytes);
+    const result = await sendSolanaTransactionViaWalletConnect(txBase58);
+    if (result.signedTransaction) {
+      // WC returns base58; convert to base64
+      const signedBytes = base58Decode(result.signedTransaction);
+      return Buffer.from(signedBytes).toString('base64');
+    }
+    throw new Error('WalletConnect did not return a signed transaction');
+  }
+
+  throw new Error(`Unsupported wallet type: ${walletType}`);
+}
+
+// ============= Expiry Parsing =============
+
+/**
+ * Parse an expiry duration string to epoch milliseconds.
+ * Accepts: "24h", "7d", "30d", or raw epoch ms string.
+ * Returns null for no expiry.
+ */
+export function parseExpiry(expiryStr) {
+  if (!expiryStr || expiryStr === 'never') return null;
+
+  const match = expiryStr.match(/^(\d+)(h|d)$/i);
+  if (match) {
+    const value = parseInt(match[1], 10);
+    const unit = match[2].toLowerCase();
+    const ms = unit === 'h' ? value * 3600 * 1000 : value * 24 * 3600 * 1000;
+    return Date.now() + ms;
+  }
+
+  // Try as raw epoch ms
+  const num = Number(expiryStr);
+  if (!isNaN(num) && num > Date.now() - 86400000) {
+    return num;
+  }
+
+  throw new Error(`Invalid expiry format: "${expiryStr}". Use "24h", "7d", "30d", or epoch ms.`);
+}
+
+// ============= Order Formatting =============
+
+function formatOrderStatus(status) {
+  const map = {
+    pending: 'Pending',
+    open: 'Open',
+    executing: 'Executing',
+    filled: 'Filled',
+    pending_withdraw: 'Withdrawing',
+    cancelled: 'Cancelled',
+    expired: 'Expired',
+    failed: 'Failed',
+  };
+  return map[status] || status;
+}
+
+// Reverse lookup: address → { symbol, decimals } for known Solana tokens
+const KNOWN_SOLANA_TOKENS = {
+  'So11111111111111111111111111111111111111112': { symbol: 'SOL', decimals: 9 },
+  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v': { symbol: 'USDC', decimals: 6 },
+  'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB': { symbol: 'USDT', decimals: 6 },
+};
+
+function tokenLabel(address) {
+  if (!address) return '?';
+  const info = KNOWN_SOLANA_TOKENS[address];
+  return info ? `${info.symbol} (${address})` : address;
+}
+
+/**
+ * Format a base-unit amount to human-readable (e.g. 116000000 SOL → "0.116 SOL").
+ * Falls back to raw amount for unknown tokens.
+ */
+function formatAmount(amount, mintAddress) {
+  if (!amount) return '?';
+  const info = KNOWN_SOLANA_TOKENS[mintAddress];
+  if (!info) return `${amount} ${mintAddress || '?'}`;
+  const raw = BigInt(amount);
+  const divisor = BigInt(10 ** info.decimals);
+  const whole = raw / divisor;
+  const frac = raw % divisor;
+  const fracStr = frac.toString().padStart(info.decimals, '0').replace(/0+$/, '');
+  const humanAmount = fracStr ? `${whole}.${fracStr}` : `${whole}`;
+  return `${humanAmount} ${info.symbol} (${amount} base units)`;
+}
+
+function formatTimestamp(ts) {
+  if (!ts) return '?';
+  const num = Number(ts);
+  if (isNaN(num)) return ts;
+  const date = new Date(num);
+  return `${date.toLocaleString()} (${date.toISOString()})`;
+}
+
+function formatOrder(order, index) {
+  const lines = [];
+  const label = index !== undefined ? `  Order #${index + 1}` : '  Order';
+  lines.push(`${label} (${order.id})`);
+  lines.push(`    Status:          ${formatOrderStatus(order.status)}`);
+  lines.push(`    Sell:            ${formatAmount(order.inputAmount, order.inputMint)}`);
+  lines.push(`    Buy:             ${tokenLabel(order.outputMint)}`);
+  lines.push(`    Trigger:         ${order.triggerCondition} $${order.triggerPriceUsd} on ${tokenLabel(order.triggerMint)}`);
+  lines.push(`    Slippage:        ${order.slippageBps != null ? `${order.slippageBps} bps` : 'auto'}`);
+  lines.push(`    Created:         ${formatTimestamp(order.createdAt)}`);
+  if (order.expiresAt) lines.push(`    Expires:         ${formatTimestamp(order.expiresAt)}`);
+  if (order.fills?.length > 0) {
+    lines.push(`    Fills:           ${order.fills.length}`);
+    for (const fill of order.fills) {
+      lines.push(`      ${fill.inputAmount} → ${fill.outputAmount} (${fill.txSignature?.slice(0, 12)}...)`);
+    }
+  }
+  return lines.join('\n');
+}
+
+// ============= CLI Command Builder =============
+
+/**
+ * Build limit order command handlers for CLI integration.
+ */
+export function buildLimitOrderCommands(deps = {}) {
+  const { log = console.log, exit = process.exit } = deps;
+
+  return {
+    'create': async (args, apiInstance, flags, options) => {
+      const fromRaw = options.from || options['from-token'] || args[0];
+      const toRaw = options.to || options['to-token'] || args[1];
+      const from = resolveTokenAddress(fromRaw, 'solana');
+      const to = resolveTokenAddress(toRaw, 'solana');
+      const amount = options.amount || args[2];
+      const triggerPrice = options['trigger-price'];
+      const triggerCondition = options['trigger-condition'];
+      const triggerMintRaw = options['trigger-mint'];
+      const slippageBps = options['slippage-bps'] != null ? Number(options['slippage-bps']) : undefined;
+      const expiresStr = options.expires || '30d';
+      const walletName = options.wallet;
+
+      if (!from || !to || !amount || triggerPrice == null || !triggerMintRaw || !triggerCondition) {
+        log(`
+Usage: nansen trade limit-order create --from <token> --to <token> --amount <amount> --trigger-mint <token> --trigger-condition <above|below> --trigger-price <usd>
+
+OPTIONS:
+  --from <symbol|address>        Token to sell (symbol like SOL, USDC or address)
+  --to <symbol|address>          Token to buy (symbol like USDC, SOL or address)
+  --amount <amount>              Amount to sell in token units (e.g. 1.5 for 1.5 SOL, 80 for 80 USDC)
+  --trigger-mint <symbol|addr>   Token whose price triggers the order (e.g. SOL)
+  --trigger-condition <cond>     "above" or "below"
+  --trigger-price <usd>          Trigger price in USD (must be a positive number)
+  --slippage-bps <bps>               Slippage in basis points (100 = 1%), omit for auto
+  --expires <duration>           Expiry duration: "24h", "7d", "30d" (default: 30d)
+  --wallet <name>                Wallet name (or "walletconnect"/"wc")
+
+EXAMPLES:
+  # Sell 1 SOL for USDC when SOL drops below $80
+  nansen trade limit-order create --from SOL --to USDC --amount 1 --trigger-mint SOL --trigger-condition below --trigger-price 80
+  # Buy SOL with 80 USDC when SOL goes above $100
+  nansen trade limit-order create --from USDC --to SOL --amount 80 --trigger-mint SOL --trigger-condition above --trigger-price 100`);
+        exit(1);
+        return;
+      }
+
+      // Validate token addresses are valid Solana addresses (catches EVM addresses, typos, etc.)
+      const fromValidation = validateTokenAddress(from, 'solana');
+      if (!fromValidation.valid) {
+        log(`Error: Invalid --from token address: ${fromValidation.error}`);
+        exit(1);
+        return;
+      }
+      const toValidation = validateTokenAddress(to, 'solana');
+      if (!toValidation.valid) {
+        log(`Error: Invalid --to token address: ${toValidation.error}`);
+        exit(1);
+        return;
+      }
+
+      // Amount is always in human-readable token units (e.g. 1.5 = 1.5 SOL)
+      // Converted to base units (lamports) internally
+      let amountBaseUnits;
+      try {
+        const num = Number(amount);
+        if (isNaN(num) || num <= 0) {
+          log('Error: --amount must be a positive number in token units (e.g. 1.5 for 1.5 SOL, 80 for 80 USDC).');
+          exit(1);
+          return;
+        }
+        const fromInfo = KNOWN_SOLANA_TOKENS[from];
+        let decimals;
+        if (fromInfo) {
+          decimals = fromInfo.decimals;
+        } else {
+          const tokenInfo = await getTokenInfo(CHAIN_RPCS.solana, from);
+          decimals = tokenInfo.decimals;
+        }
+        amountBaseUnits = String(parseAmount(String(amount), decimals));
+      } catch (err) {
+        log(`Error: Could not resolve decimals for ${from}: ${err.message}`);
+        exit(1);
+        return;
+      }
+
+      const price = Number(triggerPrice);
+      if (isNaN(price) || price <= 0) {
+        log('Error: --trigger-price must be a positive number (USD price).');
+        exit(1);
+        return;
+      }
+
+      if (triggerCondition !== 'above' && triggerCondition !== 'below') {
+        log('Error: --trigger-condition must be "above" or "below".');
+        exit(1);
+        return;
+      }
+
+      let expiresAt;
+      try {
+        expiresAt = parseExpiry(expiresStr);
+      } catch (err) {
+        log(`Error: ${err.message}`);
+        exit(1);
+        return;
+      }
+
+      const triggerMint = resolveTokenAddress(triggerMintRaw, 'solana');
+
+      const tmValidation = validateTokenAddress(triggerMint, 'solana');
+      if (!tmValidation.valid) {
+        log(`Error: Invalid --trigger-mint address: ${tmValidation.error}`);
+        exit(1);
+        return;
+      }
+
+      try {
+        // 1. Resolve wallet
+        const resolved = await resolveSolanaWallet(walletName, deps);
+        if (!resolved) return;
+
+        let { pubkey, walletType, walletInfo } = resolved;
+
+        // For local wallets, load private key now
+        if (walletType === 'local') {
+          const privateKeyHex = getLocalWalletPrivateKey(resolved.walletName);
+          walletInfo = { privateKeyHex };
+        }
+
+        log(`\nCreating limit order on Solana...`);
+        log(`  Wallet: ${pubkey}`);
+        log(`  Sell: ${formatAmount(amountBaseUnits, from)}`);
+        log(`  Buy: ${to}`);
+        log(`  Trigger: $${price} (${triggerCondition})`);
+
+        // 2. Authenticate
+        const token = await authenticate(pubkey, walletType, walletInfo, log);
+
+        // 3. Check vault, auto-register if needed
+        // Backend returns { vaultPubkey: "..." } when vault exists, or throws/returns empty when not
+        let hasVault = false;
+        try {
+          const vaultInfo = await getVault(token, pubkey);
+          hasVault = !!(vaultInfo?.vaultPubkey || vaultInfo?.vaultAddress);
+        } catch {
+          // No vault found
+        }
+        if (!hasVault) {
+          log('  Registering vault for first-time use...');
+          try {
+            await registerVault(token);
+          } catch (regErr) {
+            // Vault may already exist — ignore "already registered" errors
+            if (!/already registered/i.test(regErr.message)) throw regErr;
+          }
+        }
+
+        // 4. Craft deposit transaction
+        log('  Crafting deposit transaction...');
+        const deposit = await craftDeposit(token, {
+          inputMint: from,
+          outputMint: to,
+          userAddress: pubkey,
+          amount: amountBaseUnits,
+        });
+
+        // 5. Sign deposit transaction
+        log('  Signing deposit transaction...');
+        const signedDepositTx = await signTransaction(deposit.transaction, walletType, walletInfo);
+
+        // 6. Create order
+        log('  Submitting order...');
+        const orderParams = {
+          orderType: 'single',
+          depositRequestId: deposit.requestId,
+          depositSignedTx: signedDepositTx,
+          userPubkey: pubkey,
+          inputMint: from,
+          inputAmount: amountBaseUnits,
+          outputMint: to,
+          triggerMint,
+          triggerCondition,
+          triggerPriceUsd: price, // Must be Number, not string
+          ...(slippageBps != null ? { slippageBps } : {}),
+          ...(expiresAt != null ? { expiresAt } : {}),
+        };
+
+        const result = await createOrder(token, orderParams);
+
+        log(`\n  ✓ Limit order created`);
+        log(`    Order ID:     ${result.id}`);
+        log(`    Tx:           ${result.txSignature}`);
+        log(`    Explorer:     ${SOLSCAN_TX_URL}${result.txSignature}`);
+        log('');
+
+      } catch (err) {
+        log(`Error: ${err.message}`);
+        if (err.details) log(`  Details: ${JSON.stringify(err.details)}`);
+        if (err.cause) log(`  Cause: ${err.cause.message || err.cause}`);
+        exit(1);
+      }
+    },
+
+    'list': async (args, apiInstance, flags, options) => {
+      const walletName = options.wallet;
+      const state = options.state;
+      const mint = options.mint ? resolveTokenAddress(options.mint, 'solana') : undefined;
+      const limit = options.limit || 20;
+      const offset = options.offset || 0;
+      const sort = options.sort;
+      const dir = options.dir || 'desc';
+
+      if (mint) {
+        const mintValidation = validateTokenAddress(mint, 'solana');
+        if (!mintValidation.valid) {
+          log(`Error: Invalid --mint address: ${mintValidation.error}`);
+          exit(1);
+          return;
+        }
+      }
+
+      try {
+        const resolved = await resolveSolanaWallet(walletName, deps);
+        if (!resolved) return;
+
+        let { pubkey, walletType, walletInfo } = resolved;
+
+        // For local wallets, load private key for auth
+        if (walletType === 'local') {
+          const privateKeyHex = getLocalWalletPrivateKey(resolved.walletName);
+          walletInfo = { privateKeyHex };
+        }
+
+        const token = await authenticate(pubkey, walletType, walletInfo, log);
+
+        const result = await listOrders(token, pubkey, { state, mint, limit, offset, sort, dir });
+        const orders = result.orders || [];
+
+        if (orders.length === 0) {
+          log('\nNo limit orders found.');
+          if (state) log(`  (filtered by state: ${state})`);
+          log('');
+          return;
+        }
+
+        log(`\nLimit Orders (${result.pagination?.total || orders.length} total):\n`);
+        orders.forEach((order, i) => {
+          if (i > 0) log('');
+          log(formatOrder(order, i));
+        });
+        if (result.pagination && result.pagination.total > offset + orders.length) {
+          log(`\n  Showing ${offset + 1}-${offset + orders.length} of ${result.pagination.total}. Use --offset ${offset + orders.length} to see more.`);
+        }
+        log('');
+
+      } catch (err) {
+        log(`Error: ${err.message}`);
+        if (err.details) log(`  Details: ${JSON.stringify(err.details)}`);
+        exit(1);
+      }
+    },
+
+    'cancel': async (args, apiInstance, flags, options) => {
+      const orderId = options.order || options['order-id'] || args[0];
+      const walletName = options.wallet;
+
+      if (!orderId) {
+        log(`
+Usage: nansen trade limit-order cancel --order <orderId>
+
+OPTIONS:
+  --order <id>        Order ID to cancel
+  --wallet <name>     Wallet name (or "walletconnect"/"wc")
+
+EXAMPLES:
+  nansen trade limit-order cancel --order abc123`);
+        exit(1);
+        return;
+      }
+
+      try {
+        const resolved = await resolveSolanaWallet(walletName, deps);
+        if (!resolved) return;
+
+        let { pubkey, walletType, walletInfo } = resolved;
+
+        if (walletType === 'local') {
+          const privateKeyHex = getLocalWalletPrivateKey(resolved.walletName);
+          walletInfo = { privateKeyHex };
+        }
+
+        log(`\nCancelling order ${orderId}...`);
+
+        // 1. Authenticate
+        const token = await authenticate(pubkey, walletType, walletInfo, log);
+
+        // 2. Request cancellation — get unsigned withdrawal tx
+        log('  Requesting cancellation...');
+        const cancelResult = await cancelOrderRequest(token, orderId);
+
+        // 3. Sign the withdrawal transaction
+        log('  Signing withdrawal transaction...');
+        const signedTx = await signTransaction(cancelResult.transaction, walletType, walletInfo);
+
+        // 4. Confirm cancellation
+        log('  Confirming cancellation...');
+        const confirmed = await confirmCancelOrder(token, orderId, {
+          signedTransaction: signedTx,
+          cancelRequestId: cancelResult.requestId,
+        });
+
+        log(`\n  ✓ Order cancelled`);
+        log(`    Order ID:     ${confirmed.id}`);
+        log(`    Tx:           ${confirmed.txSignature}`);
+        log(`    Explorer:     ${SOLSCAN_TX_URL}${confirmed.txSignature}`);
+        log('');
+
+      } catch (err) {
+        log(`Error: ${err.message}`);
+        if (err.details) log(`  Details: ${JSON.stringify(err.details)}`);
+        exit(1);
+      }
+    },
+
+    'update': async (args, apiInstance, flags, options) => {
+      const orderId = options.order || options['order-id'] || args[0];
+      const triggerPrice = options['trigger-price'];
+      const slippageBps = options['slippage-bps'];
+      const walletName = options.wallet;
+
+      if (!orderId) {
+        log(`
+Usage: nansen trade limit-order update --order <orderId> [--trigger-price <usd>] [--slippage-bps <bps>]
+
+OPTIONS:
+  --order <id>            Order ID to update
+  --trigger-price <usd>   New trigger price in USD
+  --slippage-bps <bps>    Slippage in basis points (100 = 1%)
+  --wallet <name>         Wallet name (or "walletconnect"/"wc")
+
+NOTE: Only provided fields are updated. Auto slippage can only be set at creation time
+      (by omitting --slippage-bps from the create command).
+
+EXAMPLES:
+  nansen trade limit-order update --order abc123 --trigger-price 85
+  nansen trade limit-order update --order abc123 --slippage-bps 100`);
+        exit(1);
+        return;
+      }
+
+      if (triggerPrice == null && slippageBps == null) {
+        log('Error: Provide at least one of --trigger-price or --slippage-bps to update.');
+        exit(1);
+        return;
+      }
+
+      const updateBody = { orderType: 'single' };
+      if (triggerPrice != null) {
+        const price = Number(triggerPrice);
+        if (isNaN(price) || price <= 0) {
+          log('Error: --trigger-price must be a positive number.');
+          exit(1);
+          return;
+        }
+        updateBody.triggerPriceUsd = price;
+      }
+      if (slippageBps != null) {
+        const bps = Number(slippageBps);
+        if (isNaN(bps) || bps < 0 || bps > 10000) {
+          log('Error: --slippage-bps must be between 0 and 10000 basis points.');
+          exit(1);
+          return;
+        }
+        updateBody.slippageBps = bps;
+      }
+
+      try {
+        const resolved = await resolveSolanaWallet(walletName, deps);
+        if (!resolved) return;
+
+        let { pubkey, walletType, walletInfo } = resolved;
+
+        if (walletType === 'local') {
+          const privateKeyHex = getLocalWalletPrivateKey(resolved.walletName);
+          walletInfo = { privateKeyHex };
+        }
+
+        log(`\nUpdating order ${orderId}...`);
+
+        const token = await authenticate(pubkey, walletType, walletInfo, log);
+        await updateOrder(token, orderId, updateBody);
+
+        log(`\n  ✓ Order updated`);
+        if (updateBody.triggerPriceUsd != null) log(`    Trigger price: $${updateBody.triggerPriceUsd}`);
+        if (updateBody.slippageBps != null) log(`    Slippage:      ${updateBody.slippageBps} bps`);
+        log('');
+
+      } catch (err) {
+        log(`Error: ${err.message}`);
+        if (err.details) log(`  Details: ${JSON.stringify(err.details)}`);
+        exit(1);
+      }
+    },
+  };
+}

package/src/privy.js

@@ -125,6 +125,15 @@ export class PrivyClient {
     });
   }
 
+  async signSolanaMessage(walletId, messageBuffer) {
+    const messageBase64 = Buffer.from(messageBuffer).toString('base64');
+    return this._request("POST", `/wallets/${walletId}/rpc`, {
+      method: "signMessage",
+      chain_type: "solana",
+      params: { message: messageBase64, encoding: "base64" },
+    });
+  }
+
 }
 
 // ============= Helpers =============

package/src/schema.json

@@ -500,6 +500,19 @@
                   "default": true
                 }
               }
+            },
+            "top-tokens": {
+              "endpoint": "/api/v1/nansen-score/top-tokens",
+              "description": "Top tokens ranked by Nansen Score (public endpoint, any authenticated API key)",
+              "options": {
+                "market-cap": {
+                  "description": "Filter by market cap group",
+                  "enum": ["lowcap", "midcap", "largecap"]
+                },
+                "limit": {
+                  "default": 25
+                }
+              }
             }
           },
           "description": "Token God Mode - deep analytics for any token"
@@ -906,6 +919,138 @@
               "description": "Destination chain (solana or base)"
             }
           }
+        },
+        "limit-order": {
+          "description": "Limit order management (Solana only)",
+          "subcommands": {
+            "create": {
+              "description": "Place a new limit order",
+              "options": {
+                "from": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Token to sell (address or symbol)"
+                },
+                "to": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Token to buy (address or symbol)"
+                },
+                "amount": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Amount in base units (e.g. lamports)"
+                },
+                "trigger-price": {
+                  "type": "number",
+                  "required": true,
+                  "description": "Trigger price in USD"
+                },
+                "trigger-condition": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Trigger when price is 'above' or 'below' target"
+                },
+                "trigger-mint": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Token whose price triggers the order (e.g. SOL)"
+                },
+                "slippage-bps": {
+                  "type": "number",
+                  "description": "Slippage tolerance in basis points (e.g. 50 = 0.5%)"
+                },
+                "expires": {
+                  "type": "string",
+                  "default": "30d",
+                  "description": "Expiry duration (e.g. 24h, 7d, 30d) or epoch ms"
+                },
+                "wallet": {
+                  "type": "string",
+                  "description": "Wallet name (or \"walletconnect\"/\"wc\")"
+                }
+              },
+              "chains": ["solana"],
+              "prerequisites": [
+                "A Solana wallet must be configured. Run: nansen wallet create"
+              ]
+            },
+            "list": {
+              "description": "List your limit orders",
+              "options": {
+                "state": {
+                  "type": "string",
+                  "description": "Filter by state (active, past)"
+                },
+                "mint": {
+                  "type": "string",
+                  "description": "Filter by token mint address"
+                },
+                "limit": {
+                  "type": "number",
+                  "default": 20,
+                  "description": "Max results per page"
+                },
+                "offset": {
+                  "type": "number",
+                  "default": 0,
+                  "description": "Pagination offset"
+                },
+                "sort": {
+                  "type": "string",
+                  "description": "Sort field"
+                },
+                "dir": {
+                  "type": "string",
+                  "default": "desc",
+                  "description": "Sort direction (asc or desc)"
+                },
+                "wallet": {
+                  "type": "string",
+                  "description": "Wallet name (or \"walletconnect\"/\"wc\")"
+                }
+              },
+              "chains": ["solana"]
+            },
+            "cancel": {
+              "description": "Cancel an open limit order",
+              "options": {
+                "order": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Order ID to cancel"
+                },
+                "wallet": {
+                  "type": "string",
+                  "description": "Wallet name (or \"walletconnect\"/\"wc\")"
+                }
+              },
+              "chains": ["solana"]
+            },
+            "update": {
+              "description": "Update trigger price or slippage on an existing order",
+              "options": {
+                "order": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Order ID to update"
+                },
+                "trigger-price": {
+                  "type": "number",
+                  "description": "New trigger price in USD"
+                },
+                "slippage-bps": {
+                  "type": "number",
+                  "description": "New slippage in basis points (0-10000)"
+                },
+                "wallet": {
+                  "type": "string",
+                  "description": "Wallet name (or \"walletconnect\"/\"wc\")"
+                }
+              },
+              "chains": ["solana"]
+            }
+          }
         }
       }
     },

package/src/telemetry.js

@@ -158,9 +158,13 @@ function buildContext() {
 
 /**
  * Convert a command string like "smart-money netflow" to a path like "/smart-money/netflow".
+ * Agent ("agent …") always maps to "/agent" so prompts are not exploded into path segments.
  */
 function commandToPath(command) {
-  return '/' + command.replace(/\s+/g, '/');
+  if (typeof command === 'string' && /^agent(?:\s+|$)/.test(command.trimStart())) {
+    return '/agent';
+  }
+  return '/' + String(command).replace(/\s+/g, '/');
 }
 
 /**

package/src/transfer.js

@@ -302,7 +302,7 @@ function modPowBig(base, exp, mod) {
   return result;
 }
 
-async function getTokenInfo(rpcUrl, mint) {
+export async function getTokenInfo(rpcUrl, mint) {
   // Get mint account to determine token program and decimals
   const info = await rpcCall(rpcUrl, 'getAccountInfo', [mint, { encoding: 'jsonParsed' }]);
   if (!info || !info.value) throw new Error(`Token mint ${mint} not found`);

package/src/walletconnect-trading.js

@@ -9,6 +9,7 @@
  */
 
 import { wcExec } from './walletconnect-exec.js';
+import { base58Encode } from './wallet.js';
 
 const SOLANA_MAINNET_CHAIN = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
 
@@ -153,3 +154,27 @@ export async function sendSolanaTransactionViaWalletConnect(txBase58, timeoutMs
 
   throw new Error('Unexpected response from walletconnect Solana sign');
 }
+
+/**
+ * Sign a Solana message via WalletConnect.
+ *
+ * Used for challenge-response authentication (e.g., Jupiter Limit Order V2).
+ * Returns the raw Ed25519 signature as base58.
+ *
+ * @param {Buffer} messageBuffer - Raw message bytes to sign
+ * @param {number} [timeoutMs=120000] - Timeout for user approval
+ * @returns {{ signature: string }} Base58-encoded signature
+ */
+export async function signSolanaMessageViaWalletConnect(messageBuffer, timeoutMs = 120000) {
+  const payload = {
+    message: base58Encode(messageBuffer),
+    chainId: SOLANA_MAINNET_CHAIN,
+  };
+
+  const output = await wcExec('walletconnect', ['sign-message', JSON.stringify(payload)], timeoutMs);
+  const result = parseWcJson(output);
+
+  if (result.signature) return { signature: result.signature };
+
+  throw new Error('Unexpected response from walletconnect sign-message');
+}