nansen-cli 1.43.0 → 1.44.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## 1.44.0
+
+### Minor Changes
+
+- [#563](https://github.com/nansen-ai/nansen-cli/pull/563) [`3b3e11b`](https://github.com/nansen-ai/nansen-cli/commit/3b3e11b5d346662bf352cbe2e3f66e54b22213b0) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Emit privacy-preserving per-leg Hyperliquid attribution through the canonical trade-perps outcome events.
+
+- [#580](https://github.com/nansen-ai/nansen-cli/pull/580) [`c5085c5`](https://github.com/nansen-ai/nansen-cli/commit/c5085c5d062d848604402949a3e03c87d8b013bd) Thanks [@gulshngill](https://github.com/gulshngill)! - Add `nansen completion <bash|zsh|fish>`, which prints a shell completion script generated from the CLI's own command schema. Completions cover nested subcommands, per-command flags, global flags, and the enum values a flag accepts.
+
+- [#597](https://github.com/nansen-ai/nansen-cli/pull/597) [`8453355`](https://github.com/nansen-ai/nansen-cli/commit/845335501837956db2f7a899bf251048bbd706d9) Thanks [@kome12](https://github.com/kome12)! - Security: `nansen mcp verify` no longer sends a saved API key (from `nansen login` / `NANSEN_API_KEY` / config) to a custom `--url` without explicit consent. Forwarding a saved key to a non-default URL now requires `--send-api-key`, and no key is ever sent over plain HTTP to a non-loopback host. An inline `--api-key` is unaffected.
+
+  Note: verifying a custom `--url` with a saved key now errors unless `--send-api-key` is passed (previously it warned and proceeded).
+
+- [#557](https://github.com/nansen-ai/nansen-cli/pull/557) [`5a73b43`](https://github.com/nansen-ai/nansen-cli/commit/5a73b43e4f2fc753c435babcea648b156f7a99a9) Thanks [@gulshngill](https://github.com/gulshngill)! - Add the `nansen research address-premium-labels` command.
+
+- [#555](https://github.com/nansen-ai/nansen-cli/pull/555) [`4285d7f`](https://github.com/nansen-ai/nansen-cli/commit/4285d7fc22fde5bacb5b67eb3bcb6e94bb6a680e) Thanks [@gulshngill](https://github.com/gulshngill)! - Add the `nansen research chain-rank` command.
+
+- [#561](https://github.com/nansen-ai/nansen-cli/pull/561) [`dd8035c`](https://github.com/nansen-ai/nansen-cli/commit/dd8035c09f5c99c08247686c621c5c14c30607cc) Thanks [@gulshngill](https://github.com/gulshngill)! - Add the `nansen research historical-token-ohlcv` command.
+
+- [#560](https://github.com/nansen-ai/nansen-cli/pull/560) [`52f2f09`](https://github.com/nansen-ai/nansen-cli/commit/52f2f095baeaa48c43d5b0f3b1a3b036166266b5) Thanks [@gulshngill](https://github.com/gulshngill)! - Add the `nansen research perp-pnl-summary` command.
+
+- [#559](https://github.com/nansen-ai/nansen-cli/pull/559) [`ed2d7a5`](https://github.com/nansen-ai/nansen-cli/commit/ed2d7a5ac00b51240f5a2d0fb7828131dc5074c8) Thanks [@gulshngill](https://github.com/gulshngill)! - Add the `nansen research position-intelligence` command.
+
+- [#558](https://github.com/nansen-ai/nansen-cli/pull/558) [`e273152`](https://github.com/nansen-ai/nansen-cli/commit/e273152358792203435191a0f30dd307699721aa) Thanks [@gulshngill](https://github.com/gulshngill)! - Add the `nansen research smart-money-pnl-leaderboard` command.
+
+- [#556](https://github.com/nansen-ai/nansen-cli/pull/556) [`3c14359`](https://github.com/nansen-ai/nansen-cli/commit/3c143596b6d7e624338f8d9b1a0972bcbe4d7ad7) Thanks [@gulshngill](https://github.com/gulshngill)! - Add the `nansen research token-sectors` command.
+
+- [#562](https://github.com/nansen-ai/nansen-cli/pull/562) [`0d0f5e6`](https://github.com/nansen-ai/nansen-cli/commit/0d0f5e6b83ae91f0215eac3ad2e9216897e6666c) Thanks [@gulshngill](https://github.com/gulshngill)! - Add the `nansen research transaction-with-token-transfer-lookup` command.
+
+- [#581](https://github.com/nansen-ai/nansen-cli/pull/581) [`8726a23`](https://github.com/nansen-ai/nansen-cli/commit/8726a23c0e6028c98f941ee9a638dffa50e01ab1) Thanks [@gulshngill](https://github.com/gulshngill)! - Every command option in `nansen schema` now carries a type and a description (140 research and `wallet send` options had neither), and the `research points` group is described. `research token ohlcv --timeframe` documents its real default (`1d`), and `wallet send --chain`, `research search --type`, and the prediction-market `--neg-risk` filters declare the values they accept, so `--help` and shell completion offer them. Fixed `--neg-risk true` on the prediction-market screeners, which was sent to the API as `neg_risk: false` because the parsed boolean was compared against the string `'true'`. `nansen mcp install` and `nansen mcp uninstall` declare their positional client in the schema, and `nansen completion` scripts now complete it (`claude-code`, `claude-desktop`, `cursor`) in bash, zsh, and fish.
+
+### Patch Changes
+
+- [#575](https://github.com/nansen-ai/nansen-cli/pull/575) [`927ffea`](https://github.com/nansen-ai/nansen-cli/commit/927ffea1762e7de78160a209aa3cc72298b42c24) Thanks [@kome12](https://github.com/kome12)! - Fail closed on an ambiguous broadcast failure in swap and bridge execute. When
+  `/execute` (swap) returns any 5xx (regardless of body shape — a structured 504
+  `UPSTREAM_TIMEOUT` is treated the same as a bare 502) or any other
+  uninterpretable response — or the POST, or reading its body, throws a network
+  error — after the signed tx was sent, or a bridge broadcast fails ambiguously,
+  the tx may already be live. The quote is now marked spent and the
+  run aborts — rather than trying the next candidate quote or leaving the quote
+  reusable — so a re-execute (or agent auto-retry) can't double-broadcast. Gasless
+  (Relay solver-paid) swaps additionally do not retry the `/execute` POST: the
+  signed authorization is broadcast by Relay's own wrapping tx, so a re-POST can't
+  be node-deduped and could trigger a second solve — a single attempt fails closed
+  instead. A bridge send is kept reusable only when the node's error proves the tx never
+  entered the mempool (a pre-broadcast validation rejection such as insufficient
+  funds); in-flight txpool states like "already known" or "nonce too low" fail
+  closed.
+
+- [#572](https://github.com/nansen-ai/nansen-cli/pull/572) [`2ba5c15`](https://github.com/nansen-ai/nansen-cli/commit/2ba5c15a68f6cc2045dcfb928d65eecdb4083292) Thanks [@teyrebaz33](https://github.com/teyrebaz33)! - Fix `nansen changelog --since <version>` silently returning "No changelog entries found" for a version missing its patch number (e.g. `--since 1.43` instead of `--since 1.43.0`), even when matching entries exist. The comparison compared the missing component against `undefined`, and `>` is always `false` against `undefined` in both directions, so a version that matched on major.minor always came out "less than" the since-value. A missing component is now treated as `0`, and a `--since` value that isn't a valid version (e.g. `--since abc`) now prints a clear error instead of silently matching nothing.
+
+  The version-comparison logic is now shared (`src/semver.js`) between `nansen changelog --since` and the update-notifier's `isNewer` check, which had the identical bug in its own separate parser. `isNewer` couldn't misfire in practice (both versions it compares are always fully-qualified x.y.z today), but it's the same defect class, so it's fixed the same way rather than left in place.
+
+- [#569](https://github.com/nansen-ai/nansen-cli/pull/569) [`04932c7`](https://github.com/nansen-ai/nansen-cli/commit/04932c7fb26fb2c4c4f9b14eddcd43a8e3060aa4) Thanks [@memosr](https://github.com/memosr)! - Refuse to re-execute a swap quote that has already been broadcast, mirroring the single-use guard `nansen bridge execute` already had. `nansen trade execute` now marks the quote as spent (`executedAt`) the instant a transaction is broadcast — before waiting for its receipt — so a `RECEIPT_TIMEOUT` (the tx is on-chain but the command exits non-zero) no longer leaves the quote replayable. Retrying the same `--quote <id>` after such a failure previously re-signed and re-broadcast the swap under a fresh nonce instead of being refused.
+
+- [#592](https://github.com/nansen-ai/nansen-cli/pull/592) [`60bd2ef`](https://github.com/nansen-ai/nansen-cli/commit/60bd2ef64f5eebe89112bfa3366c013981f365aa) Thanks [@ygd58](https://github.com/ygd58)! - Fix the x402 auto-payment fallback in `src/api.js` generating multiple payment authorizations for the same request after an ambiguous outcome (issue #583). After a signed `Payment-Signature` was transmitted, `_x402Retry` previously collapsed every non-ok response — a clean rejection, a 5xx, an unreadable body — and every transport failure into a single `null`, and callers treated any `null` as "safe to try the next payment option/provider". That meant a 5xx, a timeout, or an unparseable response (any of which could mean the server already received and settled the payment) triggered signing and transmitting a _second_ independent payment for the same logical request. Separately, a genuine successful response whose JSON body happened to be `null` was indistinguishable from a rejection, risking a second payment for an already-settled call.
+
+  `_x402Retry` now returns a dedicated `X402_PAYMENT_REJECTED` sentinel only for a provably clean rejection (a non-5xx status with a readable body), and throws `NansenError` with the new `PAYMENT_AMBIGUOUS` code for anything else — a transport failure, a 5xx, or an unreadable body on either a rejection or a success. All three fallback call sites (Privy, local wallet, WalletConnect) now check against the sentinel instead of `null`, and re-throw a `PAYMENT_AMBIGUOUS` error immediately instead of silently moving on to the next provider.
+
+- [#524](https://github.com/nansen-ai/nansen-cli/pull/524) [`3e8dcc2`](https://github.com/nansen-ai/nansen-cli/commit/3e8dcc233598383556004da7aaa0a64275beee3f) Thanks [@dolmaciabdullah-byte](https://github.com/dolmaciabdullah-byte)! - Use BigInt for EVM balance in `checkX402Balance` to avoid precision loss on 18-decimal tokens (BSC stablecoins): `parseInt(hex, 16)` loses integer precision once the raw wei value exceeds `Number.MAX_SAFE_INTEGER` (~9.0e15 wei, i.e. ~0.009 tokens at 18 decimals), skewing the low-balance warning.
+
+- [#568](https://github.com/nansen-ai/nansen-cli/pull/568) [`9a45fc4`](https://github.com/nansen-ai/nansen-cli/commit/9a45fc494b3bcc0ebeb37f867902aecc075ee92f) Thanks [@Kewe63](https://github.com/Kewe63)! - Reject non-finite limit-order trigger prices and expiry values before wallet or API activity.
+
+- [#567](https://github.com/nansen-ai/nansen-cli/pull/567) [`c0fe57b`](https://github.com/nansen-ai/nansen-cli/commit/c0fe57b6f881aa7338a16f6aa2fd33d5e6d42757) Thanks [@Kewe63](https://github.com/Kewe63)! - Keep `research perp` analytics-only instead of routing trading subcommands through the top-level perp dispatcher.
+
+- [#558](https://github.com/nansen-ai/nansen-cli/pull/558) [`002921e`](https://github.com/nansen-ai/nansen-cli/commit/002921e5d72e7e54de26f241cb4b409e408b8bf9) Thanks [@gulshngill](https://github.com/gulshngill)! - Reject non-integer or non-positive `--limit` values with an actionable error instead of forwarding them to the API.
+
+## 1.43.1
+
+### Patch Changes
+
+- [#526](https://github.com/nansen-ai/nansen-cli/pull/526) [`a7ab05c`](https://github.com/nansen-ai/nansen-cli/commit/a7ab05c592bddd1e0ca33c08586ef325bcc19277) Thanks [@dolmaciabdullah-byte](https://github.com/dolmaciabdullah-byte)! - Fix `formatValue` displaying `1000.00K` instead of `1.00M` when a value like 999999.995 rounds up at the K/M boundary.
+
+- [#548](https://github.com/nansen-ai/nansen-cli/pull/548) [`000d01a`](https://github.com/nansen-ai/nansen-cli/commit/000d01a8530de7e5bb6af8a637ba1b4fe406b732) Thanks [@Sertug17](https://github.com/Sertug17)! - Fix `parseAmount` silently producing wrong values for negative decimal inputs. Negative amounts are now rejected with a clear error.
+
+- [#551](https://github.com/nansen-ai/nansen-cli/pull/551) [`092535a`](https://github.com/nansen-ai/nansen-cli/commit/092535aa32bedb8c11a6ee624936bffca247d2d5) Thanks [@kome12](https://github.com/kome12)! - Harden `parseAmount` input validation: reject negative amounts wrapped in whitespace (previously silently miscalculated), and reject non-numeric or malformed inputs (e.g. `abc`, empty string, `1.`, `.5`) with a clear error instead of throwing a raw error or silently returning `0`.
+
+- [#433](https://github.com/nansen-ai/nansen-cli/pull/433) [`977fbc5`](https://github.com/nansen-ai/nansen-cli/commit/977fbc51a75ef4a0764db161b4bbee26d1ebc3ae) Thanks [@aikido-autofix](https://github.com/apps/aikido-autofix)! - Validate the wallet name before the Privy pre-read in `wallet delete` and `wallet send`, routing both reads through `getWalletFile()` so the path stays confined to the wallets directory.
+
+- [#545](https://github.com/nansen-ai/nansen-cli/pull/545) [`642eb20`](https://github.com/nansen-ai/nansen-cli/commit/642eb20a48fe1ff5a9ba17fcbeac4604c7172698) Thanks [@kome12](https://github.com/kome12)! - Update Noble crypto dependencies to the patched 2.4.x releases.
+
 ## 1.43.0
 
 ### Minor Changes

package/README.md

@@ -51,11 +51,23 @@ nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
 nansen trade execute --quote <quoteId>
 nansen wallet <subcommand> [options]
 nansen mcp install <client>           # add the Nansen MCP server to Claude Code/Desktop or Cursor
+nansen completion <bash|zsh|fish>     # shell completions (no API key needed)
 nansen schema [command] [--pretty]    # full command reference (no API key needed)
 ```
 
 **Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`, `points`
 
+**Direct research subcommands:**
+- `nansen research chain-rank [--timeframe-days 7|30|365] [--chain-type all|evm]` — rank chains by growth metrics
+- `nansen research token-sectors` — list token sectors available for filtering
+- `nansen research address-premium-labels --address <addr> [--chain <chain>] [--page <n>] [--limit <n>]` — get all labels for an address, including premium labels
+- `nansen research smart-money-pnl-leaderboard [--chains c1,c2] [--timeframe-days 1|7|30|90|180] [--filters '<json>'] [--sort <field[:asc|desc]>] [--page <n>] [--limit <n>]` — rank smart money wallets by PnL
+- `nansen research position-intelligence --symbol <symbol>` — aggregate Hyperliquid positions by trader cohort
+- `nansen research perp-pnl-summary --address <addr> --from-date <date> --to-date <date>` — summarize realized Hyperliquid PnL for an address
+- `nansen research transaction-with-token-transfer-lookup --transaction-hash <hash> [--chain <chain>] [--block-timestamp "YYYY-MM-DD HH:MM:SS"]` — look up a transaction and its token/NFT transfers
+
+Plus the `historical-*` point-in-time commands — run `nansen research help` for the full list.
+
 **Trade:** `quote`, `execute`, `bridge-status`, `limit-order` — DEX swaps on Solana and Base, cross-chain bridges, and Solana limit orders.
 
 **Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send` — local or Privy server-side wallets (EVM + Solana).
@@ -253,6 +265,28 @@ tempo request POST https://api.nansen.ai/api/v1/smart-money/netflow \
 
 > Note: MPP is server-side opt-in (`MPP_ENABLED=true` on the API). It's available on dev today and rolling out to prod — if `tempo request` returns a non-MPP 402, fall back to x402 or an API key.
 
+## Shell Completions
+
+Tab-completion for commands, subcommands, flags, and the values a flag accepts:
+
+```bash
+# bash
+echo 'eval "$(nansen completion bash)"' >> ~/.bashrc
+# or system-wide: nansen completion bash > /etc/bash_completion.d/nansen
+
+# zsh
+nansen completion zsh > "${fpath[1]}/_nansen" && compinit
+# or, in ~/.zshrc after the compinit line: eval "$(nansen completion zsh)"
+
+# fish
+nansen completion fish > ~/.config/fish/completions/nansen.fish
+```
+
+The scripts are generated from the same schema as `nansen schema`, so they cover
+every nested subcommand and stay in step with the CLI. Nothing is written to
+disk and no network call is made — the script goes to stdout. Re-run the command
+after upgrading the CLI to pick up new commands.
+
 ## Key Options
 
 | Option | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
   "main": "src/index.js",
   "type": "module",
@@ -73,8 +73,8 @@
   },
   "dependencies": {
     "@ethereumjs/rlp": "^10.1.1",
-    "@noble/curves": "^2.0.1",
-    "@noble/hashes": "^2.0.1",
+    "@noble/curves": "^2.4.0",
+    "@noble/hashes": "^2.4.0",
     "@scure/base": "^2.0.0"
   }
 }

package/src/api.js

@@ -19,6 +19,16 @@ import { readResponseMeta } from './response-meta.js';
  */
 export const RESPONSE_META = Symbol('nansenResponseMeta');
 
+/**
+ * Sentinel returned by _x402Retry to mean "this payment option was cleanly
+ * rejected without settlement, safe to try the next option" — distinct from
+ * a genuine successful response whose JSON body happens to be `null`.
+ * Using `null` for both (the previous behavior) made a legitimate null-body
+ * success indistinguishable from a clean rejection, so the caller would sign
+ * and transmit ANOTHER payment for a request that had already succeeded.
+ */
+export const X402_PAYMENT_REJECTED = Symbol('x402PaymentRejected');
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 export function telemetryHeaders() {
@@ -65,6 +75,7 @@ export const ErrorCode = {
   // Client Errors
   NETWORK_ERROR: 'NETWORK_ERROR',         // Connection failed
   TIMEOUT: 'TIMEOUT',                     // Request timed out
+  PAYMENT_AMBIGUOUS: 'PAYMENT_AMBIGUOUS', // x402 payment outcome unknown after transmission — do not retry with another payment
   
   // Generic
   UNKNOWN: 'UNKNOWN',                     // Unclassified error
@@ -530,7 +541,14 @@ export class NansenAPI {
 
   /**
    * Retry a POST request with a payment signature.
-   * Returns parsed JSON if the paid request succeeds, or null if still rejected.
+   * Returns parsed JSON if the paid request succeeds, or the X402_PAYMENT_REJECTED
+   * sentinel if the server cleanly, legibly rejected it without settling.
+   * Throws a NansenError(PAYMENT_AMBIGUOUS) — instead of returning the sentinel —
+   * for any outcome that doesn't prove the payment was rejected: a transport
+   * failure after transmission, an HTTP 5xx, or a response body that can't be
+   * parsed. In all of those cases the server may already have received and
+   * settled the payment, so the caller must not treat it as safe to retry with
+   * a different option — that would risk paying twice for the same request.
    * Logs the payment and warns about low balance when walletLabel and network are given.
    *
    * @param {string} signature - Payment-Signature header value
@@ -539,7 +557,7 @@ export class NansenAPI {
    * @param {string} url - Request URL
    * @param {object} body - Request body (will be cleaned)
    * @param {object} [options={}] - Request options (may include .method, .headers)
-   * @returns {Promise<object|null>} Parsed JSON on success, null if rejected
+   * @returns {Promise<object|typeof X402_PAYMENT_REJECTED>}
    *
    * TODO: full fix — extract the entire x402 provider dispatch from request() into
    * an attemptX402Payment() method so adding a new payment provider only requires
@@ -550,21 +568,52 @@ export class NansenAPI {
     // POST burned a payment signature then hit the wrong route for GET/DELETE/PATCH.
     const method = options.method || 'POST';
     const isGet = method === 'GET';
-    const paidResponse = await fetch(url, {
-      method,
-      redirect: 'error',
-      headers: {
-        ...(!isGet && { 'Content-Type': 'application/json' }),
-        'X-Client-Type': 'nansen-cli',
-        'X-Client-Version': packageVersion,
-        ...telemetryHeaders(),
-        'Payment-Signature': signature,
-        ...this.defaultHeaders,
-        ...options.headers,
-      },
-      ...(!isGet && method !== 'DELETE' && { body: JSON.stringify(NansenAPI.cleanBody(body)) }),
-    });
-    if (!paidResponse.ok) return null;
+    let paidResponse;
+    try {
+      paidResponse = await fetch(url, {
+        method,
+        redirect: 'error',
+        headers: {
+          ...(!isGet && { 'Content-Type': 'application/json' }),
+          'X-Client-Type': 'nansen-cli',
+          'X-Client-Version': packageVersion,
+          ...telemetryHeaders(),
+          'Payment-Signature': signature,
+          ...this.defaultHeaders,
+          ...options.headers,
+        },
+        ...(!isGet && method !== 'DELETE' && { body: JSON.stringify(NansenAPI.cleanBody(body)) }),
+      });
+    } catch (err) {
+      // The signature was already on the wire when the connection failed —
+      // the server may have received and settled it before we lost the
+      // response. Fail closed rather than let the caller sign and send a
+      // second payment for the same logical request.
+      throw new NansenError(
+        `x402 payment outcome unknown: request failed after the signed payment was transmitted (${err.message}). Not attempting another payment for the same request.`,
+        ErrorCode.PAYMENT_AMBIGUOUS,
+      );
+    }
+    if (!paidResponse.ok) {
+      // A 5xx doesn't prove the payment was rejected — the server could have
+      // processed it before failing to respond. Only a readable non-5xx
+      // rejection body is safe to treat as "try the next option".
+      if (paidResponse.status >= 500) {
+        throw new NansenError(
+          `x402 payment outcome unknown: server returned ${paidResponse.status} after the signed payment was transmitted. Not attempting another payment for the same request.`,
+          ErrorCode.PAYMENT_AMBIGUOUS,
+        );
+      }
+      try {
+        await paidResponse.json();
+      } catch (err) {
+        throw new NansenError(
+          `x402 payment outcome unknown: rejection response body was unreadable (${err.message}). Not attempting another payment for the same request.`,
+          ErrorCode.PAYMENT_AMBIGUOUS,
+        );
+      }
+      return X402_PAYMENT_REJECTED;
+    }
     if (walletLabel) {
       console.error(`[x402] Paid via ${walletLabel}${network ? ` (${network})` : ''}`);
     }
@@ -577,7 +626,18 @@ export class NansenAPI {
         }
       } catch { /* balance check is best-effort */ }
     }
-    const data = await paidResponse.json();
+    let data;
+    try {
+      data = await paidResponse.json();
+    } catch (err) {
+      // The payment was accepted (2xx) — it settled. We just can't read the
+      // response body, so surface that plainly rather than silently treating
+      // it as a rejection and paying again.
+      throw new NansenError(
+        `x402 payment succeeded but its response body was unreadable (${err.message}). The payment was not repeated.`,
+        ErrorCode.PAYMENT_AMBIGUOUS,
+      );
+    }
     const meta = readResponseMeta(paidResponse);
     this.lastResponseMeta = meta;
     if (meta && data !== null && typeof data === 'object') data[RESPONSE_META] = meta;
@@ -712,9 +772,14 @@ export class NansenAPI {
                 const { createPrivyPaymentSignatures } = await import('./privy.js');
                 for await (const { signature, network } of createPrivyPaymentSignatures(response, url)) {
                   const result = await this._x402Retry(signature, `Privy wallet ${defaultWalletName}`, network, url, body, options);
-                  if (result !== null) return result;
+                  if (result !== X402_PAYMENT_REJECTED) return result;
                 }
               } catch (privyErr) {
+                // An ambiguous outcome (transport failure, 5xx, unreadable body)
+                // after a signed payment was already transmitted must not be
+                // treated as an ordinary payment failure — there is no other
+                // provider to fall back to here, and retrying could double-pay.
+                if (privyErr instanceof NansenError && privyErr.code === ErrorCode.PAYMENT_AMBIGUOUS) throw privyErr;
                 message = `x402 Privy payment failed: ${privyErr.message}`;
               }
             } else {
@@ -724,10 +789,17 @@ export class NansenAPI {
                 const { createPaymentSignatures } = await import('./x402.js');
                 for await (const { signature, network, asset } of createPaymentSignatures(response, url)) {
                   const result = await this._x402Retry(signature, `local wallet ${defaultWalletName}`, network, url, body, options, asset);
-                  if (result !== null) return result;
-                  // This payment option was rejected, try next
+                  if (result !== X402_PAYMENT_REJECTED) return result;
+                  // This payment option was cleanly rejected without settling, try next
                 }
-              } catch { /* local wallet unavailable, try WalletConnect */ }
+              } catch (localErr) {
+                // An ambiguous outcome here means a signed payment may already
+                // be in flight or settled server-side. Do NOT fall through to
+                // WalletConnect below — that would sign and transmit a second,
+                // independent payment authorization for the same request.
+                if (localErr instanceof NansenError && localErr.code === ErrorCode.PAYMENT_AMBIGUOUS) throw localErr;
+                /* local wallet unavailable for any other reason, try WalletConnect */
+              }
 
               // 2. Fall back to WalletConnect (walletconnect-x402.js)
               {
@@ -749,8 +821,13 @@ export class NansenAPI {
                     const { handleX402Payment } = await import('./walletconnect-x402.js');
                     const paymentSignature = await handleX402Payment(paymentRequirements);
                     const result = await this._x402Retry(paymentSignature, 'WalletConnect', null, url, body, options);
-                    if (result !== null) return result;
+                    if (result !== X402_PAYMENT_REJECTED) return result;
                   } catch (x402Err) {
+                    // WalletConnect is the last resort in this chain — an
+                    // ambiguous outcome here still must not be reported as an
+                    // ordinary "payment failed" that invites the caller to
+                    // retry the whole request (and sign yet another payment).
+                    if (x402Err instanceof NansenError && x402Err.code === ErrorCode.PAYMENT_AMBIGUOUS) throw x402Err;
                     if (!this.apiKey) {
                       message = 'No API key configured. Three ways to authenticate:\n' +
                         '  1. API key: run `nansen login --human` or set NANSEN_API_KEY (get key at https://app.nansen.ai/auth/agent-setup)\n' +
@@ -834,6 +911,16 @@ export class NansenAPI {
     return this.request('/api/v1/account', {}, { method: 'GET', cache: false });
   }
 
+  // ============= Chain Endpoints =============
+
+  async chainRank(params = {}) {
+    const { timeFrame = 7, chainType = 'all' } = params;
+    return this.request('/api/v1/chains/chain-rank', {
+      time_frame: timeFrame,
+      chain_type: chainType
+    });
+  }
+
   // ============= Smart Money Endpoints =============
   
   async smartMoneyNetflow(params = {}) {
@@ -896,6 +983,17 @@ export class NansenAPI {
     });
   }
 
+  async smartMoneyPnlLeaderboard(params = {}) {
+    const { chains = ['solana'], timeframe = 7, filters = {}, orderBy, pagination } = params;
+    return this.request('/api/v1/smart-money/pnl-leaderboard', {
+      chains,
+      timeframe,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
   // ============= Profiler Endpoints =============
 
   async addressBalance(params = {}) {
@@ -921,6 +1019,16 @@ export class NansenAPI {
     });
   }
 
+  async addressPremiumLabels(params = {}) {
+    const { address, chain = 'all', pagination = { page: 1, per_page: 100 } } = params;
+    if (address) requireValidAddress(address, chain);
+    return this.request('/api/v1/profiler/address/premium-labels', {
+      address,
+      chain,
+      pagination
+    });
+  }
+
   async addressTransactions(params = {}) {
     const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30, date } = params;
     if (address) requireValidAddress(address, chain);
@@ -970,6 +1078,10 @@ export class NansenAPI {
     return this.request('/api/v1/search/general', body);
   }
 
+  async tokenSectors() {
+    return this.request('/api/v1/search/token-sectors', {}, { method: 'GET' });
+  }
+
   async webSearch(params = {}) {
     const { queries, numResults = 10 } = params;
     if (!queries || queries.length === 0) {
@@ -1092,6 +1204,25 @@ export class NansenAPI {
     });
   }
 
+  async addressPerpPnlSummary(params = {}) {
+    const { address, fromDate, toDate } = params;
+    // HL addresses are EVM-format, so ethereum validation accepts every valid HL address
+    if (address) requireValidAddress(address, 'ethereum');
+    return this.request('/api/v1/profiler/perp-pnl-summary', {
+      address,
+      date: { from: fromDate, to: toDate }
+    });
+  }
+
+  async transactionWithTokenTransferLookup(params = {}) {
+    const { chain = 'ethereum', transactionHash, blockTimestamp } = params;
+    return this.request('/api/v1/transaction-with-token-transfer-lookup', {
+      chain,
+      transaction_hash: transactionHash,
+      block_timestamp: blockTimestamp
+    });
+  }
+
   // ============= Token God Mode Endpoints =============
 
   async tokenScreener(params = {}) {
@@ -1240,6 +1371,13 @@ export class NansenAPI {
     });
   }
 
+  async tokenPositionIntelligence(params = {}) {
+    const { tokenAddress } = params;
+    return this.request('/api/v1/tgm/position-intelligence', {
+      token_address: tokenAddress
+    });
+  }
+
   async tokenPerpPnlLeaderboard(params = {}) {
     const { tokenSymbol, filters = {}, orderBy, pagination, days = 30, withLabels } = params;
     const body = {
@@ -1632,6 +1770,29 @@ export class NansenAPI {
     });
   }
 
+  async researchHistoricalTokenOhlcv(params = {}) {
+    const { chain = 'solana', tokenAddress, fromDate, asOfDate, asOfTs, timeframe, applyBlacklistFilter } = params;
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
+    if (!fromDate) {
+      throw new NansenError('fromDate is required', ErrorCode.MISSING_PARAM);
+    }
+    if (asOfDate && asOfTs) {
+      throw new NansenError('asOfDate and asOfTs are mutually exclusive', ErrorCode.INVALID_PARAMS);
+    }
+    if (!asOfDate && !asOfTs) {
+      throw new NansenError('One of asOfDate or asOfTs is required', ErrorCode.MISSING_PARAM);
+    }
+    return this.request('/api/v1beta1/tgm/historical-token-ohlcv', {
+      chain,
+      token_address: tokenAddress,
+      date_from: fromDate,
+      as_of_date: asOfDate,
+      as_of_ts: asOfTs,
+      timeframe,
+      apply_blacklist_filter: applyBlacklistFilter
+    });
+  }
+
   // ============= Smart Alert Endpoints =============
 
   async alertsList(params = {}) {

package/src/bridge.js

@@ -1077,6 +1077,56 @@ export async function resolveEvmStepFees(chain, txData, overrides = {}) {
   return { gasPrice: await evmRpcCall(chain, 'eth_gasPrice') };
 }
 
+// eth_sendRawTransaction JSON-RPC error messages that PROVE the tx never
+// entered the mempool: the node rejected it during validation, so nothing is in
+// flight and the quote stays reusable. Matched case-insensitively as substrings
+// of the node's error text. Every entry here must be UNAMBIGUOUSLY pre-broadcast
+// across EVM node implementations. Everything NOT listed fails closed — crucially
+// the txpool states ("already known", "known transaction", "already imported",
+// "nonce too low", "replacement transaction underpriced") that mean a tx is
+// ALREADY in flight; treating those as safe rejections would let a re-execute
+// sign a fresh nonce and broadcast a second bridge tx.
+//
+// Deliberately EXCLUDED: the bare "transaction underpriced". On go-ethereum /
+// op-geth (which is what Base — today's only EVM bridge chain — runs) it means a
+// fresh too-low-fee tx that was never accepted, i.e. safe. But some other nodes
+// (certain Besu / Nethermind versions) reuse that same bare message for a failed
+// REPLACEMENT (a nonce collision with an in-flight tx). Since the allowlist is
+// not chain-scoped and processEvmStep runs for whatever CHAIN_RPCS resolves, we
+// fail closed on it rather than risk a future non-geth chain misclassifying an
+// in-flight tx as safe. Cost is at most a needless re-quote.
+const PRE_BROADCAST_SEND_ERRORS = [
+  'insufficient funds',
+  'intrinsic gas too low',
+  'gas too low',
+  'exceeds block gas limit',
+  'exceeds the block gas limit',
+  'max fee per gas less than block base fee',
+  'fee cap less than block base fee',
+  'max priority fee per gas higher than max fee per gas',
+  'invalid sender',
+  'invalid signature',
+  'could not decode',
+  'rlp: ', // geth's RLP decode errors ("rlp: input string too long", …); the
+           // trailing space avoids matching "rlp" embedded in an unrelated message
+  'negative value',
+];
+
+// True when we are CONFIDENT a failed send never put the tx into the mempool, so
+// the bridge quote may be retried. This is deliberately NARROW: a definitive
+// answer requires a JSON-RPC rejection (RPC_JSON_ERROR) whose message is on the
+// pre-broadcast allowlist, or a missing-RPC config error (the request never
+// left this process). A transport/HTTP failure, or ANY other JSON-RPC error
+// (including in-flight txpool states and the cross-node-ambiguous bare
+// "transaction underpriced"), is treated as unsafe and must fail closed — see
+// evmRpcCall (trading.js) for the error codes.
+function isPreBroadcastSendRejection(err) {
+  if (err?.code === 'RPC_UNCONFIGURED') return true;
+  if (err?.code !== 'RPC_JSON_ERROR') return false;
+  const msg = (err.message || '').toLowerCase();
+  return PRE_BROADCAST_SEND_ERRORS.some(pattern => msg.includes(pattern));
+}
+
 async function processEvmStep(step, { chain, privateKeyHex, signerAddress, log, onBroadcast, feeOverrides, nonceSequence, intent }) {
   for (const item of step.items || []) {
     if (item.status === 'complete') continue;
@@ -1114,7 +1164,20 @@ async function processEvmStep(step, { chain, privateKeyHex, signerAddress, log,
     );
 
     log(`  Broadcasting ${step.id} on ${chain}...`);
-    const txHash = await evmRpcCall(chain, 'eth_sendRawTransaction', [signedTx]);
+    let txHash;
+    try {
+      txHash = await evmRpcCall(chain, 'eth_sendRawTransaction', [signedTx]);
+    } catch (sendErr) {
+      // Fail closed UNLESS we're confident the tx never entered the mempool (a
+      // pre-broadcast validation rejection, or no RPC configured). Everything
+      // else — a lost ack, a gateway error, OR an in-flight txpool state like
+      // "already known" / "nonce too low" that a node reports as a JSON-RPC
+      // error — may already be broadcasting, so mark the quote spent before
+      // rethrowing to abort, so a later re-execute can't re-sign this step at a
+      // fresh nonce and double-broadcast.
+      if (!isPreBroadcastSendRejection(sendErr)) onBroadcast?.(step.id, null);
+      throw sendErr;
+    }
     // In flight now: record it before waiting on the receipt, because a receipt
     // timeout must not leave the quote reusable.
     onBroadcast?.(step.id, txHash);
@@ -1158,7 +1221,16 @@ async function processSignatureStepLocal(step, { privateKeyHex, log, apiInstance
       }
 
       log(`  Signing ${step.id} (EIP-712)...`);
-      await postBridgeExecute(apiInstance, targetUrl, postBody);
+      // Fail closed on ANY submit failure: the proxy may have forwarded the
+      // authorization before the error surfaced, and we can't tell that from a
+      // clean pre-forward rejection. Consume the quote before rethrowing so a
+      // re-execute can't resubmit this leg.
+      try {
+        await postBridgeExecute(apiInstance, targetUrl, postBody);
+      } catch (sendErr) {
+        onBroadcast?.(step.id, null);
+        throw sendErr;
+      }
       onBroadcast?.(step.id, null);
       log(`  Submitted to ${new URL(targetUrl).hostname}`);
     } else if (signData.action) {
@@ -1196,7 +1268,17 @@ async function processSignatureStepLocal(step, { privateKeyHex, log, apiInstance
       };
 
       log(`  Signing ${step.id} (Hyperliquid deposit)...`);
-      const result = await postBridgeExecute(apiInstance, 'https://api.hyperliquid.xyz/exchange', hlBody);
+      // Fail closed if the SUBMIT itself throws (transport/proxy error — HL may
+      // still have received the action). A clean HL rejection instead returns
+      // 200 and is caught by assertHyperliquidStepAccepted below, OUTSIDE this
+      // try: that is a definitive no-op, so it must NOT consume the quote.
+      let result;
+      try {
+        result = await postBridgeExecute(apiInstance, 'https://api.hyperliquid.xyz/exchange', hlBody);
+      } catch (sendErr) {
+        onBroadcast?.(step.id, null);
+        throw sendErr;
+      }
       assertHyperliquidStepAccepted(result, step.id);
       onBroadcast?.(step.id, null);
       log(`  Submitted to api.hyperliquid.xyz`);
@@ -1270,7 +1352,14 @@ async function processSignatureStepPrivy(step, { privyClient, walletId, log, api
       } else {
         postBody.signature = signature;
       }
-      await postBridgeExecute(apiInstance, targetUrl, postBody);
+      // Fail closed on any submit failure — see the local path for the rationale
+      // (an ambiguous forward must not leave the quote reusable).
+      try {
+        await postBridgeExecute(apiInstance, targetUrl, postBody);
+      } catch (sendErr) {
+        onBroadcast?.(step.id, null);
+        throw sendErr;
+      }
       onBroadcast?.(step.id, null);
     } else {
       const [rHex, sHex, vHex] = [signature.slice(2, 66), signature.slice(66, 130), signature.slice(130, 132)];
@@ -1279,7 +1368,16 @@ async function processSignatureStepPrivy(step, { privyClient, walletId, log, api
         nonce: signData.nonce,
         signature: { r: '0x' + rHex, s: '0x' + sHex, v: parseInt(vHex, 16) },
       };
-      const result = await postBridgeExecute(apiInstance, 'https://api.hyperliquid.xyz/exchange', hlBody);
+      // Submit-throw = ambiguous → fail closed; a clean HL rejection returns 200
+      // and is caught by assertHyperliquidStepAccepted (outside the try) as a
+      // definitive no-op that must NOT consume the quote.
+      let result;
+      try {
+        result = await postBridgeExecute(apiInstance, 'https://api.hyperliquid.xyz/exchange', hlBody);
+      } catch (sendErr) {
+        onBroadcast?.(step.id, null);
+        throw sendErr;
+      }
       assertHyperliquidStepAccepted(result, step.id);
       onBroadcast?.(step.id, null);
     }