nansen-cli 1.36.1 → 1.37.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.37.0
+
+### Minor Changes
+
+- [#481](https://github.com/nansen-ai/nansen-cli/pull/481) [`ccaa40b`](https://github.com/nansen-ai/nansen-cli/commit/ccaa40beb570c2a6df5917ded308c3bb1722eb70) Thanks [@kome12](https://github.com/kome12)! - Add `research profiler first-funder` command to look up the first wallet that funded an EVM address. The funder is the earliest address to send native gas, resolved across chains, returned with its Nansen label and the funding transaction.
+
+- [#485](https://github.com/nansen-ai/nansen-cli/pull/485) [`b49c758`](https://github.com/nansen-ai/nansen-cli/commit/b49c75866379421c0738032e1f98a4a74b3fb5b4) Thanks [@MarcLlopart](https://github.com/MarcLlopart)! - `nansen perp order` and `perp close` now print the Hyperliquid order id (`oid`) and fill (size @ avg price) returned by the exchange, plus a ready-to-run `nansen perp cancel` command for any resting order — mirroring how spot trading surfaces its quote id. TP/SL bracket legs are labelled (parent / take-profit / stop-loss). Order ids are uint64; an id beyond JavaScript's safe integer range (2^53) is detected and its exact value and cancel hint are withheld rather than shown rounded, so a wrong id is never presented as actionable.
+
+### Patch Changes
+
+- [#483](https://github.com/nansen-ai/nansen-cli/pull/483) [`d0d10a2`](https://github.com/nansen-ai/nansen-cli/commit/d0d10a266e32aa086a8934acaa8e1d0b9ddff2e2) Thanks [@kome12](https://github.com/kome12)! - Unknown-command errors now detect when a whole multi-word command was passed as a single argument (a common shell-quoting mistake, e.g. `nansen "trade --help"` or an unquoted variable under zsh) and point at the likely cause instead of a bare "Unknown command".
+
+- [#484](https://github.com/nansen-ai/nansen-cli/pull/484) [`bc5f774`](https://github.com/nansen-ai/nansen-cli/commit/bc5f774165df7103eff9ba5cfcdc660bcec5d752) Thanks [@kome12](https://github.com/kome12)! - Write the cost-map and update-check cache files atomically (temp file + rename) so concurrent `nansen` processes can no longer observe an empty or truncated cache.
+
+- [#465](https://github.com/nansen-ai/nansen-cli/pull/465) [`4105193`](https://github.com/nansen-ai/nansen-cli/commit/41051932236a37121819e0d1bf47c8fb34422ec8) Thanks [@dobbydobap](https://github.com/dobbydobap)! - Fix `nansen quote --help`, `nansen trade quote --help`, and `nansen execute --help` to print the trade usage and exit with code 0 instead of erroring with exit code 1.
+
+- [#485](https://github.com/nansen-ai/nansen-cli/pull/485) [`c9aaf58`](https://github.com/nansen-ai/nansen-cli/commit/c9aaf58923819c014588cb2c068600ad9872276e) Thanks [@MarcLlopart](https://github.com/MarcLlopart)! - `nansen perp order` / `perp close` now emit an anonymous `perp_order_completed` telemetry event after the Hyperliquid `/exchange` response is parsed. Perp orders bypass the Nansen API on submit (the CLI signs and posts straight to Hyperliquid), so this client-side event is the only signal that an order was placed. The payload is deliberately minimal — only the trade side and the Hyperliquid order id (omitted when it exceeded JS safe-integer precision); no asset, price, size, or fill detail is sent. The telemetry disclosure (CLI help footer and module docs) names exactly these fields. Honours the existing `DO_NOT_TRACK` / `NANSEN_NO_TELEMETRY` opt-out; order rejections remain covered by `cli_command_failed`.
+
+- [#478](https://github.com/nansen-ai/nansen-cli/pull/478) [`758ce13`](https://github.com/nansen-ai/nansen-cli/commit/758ce13b7c65a5a88d20378ae1ad5cc7bba7d7ba) Thanks [@boleklebovski](https://github.com/boleklebovski)! - Document the missing `trade quote` and `trade execute` options in `src/schema.json`: `--swap-mode`, `--slippage`, `--auto-slippage`, `--max-auto-slippage`, `--quote`, `--quote-index` and `--no-simulate`. These options are already implemented and documented for humans, but were absent from the machine-readable schema.
+
+- [#488](https://github.com/nansen-ai/nansen-cli/pull/488) [`f653b37`](https://github.com/nansen-ai/nansen-cli/commit/f653b3761a4abc8e8a45d3ff42cedf0241a8ff20) Thanks [@gulshngill](https://github.com/gulshngill)! - Warn on logout when `NANSEN_API_KEY` remains active in the environment.
+
+## 1.36.2
+
+### Patch Changes
+
+- [#479](https://github.com/nansen-ai/nansen-cli/pull/479) [`e2590ed`](https://github.com/nansen-ai/nansen-cli/commit/e2590ed5caf0461b43f6e726ec62d87f70d391fd) Thanks [@gulshngill](https://github.com/gulshngill)! - Surface richer API response metadata: the `X-Nansen-Credits-Cost` header now drives credit reporting (a concise `Credits: N (this call)` stderr line after each data command, falling back to the cached spec estimate when the header is absent), `requestId` is hoisted to the top level of the JSON error envelope (including `nansen agent` failures, which previously dropped it), and error codes now come from the API's stable `code` field when present — known codes map onto the existing error code enum, unknown ones pass through verbatim instead of being flattened. stdout JSON is unchanged; all new reporting goes to stderr.
+
 ## 1.36.1
 
 ### Patch Changes

package/README.md

@@ -209,7 +209,7 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
 
 ```json
 { "success": true,  "data": <api_response> }
-{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "details": { ... } }
+{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "requestId": "...", "details": { ... } }
 ```
 
 **Critical error codes:**
@@ -226,8 +226,8 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
 
 | Field | Meaning |
 |-------|---------|
-| `requestId` | Identifies this call end to end. Quote it in any support report. Opaque — do not parse it. |
-| `credits` | `used`, `remaining` |
+| `requestId` | Identifies this call end to end. Quote it in any support report. Opaque — do not parse it. Also hoisted to the top level of the error envelope. |
+| `credits` | `used`, `remaining`, `cost` (the authoritative charge for this call) |
 | `rateLimit` | `limit`, `remaining`, `resetSeconds` |
 
 Any field may be absent or `null`, meaning unknown — never assume zero. A low-balance warning goes to **stderr**, so stdout stays pure JSON.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.36.1",
+  "version": "1.37.0",
   "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
   "main": "src/index.js",
   "type": "module",

package/skills/nansen-trading/SKILL.md

@@ -216,6 +216,8 @@ nansen perp order --coin BTC --side sell --size 0.001 --price 95000 --type marke
 - `--type`: `limit` (default) or `market`. `--tif`: `Gtc` (default), `Ioc`, `Alo`.
 - `--slippage`: decimal in `[0,1]` for market orders (default `0.03` = 3%).
 
+On success the command prints the Hyperliquid order id (`oid`) and the fill (size @ avg price). A resting (unfilled) order also prints a ready-to-run `nansen perp cancel --coin <coin> --oid <oid>`. Attached take-profit/stop-loss legs are labelled and each print their own `oid`.
+
 ## Close / cancel
 
 ```bash

package/src/api.js

@@ -116,12 +116,43 @@ export class NansenError extends Error {
 }
 
 /**
- * Map HTTP status codes to error codes
+ * Stable snake_case codes the server sends in error bodies, mapped to the
+ * ErrorCode values downstream consumers already key on.
+ */
+const SERVER_CODE_MAP = {
+  rate_limit_exceeded: ErrorCode.RATE_LIMITED,
+  insufficient_credits: ErrorCode.CREDITS_EXHAUSTED,
+  payment_required: ErrorCode.PAYMENT_REQUIRED,
+  unauthorized: ErrorCode.UNAUTHORIZED,
+  forbidden: ErrorCode.FORBIDDEN,
+  not_found: ErrorCode.NOT_FOUND,
+  unsupported_filter: ErrorCode.UNSUPPORTED_FILTER,
+  validation_error: ErrorCode.INVALID_PARAMS,
+  invalid_params: ErrorCode.INVALID_PARAMS,
+};
+
+/**
+ * Map an error response to an error code.
+ *
+ * Order matters: a 402 is always PAYMENT_REQUIRED (the x402 auto-payment flow
+ * keys on it, whatever the body says); then a stable `code` field from the
+ * server body wins over prose matching — known codes map onto the ErrorCode
+ * enum, unknown ones pass through verbatim so new server codes are tolerated,
+ * never flattened; bodies without a code fall back to status + prose.
  */
 export function statusToErrorCode(status, data = {}) {
+  if (status === 402) return ErrorCode.PAYMENT_REQUIRED;
+
+  const rawCode = [data?.code, data?.detail?.code]
+    .find(value => typeof value === 'string' && value.trim() !== '');
+  if (rawCode !== undefined) {
+    const serverCode = rawCode.trim();
+    return SERVER_CODE_MAP[serverCode] ?? serverCode;
+  }
+
   const message = data?.message || data?.error || '';
   const messageLower = message.toLowerCase();
-  
+
   switch (status) {
     case 400:
     case 422:
@@ -484,6 +515,8 @@ export class NansenAPI {
      * low-credit warning wants.
      */
     this.lastResponseMeta = null;
+    /** API path of the most recent request(), for pairing lastResponseMeta with a cost estimate. */
+    this.lastEndpoint = null;
   }
 
   static cleanBody(body) {
@@ -547,6 +580,7 @@ export class NansenAPI {
   }
 
   async request(endpoint, body = {}, options = {}) {
+    this.lastEndpoint = endpoint;
     const url = `${this.baseUrl}${endpoint}`;
     const { maxRetries, baseDelayMs, maxDelayMs, retryOnStatus } = this.retryOptions;
     const shouldRetry = options.retry !== false; // Allow disabling retry per-request
@@ -978,6 +1012,17 @@ export class NansenAPI {
     });
   }
 
+  async addressFirstFunder(params = {}) {
+    const { address } = params;
+    // EVM addresses only; the funder is resolved across chains server-side, so
+    // chain is fixed to 'all' and the endpoint forbids any extra fields.
+    if (address) requireValidAddress(address, 'ethereum');
+    return this.request('/api/v1/profiler/address/first-funder', {
+      address,
+      chain: 'all'
+    });
+  }
+
   async addressCounterparties(params = {}) {
     const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30 } = params;
     if (address) requireValidAddress(address, chain);

package/src/cli.js

@@ -15,7 +15,7 @@ import { buildResearchCommands, RESEARCH_HISTORICAL_SUBCOMMANDS } from './comman
 import { resolveAddress, isEnsName } from './ens.js';
 import fs from 'fs';
 import { getUpdateNotification, getUpgradeNotice, scheduleUpdateCheck } from './update-check.js';
-import { refreshCostMapIfStale, getCostForEndpoint } from './cost-cache.js';
+import { refreshCostMapIfStale, getCostForEndpoint, creditsCharged } from './cost-cache.js';
 import { creditWarning, noticeWarnings } from './response-meta.js';
 import { trackCommandSucceeded, trackCommandFailed } from './telemetry.js';
 import { createRequire } from 'module';
@@ -390,6 +390,10 @@ export function formatError(error) {
     code: error.code || 'UNKNOWN',
     status: error.status || null,
   };
+  // Hoisted so the id survives even if details is omitted or later pruned.
+  if (details?.requestId) {
+    result.requestId = details.requestId;
+  }
   if (details != null && !(typeof details === 'object' && !Array.isArray(details) && Object.keys(details).length === 0)) {
     result.details = details;
   }
@@ -767,9 +771,54 @@ Labels: Fund, Smart Trader, 30D/90D/180D Smart Trader, Smart HL Perps Trader
 Docs: https://docs.nansen.ai
 Skills: npx skills add nansen-ai/nansen-cli (agent-optimised docs per command group)
 
-Telemetry: anonymous usage stats collected. Disable: DO_NOT_TRACK=1
+Telemetry: anonymous usage stats (commands, timing, errors). Perp order/close additionally send the order side and Hyperliquid order id. Disable: DO_NOT_TRACK=1
 `;
 
+// Usage text for the `trade` command group. Shared by the trade handler and the
+// --help path in runCLI, so `nansen trade`, `nansen trade <sub> --help`, and the
+// deprecated top-level `quote`/`execute --help` all show the same usage.
+export const TRADE_USAGE = `nansen trade — DEX trading commands
+
+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
+  nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
+  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 1.5 --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.
+                    Defaults to the default local wallet if omitted.
+
+SYMBOLS:
+  Common tokens resolve automatically: SOL, ETH, USDC, USDT, WETH
+  Raw addresses are also accepted.
+
+CROSS-CHAIN NOTES (when using --to-chain):
+  Supported combos:
+    native → native (ETH <-> SOL)
+    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 providers: Li.Fi or Relay (selected automatically based on best price)
+  Typical bridge time: 1-5 minutes`;
+
 // Helper to prompt for input (exported for mocking)
 export async function prompt(question, hidden = false) {
   return new Promise((resolve) => {
@@ -828,7 +877,8 @@ export function buildCommands(deps = {}) {
     saveConfigFn = saveConfig,
     deleteConfigFn = deleteConfig,
     getConfigFileFn = getConfigFile,
-    isTTY = process.stdin.isTTY
+    isTTY = process.stdin.isTTY,
+    env = process.env
   } = deps;
 
   const cmds = {
@@ -1000,6 +1050,9 @@ export function buildCommands(deps = {}) {
       } else {
         log('No saved credentials found');
       }
+      if (env.NANSEN_API_KEY) {
+        log('Warning: NANSEN_API_KEY remains active. Run: unset NANSEN_API_KEY');
+      }
     },
 
     'help': async (_args, _apiInstance, _flags, _options) => {
@@ -1143,7 +1196,8 @@ export function buildCommands(deps = {}) {
       let ensName;
       if (address && isEnsName(address)) {
         try {
-          const resolved = await resolveAddress(address, chain);
+          const ensChain = subcommand === 'first-funder' ? 'ethereum' : chain;
+          const resolved = await resolveAddress(address, ensChain);
           address = resolved.address;
           ensName = resolved.ensName;
         } catch (err) {
@@ -1169,6 +1223,7 @@ export function buildCommands(deps = {}) {
         'search': () => apiInstance.entitySearch({ query: options.query }),
         'historical-balances': () => apiInstance.addressHistoricalBalances({ address, chain, filters, orderBy, pagination, days }),
         'related-wallets': () => apiInstance.addressRelatedWallets({ address, chain, orderBy, pagination }),
+        'first-funder': () => apiInstance.addressFirstFunder({ address }),
         'counterparties': () => apiInstance.addressCounterparties({ address, chain, filters, orderBy, pagination, days }),
         'pnl-summary': () => apiInstance.addressPnlSummary({ address, chain, orderBy, pagination, days }),
         'perp-positions': () => apiInstance.addressPerpPositions({ address, filters, orderBy, pagination }),
@@ -1215,7 +1270,7 @@ export function buildCommands(deps = {}) {
           return compareWallets(apiInstance, { addresses: addrs, chain, days });
         },
         'help': () => ({
-          commands: ['balance', 'labels', 'transactions', 'pnl', 'search', 'historical-balances', 'related-wallets', 'counterparties', 'pnl-summary', 'perp-positions', 'perp-trades', 'dex-trades', 'batch', 'trace', 'compare'],
+          commands: ['balance', 'labels', 'transactions', 'pnl', 'search', 'historical-balances', 'related-wallets', 'first-funder', 'counterparties', 'pnl-summary', 'perp-positions', 'perp-trades', 'dex-trades', 'batch', 'trace', 'compare'],
           description: 'Wallet profiling endpoints',
           example: 'nansen research profiler compare --addresses "0xABC...,0xDEF..." --chain ethereum'
         })
@@ -1554,47 +1609,7 @@ export function buildCommands(deps = {}) {
   cmds['trade'] = async (args, apiInstance, flags, options) => {
     const sub = args[0];
     if (!sub || sub === 'help') {
-      log(`nansen trade — DEX trading commands
-
-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
-  nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
-  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 1.5 --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.
-                    Defaults to the default local wallet if omitted.
-
-SYMBOLS:
-  Common tokens resolve automatically: SOL, ETH, USDC, USDT, WETH
-  Raw addresses are also accepted.
-
-CROSS-CHAIN NOTES (when using --to-chain):
-  Supported combos:
-    native → native (ETH <-> SOL)
-    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 providers: Li.Fi or Relay (selected automatically based on best price)
-  Typical bridge time: 1-5 minutes`);
+      log(TRADE_USAGE);
       return;
     }
     if (sub === 'limit-order') {
@@ -1918,7 +1933,16 @@ export async function runCLI(rawArgs, deps = {}) {
         return { type: 'command-help', command };
       }
     }
-    // Commands with handlers (e.g. quote, execute) show their own usage
+    // The trade group (and the deprecated top-level quote/execute aliases) use
+    // handler-based usage rather than schema help. Show it and exit 0, instead of
+    // falling through to command execution, which would error on missing required
+    // args and exit 1.
+    if (command === 'trade' || DEPRECATED_TO_TRADE.has(command)) {
+      output(deprecationNote(command) + TRADE_USAGE);
+      notify();
+      return { type: 'command-help', command };
+    }
+    // 'help' and unknown commands: full banner + command list
     if (command === 'help' || !commands[command]) {
       output(BANNER + HELP);
       notify();
@@ -1935,8 +1959,15 @@ export async function runCLI(rawArgs, deps = {}) {
   const chain = options.chain || null;
 
   if (!commands[command]) {
+    // A command token containing whitespace almost always means a multi-word
+    // invocation was passed as a single argument — e.g. `nansen "trade --help"`,
+    // or an unquoted shell variable under zsh (which, unlike bash, does not
+    // word-split `$var`). Point the user straight at the cause instead of a bare
+    // "Unknown command" that reads like a spurious failure.
     const errorData = {
-      error: `Unknown command: ${command}`,
+      error: /\s/.test(command)
+        ? `Unknown command: "${command}". This looks like multiple words passed as one argument — check your shell quoting (use \`nansen trade --help\`, not \`nansen "trade --help"\`).`
+        : `Unknown command: ${command}`,
       available: Object.keys(commands)
     };
     const formatted = formatOutput(errorData, { pretty, table });
@@ -1983,6 +2014,15 @@ export async function runCLI(rawArgs, deps = {}) {
     if (lowCredits) errorOutput(lowCredits);
     for (const notice of noticeWarnings(api.lastResponseMeta)) errorOutput(notice);
 
+    // What this call cost — authoritative header when the API sent one, else
+    // the cached spec estimate. stderr only, so stdout JSON stays pure.
+    const charged = creditsCharged(api.lastResponseMeta, api.lastEndpoint);
+    if (charged?.source === 'header') {
+      errorOutput(`Credits: ${charged.cost} (this call)`);
+    } else if (charged?.source === 'estimate') {
+      errorOutput(`Credits: ~${charged.estimate.free} free / ${charged.estimate.pro} pro (estimated)`);
+    }
+
     // Commands that handle their own output return undefined
     if (result === undefined) {
       await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });

package/src/commands/agent.js

@@ -6,6 +6,7 @@
 import crypto from 'crypto';
 import { NansenError, ErrorCode, statusToErrorCode, telemetryHeaders, packageVersion } from '../api.js';
 import { getCostForEndpoint } from '../cost-cache.js';
+import { readResponseMeta } from '../response-meta.js';
 
 /**
  * Build standard request headers, matching apiInstance.request() conventions.
@@ -25,7 +26,7 @@ function buildHeaders(apiInstance) {
  * Throw a NansenError with the same structure as apiInstance.request() errors.
  * Includes `details` field for consistency with other commands.
  */
-function throwApiError(message, status, serverDetail) {
+function throwApiError(message, status, serverDetail, errData = null, requestId = null) {
   // Match the friendly wrapper messages from apiInstance.request()
   let friendlyMessage = message;
   if (status === 401) {
@@ -36,9 +37,14 @@ function throwApiError(message, status, serverDetail) {
 
   throw new NansenError(
     friendlyMessage,
-    statusToErrorCode(status),
+    statusToErrorCode(status, errData || {}),
     status,
-    { detail: serverDetail || message, attempt: 1, retryAfterMs: null },
+    {
+      detail: serverDetail || message,
+      attempt: 1,
+      retryAfterMs: null,
+      ...(requestId && { requestId }),
+    },
   );
 }
 
@@ -273,16 +279,20 @@ EXAMPLES:
       if (!response.ok) {
         clearTimeout(timer);
         let serverDetail;
+        let errData = null;
         if (response.headers.get('content-type')?.includes('application/json')) {
           try {
-            const errData = await response.json();
+            errData = await response.json();
             serverDetail = errData.detail || errData.message;
           } catch { /* ignore parse failure */ }
         }
+        const meta = readResponseMeta(response);
         throwApiError(
           serverDetail || `Agent returned ${response.status}`,
           response.status,
           serverDetail,
+          errData,
+          meta?.requestId,
         );
       }
 

package/src/cost-cache.js

@@ -14,6 +14,24 @@ const CACHE_FILE = path.join(CONFIG_DIR, 'cost-map.json');
 const STALE_MS = 24 * 60 * 60 * 1000; // 24 hours
 const OPENAPI_URL = 'https://api.nansen.ai/openapi.json';
 
+/**
+ * Write `data` to `file` atomically: write to a unique temp file in the same
+ * directory, then rename over the target. rename(2) is atomic on POSIX, so a
+ * concurrent reader always sees either the old file or the fully-written new
+ * one — never a truncated/empty file. The temp name includes the pid so
+ * concurrent writers don't clobber each other's temp files.
+ */
+function writeAtomic(file, data) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* temp file may not exist */ }
+    throw err;
+  }
+}
+
 /**
  * Returns { free, pro } credit cost for the given API path, or null if unavailable.
  */
@@ -27,6 +45,21 @@ export function getCostForEndpoint(endpoint) {
   }
 }
 
+/**
+ * What did (or would) this call cost?
+ *
+ * Prefers the authoritative cost response header, then the spec-derived
+ * estimate for the endpoint, else null.
+ * Returns { cost, source: 'header' } or { estimate: { free, pro }, source: 'estimate' }.
+ */
+export function creditsCharged(meta, endpoint) {
+  const charged = meta?.credits?.cost;
+  if (charged != null) return { cost: charged, source: 'header' };
+  const estimate = endpoint ? getCostForEndpoint(endpoint) : null;
+  if (estimate != null) return { estimate, source: 'estimate' };
+  return null;
+}
+
 /**
  * Fetches the OpenAPI spec and writes the cost map to disk if the cache is
  * missing or older than 24h. Awaited inline — only blocks on cold/stale cache.
@@ -60,7 +93,7 @@ export async function refreshCostMapIfStale() {
     }
 
     if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { mode: 0o700, recursive: true });
-    fs.writeFileSync(CACHE_FILE, JSON.stringify({ costs, fetchedAt: Date.now() }));
+    writeAtomic(CACHE_FILE, JSON.stringify({ costs, fetchedAt: Date.now() }));
   } catch {
     // silent — network failure, parse error, write error
   }

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/response-meta.js

@@ -19,6 +19,7 @@
 /** Header names, as documented in the API reference. */
 const CREDITS_USED = 'x-nansen-credits-used';
 const CREDITS_REMAINING = 'x-nansen-credits-remaining';
+const CREDITS_COST = 'x-nansen-credits-cost';
 const RATE_LIMIT = 'x-ratelimit-limit';
 const RATE_REMAINING = 'x-ratelimit-remaining';
 const RATE_RESET = 'x-ratelimit-reset';
@@ -34,8 +35,8 @@ const REQUEST_ID = 'x-request-id';
 function intHeader(response, name) {
   const raw = stringHeader(response, name);
   if (raw === null) return null;
-  const value = Number.parseInt(raw, 10);
-  return Number.isInteger(value) && value >= 0 ? value : null;
+  const value = Number(raw);
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
 }
 
 /**
@@ -57,6 +58,7 @@ function stringHeader(response, name) {
 export function readResponseMeta(response) {
   const used = intHeader(response, CREDITS_USED);
   const remaining = intHeader(response, CREDITS_REMAINING);
+  const cost = intHeader(response, CREDITS_COST);
   const limit = intHeader(response, RATE_LIMIT);
   const rateRemaining = intHeader(response, RATE_REMAINING);
   const resetSeconds = intHeader(response, RATE_RESET);
@@ -71,8 +73,10 @@ export function readResponseMeta(response) {
     // never parse it or assume a format.
     meta.requestId = requestId;
   }
-  if (used !== null || remaining !== null) {
-    meta.credits = { used, remaining };
+  if (used !== null || remaining !== null || cost !== null) {
+    // cost is the server's authoritative pre-flight price for this call;
+    // used is what was actually deducted. They can disagree (e.g. free rails).
+    meta.credits = { used, remaining, cost };
   }
   if (limit !== null || rateRemaining !== null || resetSeconds !== null) {
     // resetSeconds is a delta in seconds — how long the tripped window needs to
@@ -111,13 +115,15 @@ export function noticeWarnings(meta) {
 export function creditWarning(meta) {
   const credits = meta?.credits;
   if (!credits) return null;
-  const { used, remaining } = credits;
+  const { used, remaining, cost } = credits;
   if (remaining === null) return null;
   if (remaining === 0) {
     return '⚠️  Out of API credits. Top up at https://app.nansen.ai/api';
   }
-  if (used !== null && used > 0 && remaining < used) {
-    return `⚠️  ${remaining} API credit${remaining === 1 ? '' : 's'} left — less than this call cost (${used}). Top up at https://app.nansen.ai/api`;
+  // The cost header is the authoritative charge; used is the fallback.
+  const charged = cost ?? used;
+  if (charged !== null && charged > 0 && remaining < charged) {
+    return `⚠️  ${remaining} API credit${remaining === 1 ? '' : 's'} left — less than this call cost (${charged}). Top up at https://app.nansen.ai/api`;
   }
   return null;
 }

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,23 @@
             "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%)."
             }
           },
           "prerequisites": [
@@ -1566,6 +1592,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 +1609,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."
             }
           }
         },

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';
@@ -245,3 +249,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(),
+  });
+}

package/src/update-check.js

@@ -84,6 +84,48 @@ export function getUpdateNotification(currentVersion) {
   }
 }
 
+const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+
+/**
+ * Build the Node source run by the detached child. It fetches the latest
+ * version and writes it to `file` atomically: the JSON is written to a
+ * pid-scoped temp file, then renamed over the target. rename(2) is atomic on
+ * POSIX, so a concurrent `nansen` reader always sees either the old file or the
+ * fully-written new one — never a truncated/empty file.
+ *
+ * The registry URL is overridable via NANSEN_REGISTRY_URL purely as a test seam
+ * (lets a test point the child at a local server); it defaults to npm.
+ */
+export function buildCheckScript(dir, file, url = process.env.NANSEN_REGISTRY_URL || REGISTRY_URL) {
+  return `
+    const url = ${JSON.stringify(url)};
+    const http = require(url.startsWith('https:') ? 'https' : 'http');
+    const fs = require('fs');
+    const dir = ${JSON.stringify(dir)};
+    const file = ${JSON.stringify(file)};
+    const req = http.get(url, { timeout: 5000 }, (res) => {
+      let body = '';
+      res.on('data', c => body += c);
+      res.on('end', () => {
+        try {
+          const { version } = JSON.parse(body);
+          if (!fs.existsSync(dir)) fs.mkdirSync(dir, { mode: 0o700, recursive: true });
+          const tmp = file + '.' + process.pid + '.tmp';
+          try {
+            fs.writeFileSync(tmp, JSON.stringify({ latest: version, checkedAt: Date.now() }));
+            fs.renameSync(tmp, file);
+          } catch (e) {
+            try { fs.unlinkSync(tmp); } catch {}
+            throw e;
+          }
+        } catch {}
+      });
+    });
+    req.on('error', () => {});
+    req.setTimeout(5000, () => req.destroy());
+  `;
+}
+
 /**
  * If the cache is missing or stale, spawn a detached background process to refresh it.
  */
@@ -97,29 +139,7 @@ export function scheduleUpdateCheck() {
       if (checkedAt && Date.now() - checkedAt < STALE_MS) return;
     }
 
-    // Inline script executed by the detached child
-    const script = `
-      const https = require('https');
-      const fs = require('fs');
-      const path = require('path');
-      const dir = ${JSON.stringify(CONFIG_DIR)};
-      const file = ${JSON.stringify(CACHE_FILE)};
-      const req = https.get('https://registry.npmjs.org/${PACKAGE_NAME}/latest', { timeout: 5000 }, (res) => {
-        let body = '';
-        res.on('data', c => body += c);
-        res.on('end', () => {
-          try {
-            const { version } = JSON.parse(body);
-            if (!fs.existsSync(dir)) fs.mkdirSync(dir, { mode: 0o700, recursive: true });
-            fs.writeFileSync(file, JSON.stringify({ latest: version, checkedAt: Date.now() }));
-          } catch {}
-        });
-      });
-      req.on('error', () => {});
-      req.setTimeout(5000, () => req.destroy());
-    `;
-
-    const child = childProcess.spawn(process.execPath, ['-e', script], {
+    const child = childProcess.spawn(process.execPath, ['-e', buildCheckScript(CONFIG_DIR, CACHE_FILE)], {
       detached: true,
       stdio: 'ignore'
     });