nansen-cli 1.36.2 → 1.38.0

package/src/perp.js

@@ -22,6 +22,7 @@ import {
   userSignedEip712,
 } from './hl-action.js';
 import { submitExchange } from './hl-client.js';
+import { trackPerpOrderCompleted } from './telemetry.js';
 import { resolveEvmWallet, resolvePrivateKey } from './wallet-signing.js';
 import { hashTypedData } from './x402-evm.js';
 
@@ -241,8 +242,66 @@ async function signHlAction(eip712, { privateKeyHex, privyClient, privyWalletId,
 // { action, nonce, eip712, size?, price? } from an hl-action.js builder; the
 // vault is always null for a normal wallet (the CLI signs L1 actions with the
 // wallet key directly). submitExchange throws on any HL rejection.
+// Parse the per-order statuses HL returns for an `order` action so the oid and
+// fill are surfaced — the perp analogue of spot printing its quote id. HL replies:
+//   response.data.statuses[] = { resting:{oid} } | { filled:{oid,totalSz,avgPx} } | { error }
+// A rejected leg ({error}) has already thrown in submitExchange, so only
+// resting/filled legs reach here. A TP/SL bracket returns multiple legs; label
+// them the same way extractActionErrors does (parent / take-profit / stop-loss).
+// Gated on the SUBMITTED action being an order: leverage/transfer/builder-fee
+// actions (type "default") and cancels return no oids, so [] falls back to the
+// concise raw response line in buildScreenSignSubmit.
+export function summarizeOrderResult(result, action) {
+  if (action?.type !== 'order') return [];
+  const statuses = result?.response?.data?.statuses;
+  if (!Array.isArray(statuses)) return [];
+  const multiLeg = (action.orders?.length ?? 0) > 1;
+  const out = [];
+  for (const [index, entry] of statuses.entries()) {
+    if (!entry || typeof entry !== 'object') continue;
+    const tpsl = action.orders?.[index]?.t?.trigger?.tpsl;
+    const leg = tpsl === 'tp'
+      ? 'take-profit'
+      : tpsl === 'sl'
+        ? 'stop-loss'
+        : action.grouping === 'normalTpsl' && index === 0
+          ? 'parent'
+          : multiLeg
+            ? `leg ${index + 1}`
+            : 'parent';
+    // HL oids are uint64; JSON.parse already narrowed them to Number, so any id
+    // above 2^53 arrived rounded. Flag precision (oidSafe) so the caller can
+    // withhold a copy-paste cancel — and BI can drop the id — rather than act on
+    // a wrong oid presented as authoritative.
+    if (entry.filled && entry.filled.oid !== undefined) {
+      const { oid, totalSz, avgPx } = entry.filled;
+      out.push({ leg, kind: 'filled', oid, oidSafe: Number.isSafeInteger(oid), totalSz, avgPx });
+    } else if (entry.resting && entry.resting.oid !== undefined) {
+      const { oid } = entry.resting;
+      out.push({ leg, kind: 'resting', oid, oidSafe: Number.isSafeInteger(oid) });
+    }
+  }
+  return out;
+}
+
+// Fire the perp_order_completed event via the injected tracker. Deliberately
+// minimal (privacy): only the trade side and the parent Hyperliquid order id —
+// no asset, price, size, or fill detail. The order-placement response carries no
+// trade/fill id (that exists only once the order fills, via the fills feed), so
+// side + oid is the reliable maximum here. The oid is omitted when it arrived
+// rounded past 2^53 (oidSafe false) so BI never records a wrong id. `summary` is
+// summarizeOrderResult's output; its parent leg carries the order id.
+function emitPerpOrderCompleted(telemetry, summary) {
+  const parent = summary.find((o) => o.leg === 'parent') ?? summary[0];
+  return telemetry.track({
+    command: telemetry.command,
+    side: telemetry.side,
+    oid: parent && parent.oidSafe ? parent.oid : undefined,
+  });
+}
+
 async function buildScreenSignSubmit(apiInstance, prepared, ctx) {
-  const { action, nonce, eip712, size, price } = prepared;
+  const { action, nonce, eip712, size, price, coin, telemetry } = prepared;
   const { walletAddress, log } = ctx;
 
   log('  Screening...');
@@ -262,10 +321,44 @@ async function buildScreenSignSubmit(apiInstance, prepared, ctx) {
 
   const status = result.status ?? 'ok';
   log(`  Status: ${status}`);
-  if (result.response) {
+
+  // Surface the order id(s) HL returned so the caller can track/cancel the
+  // order — mirrors how spot prints its quote id plus a ready-to-run follow-up.
+  const orders = summarizeOrderResult(result, action);
+  if (orders.length) {
+    for (const o of orders) {
+      const tag = o.leg === 'parent' ? '' : ` [${o.leg}]`;
+      // Withhold the exact id (and the copy-paste cancel) when it arrived rounded
+      // past 2^53 — a wrong oid presented as actionable is worse than none.
+      const oidText = o.oidSafe ? `oid ${o.oid}` : 'oid too large to display precisely';
+      if (o.kind === 'filled') {
+        log(`  Filled${tag}: ${o.totalSz} @ ${o.avgPx}  (${oidText})`);
+      } else {
+        log(`  Resting order${tag}: ${oidText}`);
+        if (coin && o.oidSafe) log(`  Cancel:  nansen perp cancel --coin ${coin} --oid ${o.oid}`);
+      }
+    }
+  } else if (result.response) {
+    // Non-order actions (leverage, transfer, builder-fee approval) or a response
+    // shape without statuses: keep the concise raw line.
     const resp = typeof result.response === 'string' ? result.response : JSON.stringify(result.response);
     log(`  Response: ${resp}`);
   }
+
+  // Emit the order OUTCOME to BI (oid, fill status/price/size, TP/SL legs) — the
+  // perp analogue of the command-level telemetry, which fires too early (before
+  // this HL response) to observe any of it. Order/close only: cancel / leverage
+  // / transfer / builder-fee actions carry no `telemetry` and also summarize to
+  // []. Guarded + swallowed so a telemetry failure can never downgrade a
+  // completed order into a cli_command_failed.
+  if (telemetry && orders.length) {
+    try {
+      await emitPerpOrderCompleted(telemetry, orders);
+    } catch {
+      // Best-effort; never surface a tracking error after a real fill.
+    }
+  }
+
   return result;
 }
 
@@ -468,7 +561,11 @@ function resolveCoin(options) {
 // ── Command builder ──────────────────────────────────────────────────
 
 export function buildPerpCommands(deps = {}) {
-  const { log = console.log, warn = (m) => process.stderr.write(`${m}\n`) } = deps;
+  const {
+    log = console.log,
+    warn = (m) => process.stderr.write(`${m}\n`),
+    track = trackPerpOrderCompleted,
+  } = deps;
 
   return {
     'order': async (args, apiInstance, flags, options) => {
@@ -542,7 +639,23 @@ OPTIONS:
       const nonce = hlNonce();
       const eip712 = l1Eip712(action, null, nonce);
 
-      await buildScreenSignSubmit(apiInstance, { action, nonce, eip712, size: effSize, price: effPrice }, ctx);
+      await buildScreenSignSubmit(
+        apiInstance,
+        {
+          action,
+          nonce,
+          eip712,
+          size: effSize,
+          price: effPrice,
+          coin,
+          telemetry: {
+            command: 'order',
+            side: isBuy ? 'buy' : 'sell',
+            track,
+          },
+        },
+        ctx,
+      );
       log('');
       return undefined;
     },
@@ -639,7 +752,23 @@ OPTIONS:
       const nonce = hlNonce();
       const eip712 = l1Eip712(action, null, nonce);
 
-      await buildScreenSignSubmit(apiInstance, { action, nonce, eip712, size: effSize, price: effPrice }, ctx);
+      await buildScreenSignSubmit(
+        apiInstance,
+        {
+          action,
+          nonce,
+          eip712,
+          size: effSize,
+          price: effPrice,
+          coin,
+          telemetry: {
+            command: 'close',
+            side: isBuy ? 'buy' : 'sell',
+            track,
+          },
+        },
+        ctx,
+      );
       log('');
       return undefined;
     },

package/src/schema.json

@@ -564,6 +564,15 @@
                 }
               }
             },
+            "first-funder": {
+              "endpoint": "/api/v1/profiler/address/first-funder",
+              "description": "Find the first wallet that funded an EVM address",
+              "options": {
+                "address": {
+                  "required": true
+                }
+              }
+            },
             "pnl": {
               "endpoint": "/api/v1/profiler/address/pnl",
               "description": "PnL and trade performance",
@@ -1557,6 +1566,27 @@
             "aggregator": {
               "type": "string",
               "description": "Force a specific aggregator: lifi, relay, jupiter, or okx. Filters the returned quote list client-side; errors if no quote from that aggregator was returned."
+            },
+            "swap-mode": {
+              "type": "string",
+              "default": "exactIn",
+              "description": "\"exactIn\" (default) to spend exactly --amount of the sell token, or \"exactOut\" to receive exactly --amount of the buy token. Not supported together with --amount-unit percent."
+            },
+            "slippage": {
+              "type": "string",
+              "description": "Slippage tolerance as a decimal between 0 and 1 (e.g. 0.03 for 3%). Values outside that range are rejected."
+            },
+            "auto-slippage": {
+              "type": "boolean",
+              "description": "Let slippage be calculated automatically instead of using a fixed --slippage."
+            },
+            "max-auto-slippage": {
+              "type": "string",
+              "description": "Upper bound applied when --auto-slippage is enabled, as a decimal between 0 and 1 (e.g. 0.03 for 3%)."
+            },
+            "max-input": {
+              "type": "string",
+              "description": "exactOut only: hard ceiling on the sell-token spend, in base units. Required for EVM (Base) exactOut and optional on Solana (which has no ERC-20 approval to scope). Measured against the slippage-buffered approval (input + slippage), not the bare quote input, so it matches the amount that can actually leave the wallet. Persisted with the quote and enforced before any approval or signing — a quote whose buffered approval exceeds it is refused."
             }
           },
           "prerequisites": [
@@ -1566,6 +1596,11 @@
         "execute": {
           "description": "Sign and broadcast a quoted trade",
           "options": {
+            "quote": {
+              "type": "string",
+              "required": true,
+              "description": "Quote ID returned by `nansen trade quote` (alias: --quote-id)."
+            },
             "chain": {
               "type": "string",
               "default": "base",
@@ -1578,6 +1613,14 @@
             "gasless": {
               "type": "boolean",
               "description": "Relay-only: have Relay's solver pay gas + broadcast (user signs only). Requires the selected quote's aggregator to be \"relay\". Not supported via WalletConnect."
+            },
+            "quote-index": {
+              "type": "string",
+              "description": "Pin a specific quote by 0-based index when the cached quote returned several. Must be within range; there is no fallback to the other quotes."
+            },
+            "no-simulate": {
+              "type": "boolean",
+              "description": "Skip the pre-broadcast simulation."
             }
           }
         },
@@ -1792,6 +1835,56 @@
     "account": {
       "description": "Show API key status, plan, and remaining credits. Does not consume credits."
     },
+    "auth": {
+      "description": "Offline authentication status. Reports API key presence and source (env var vs config file), base URL, and x402 wallet readiness without any network call. Consumes no credits.",
+      "subcommands": {
+        "status": {
+          "description": "Show where credentials come from, entirely offline",
+          "returns": [
+            "logged_in",
+            "api_key.present",
+            "api_key.source",
+            "api_key.masked",
+            "config_file.path",
+            "config_file.exists",
+            "config_file.error",
+            "base_url.value",
+            "base_url.source",
+            "x402.configured",
+            "x402.wallets_dir",
+            "x402.wallets_dir_error",
+            "x402.wallet_count",
+            "x402.default_wallet",
+            "x402.default_wallet_provider",
+            "x402.password.available",
+            "x402.password.source",
+            "x402.password.keychain_available",
+            "offline"
+          ],
+          "examples": [
+            "nansen auth status --pretty"
+          ]
+        }
+      }
+    },
+    "doctor": {
+      "description": "Diagnostics for the CLI setup: Node version, auth config, wallet storage and password hygiene, keychain availability, caches, telemetry, plus a safe API connectivity probe (unauthenticated, consumes no credits). Local checks work with the API unavailable; --offline skips network entirely.",
+      "options": {
+        "json": {
+          "type": "boolean",
+          "description": "Return machine-readable checks ({id, status, message, fix?}) instead of formatted text"
+        },
+        "offline": {
+          "type": "boolean",
+          "description": "Skip the connectivity probe — no network access at all"
+        }
+      },
+      "examples": [
+        "nansen doctor",
+        "nansen doctor --offline",
+        "nansen doctor --json --pretty"
+      ]
+    },
     "web": {
       "description": "Web search and fetch commands",
       "subcommands": {

package/src/telemetry.js

@@ -5,6 +5,10 @@
  * how long they take, and where errors occur.  Events are fire-and-forget —
  * failures are silently ignored and never block the CLI.
  *
+ * Perp `order`/`close` additionally emit a `perp_order_completed` event that
+ * carries only the trade side and the Hyperliquid order id, tied to the same
+ * random anonymous_id. All telemetry is opt-out via DO_NOT_TRACK=1 or
+ * NANSEN_NO_TELEMETRY=1.
  */
 
 import fs from 'fs';
@@ -26,8 +30,15 @@ const TIMEOUT_MS = 1000;
 
 // ─── opt-out ──────────────────────────────────────────────
 
-export const TELEMETRY_DISABLED =
-  process.env.DO_NOT_TRACK === '1' || process.env.NANSEN_NO_TELEMETRY === '1';
+/**
+ * The single source of truth for the opt-out predicate — only the literal '1'
+ * disables telemetry. Also used by `nansen doctor` to report telemetry state.
+ */
+export function isTelemetryDisabled(env = process.env) {
+  return env.DO_NOT_TRACK === '1' || env.NANSEN_NO_TELEMETRY === '1';
+}
+
+export const TELEMETRY_DISABLED = isTelemetryDisabled();
 
 // ─── environment ──────────────────────────────────────────
 
@@ -245,3 +256,49 @@ export function trackCommandFailed({
     context: buildContext(),
   });
 }
+
+/**
+ * Track a completed Hyperliquid perp order (`nansen perp order` / `perp close`).
+ *
+ * Fired from `buildScreenSignSubmit` in perp.js AFTER the HL /exchange response
+ * is parsed (`summarizeOrderResult`). This is the only event that sees the order
+ * OUTCOME: `cli_command_succeeded` fires at the command wrapper, before the
+ * order path returns, so it captures command metadata but never the fill. Perp
+ * orders bypass the Nansen API on submit (CLI signs and posts straight to
+ * Hyperliquid — Decision D4), so the backend never sees the response either;
+ * this client-side event is the only way order outcomes reach BI.
+ *
+ * Fires on success only: a HL rejection throws in `submitExchange` and is
+ * captured by `cli_command_failed`, so no failed event is emitted here.
+ *
+ * Deliberately minimal: only the trade side and the Hyperliquid order id — no
+ * asset, price, size, or fill detail. A trade (fill) id is not carried by the
+ * order-placement response (it exists only once the order fills, via the fills
+ * feed), so it is not available here. `oid` is omitted when it exceeded JS
+ * safe-integer precision at parse time (see summarizeOrderResult).
+ *
+ * @param {object} opts
+ * @param {'order'|'close'} opts.command  - Which perp command placed the order (routes `path`)
+ * @param {'buy'|'sell'} opts.side        - Normalized trade side
+ * @param {number} [opts.oid]             - Parent leg's Hyperliquid order id (omitted if imprecise)
+ */
+export function trackPerpOrderCompleted({ command, side, oid }) {
+  return sendEvent({
+    event: 'perp_order_completed',
+    event_source: getEventSource(),
+    event_id: crypto.randomUUID(),
+    user_id: null,
+    anonymous_id: getAnonymousId(),
+    session_id: getSessionId(),
+    timestamp: new Date().toISOString(),
+    // Same path as the command's cli_command_succeeded ("/perp/order" |
+    // "/perp/close"), so BI can line the two events up per command.
+    path: commandToPath(`perp ${command}`),
+    properties: {
+      source: `nansen-cli/${cliVersion}`,
+      side,
+      ...(oid !== undefined && { oid }),
+    },
+    context: buildContext(),
+  });
+}