nansen-cli 1.39.0 → 1.40.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 1.40.1
+
+### Patch Changes
+
+- [#516](https://github.com/nansen-ai/nansen-cli/pull/516) [`48722ef`](https://github.com/nansen-ai/nansen-cli/commit/48722ef0c7e6c0a7ce8c4c026245afb6e6f47e79) Thanks [@kome12](https://github.com/kome12)! - Fix cross-chain bridges into native SOL being refused at execute time. The quote/intent binding compared the wrapped-SOL mint (how `--to SOL` resolves) against the System Program address that aggregators use as the native-SOL sentinel and rejected them as different tokens. Both spellings are now treated as the same asset.
+
+## 1.40.0
+
+### Minor Changes
+
+- [#509](https://github.com/nansen-ai/nansen-cli/pull/509) [`430c300`](https://github.com/nansen-ai/nansen-cli/commit/430c3003d28a44bd1bfb123eef9290a7350a7e1e) Thanks [@kome12](https://github.com/kome12)! - `trade execute` now revokes an existing on-chain ERC-20 allowance before
+  re-approving when it is more than 10x the current trade's scoped amount, such
+  as a legacy unlimited approval or an allowance granted by another app. Most
+  trades are unaffected. Opt out with `--no-revoke-excessive-allowance`.
+
+  After each revoke or reapproval, the CLI reads the resulting allowance back
+  on-chain and fails closed (instead of proceeding to the swap) if it doesn't
+  match what was expected or can't be read.
+
+### Patch Changes
+
+- [#498](https://github.com/nansen-ai/nansen-cli/pull/498) [`a964dd1`](https://github.com/nansen-ai/nansen-cli/commit/a964dd19c826f5231d2651547212d8169a74e7fe) Thanks [@crazywriter1](https://github.com/crazywriter1)! - Use `pending` nonce block tag for EVM sends: back-to-back transfers no longer risk reusing the same nonce when mempool transactions are queued.
+
+- [#493](https://github.com/nansen-ai/nansen-cli/pull/493) [`bc89fef`](https://github.com/nansen-ai/nansen-cli/commit/bc89fef74489da3df32a12079effbdfa899373fd) Thanks [@crazywriter1](https://github.com/crazywriter1)! - Validate `--slippage-bps` on `limit-order create`: values outside 0-10000 now fail with a clear error before any auth/API call.
+
 ## 1.39.0
 
 ### Minor Changes

package/package.json

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

package/src/cli.js

@@ -190,7 +190,7 @@ export function parseArgs(args) {
       const key = arg.slice(2);
       const next = args[i + 1];
       
-      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full' || key === 'human' || key === 'enabled' || key === 'disabled' || key === 'expert' || key === 'json' || key === 'offline') {
+      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full' || key === 'human' || key === 'enabled' || key === 'disabled' || key === 'expert' || key === 'json' || key === 'offline' || key === 'no-simulate' || key === 'no-verify-outcome' || key === 'no-revoke-excessive-allowance') {
         result.flags[key] = true;
       } else if (next && (!next.startsWith('-') || /^-\d/.test(next))) {
         // Try to parse as JSON first (for objects/arrays/booleans),

package/src/limit-order.js

@@ -401,6 +401,17 @@ export function parseExpiry(expiryStr) {
   throw new Error(`Invalid expiry format: "${expiryStr}". Use "24h", "7d", "30d", or epoch ms.`);
 }
 
+// Whole integer bps in [0, 10000], matching bridge parseSlippageBps.
+// Number() would accept "1.5", "1e2", "0x10", and boolean true.
+function parseSlippageBps(raw) {
+  const s = String(raw).trim();
+  const bad = 'Error: --slippage-bps must be a whole integer between 0 and 10000 basis points.';
+  if (!/^\d+$/.test(s)) throw new Error(bad);
+  const n = parseInt(s, 10);
+  if (!Number.isInteger(n) || n < 0 || n > 10000) throw new Error(bad);
+  return n;
+}
+
 // ============= Order Formatting =============
 
 function formatOrderStatus(status) {
@@ -501,7 +512,7 @@ export function buildLimitOrderCommands(deps = {}) {
       const triggerPrice = options['trigger-price'];
       const triggerCondition = options['trigger-condition'];
       const triggerMintRaw = options['trigger-mint'];
-      const slippageBps = options['slippage-bps'] != null ? Number(options['slippage-bps']) : undefined;
+      const slippageBpsRaw = options['slippage-bps'];
       const expiresStr = options.expires || '30d';
       const walletName = options.wallet;
 
@@ -516,7 +527,7 @@ OPTIONS:
   --trigger-mint <symbol|addr>   Token whose price triggers the order (e.g. SOL)
   --trigger-condition <cond>     "above" or "below"
   --trigger-price <usd>          Trigger price in USD (must be a positive number)
-  --slippage-bps <bps>               Slippage in basis points (100 = 1%), omit for auto
+  --slippage-bps <bps>           Whole integer bps, 0-10000 (100 = 1%), omit for auto
   --expires <duration>           Expiry duration: "24h", "7d", "30d" (default: 30d)
   --wallet <name>                Wallet name (or "walletconnect"/"wc")
 
@@ -581,6 +592,18 @@ EXAMPLES:
         return;
       }
 
+      // Same bounds as update / bridge: whole-integer bps in 0–10000.
+      let slippageBps;
+      if (slippageBpsRaw != null) {
+        try {
+          slippageBps = parseSlippageBps(slippageBpsRaw);
+        } catch (err) {
+          log(err.message);
+          exit(1);
+          return;
+        }
+      }
+
       let expiresAt;
       try {
         expiresAt = parseExpiry(expiresStr);
@@ -820,7 +843,7 @@ Usage: nansen trade limit-order update --order <orderId> [--trigger-price <usd>]
 OPTIONS:
   --order <id>            Order ID to update
   --trigger-price <usd>   New trigger price in USD
-  --slippage-bps <bps>    Slippage in basis points (100 = 1%)
+  --slippage-bps <bps>    Whole integer bps, 0-10000 (100 = 1%)
   --wallet <name>         Wallet name (or "walletconnect"/"wc")
 
 NOTE: Only provided fields are updated. Auto slippage can only be set at creation time
@@ -850,13 +873,13 @@ EXAMPLES:
         updateBody.triggerPriceUsd = price;
       }
       if (slippageBps != null) {
-        const bps = Number(slippageBps);
-        if (isNaN(bps) || bps < 0 || bps > 10000) {
-          log('Error: --slippage-bps must be between 0 and 10000 basis points.');
+        try {
+          updateBody.slippageBps = parseSlippageBps(slippageBps);
+        } catch (err) {
+          log(err.message);
           exit(1);
           return;
         }
-        updateBody.slippageBps = bps;
       }
 
       try {

package/src/schema.json

@@ -1625,6 +1625,10 @@
             "no-verify-outcome": {
               "type": "boolean",
               "description": "Skip EVM swap-outcome verification. That check simulates the swap and confirms the wallet's balance changes match the quote (input spent within your max, expected output received, no other token moved) before broadcasting; it needs a simulation-capable endpoint (NANSEN_BASE_SIM_RPC) and degrades with a warning when none is available. No effect on Solana."
+            },
+            "no-revoke-excessive-allowance": {
+              "type": "boolean",
+              "description": "Skip revoking an existing on-chain ERC-20 allowance before re-approving when it exceeds 10x this trade's scoped amount. By default, an oversized or legacy allowance is revoked to zero and a fresh trade-scoped allowance is granted. WalletConnect users will see separate wallet prompts for the revoke and re-approval."
             }
           }
         },
@@ -1690,7 +1694,7 @@
                 },
                 "slippage-bps": {
                   "type": "number",
-                  "description": "Slippage tolerance in basis points (e.g. 50 = 0.5%)"
+                  "description": "Slippage as a whole integer in basis points, 0-10000 (50 = 0.5%), omit for auto"
                 },
                 "expires": {
                   "type": "string",
@@ -1779,7 +1783,7 @@
                 },
                 "slippage-bps": {
                   "type": "number",
-                  "description": "New slippage in basis points (0-10000)"
+                  "description": "New slippage as a whole integer in basis points (0-10000)"
                 },
                 "wallet": {
                   "type": "string",

package/src/trade-validation.js

@@ -122,6 +122,17 @@ const NATIVE_TOKEN_ADDRESSES = {
   base: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
 };
 
+// Native SOL has two on-chain spellings that denote the same asset: the
+// canonical wrapped-SOL mint (what the CLI resolves `SOL` to and persists as
+// the request intent) and the System Program address that aggregators and
+// bridges (e.g. Relay) use as the native-lamport sentinel in their quotes.
+// tokensEqual treats them as equivalent so the intent-binding check doesn't
+// false-reject a legitimate quote that names native SOL the other way.
+const SOLANA_NATIVE_SOL_ALIASES = new Set([
+  'So11111111111111111111111111111111111111112', // wrapped SOL mint
+  '11111111111111111111111111111111', // System Program — native SOL sentinel
+]);
+
 // USDC contract addresses per chain.
 const USDC_ADDRESSES = {
   solana: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
@@ -437,7 +448,8 @@ export function assertValidApprovalSpender(spender) {
  *
  * Guarantees on the returned string:
  *   - spender is a valid 20-byte address (see assertValidApprovalSpender)
- *   - amount is a positive integer strictly below MAX_UINT256 (never unlimited)
+ *   - amount is a positive integer strictly below MAX_UINT256 (never unlimited),
+ *     unless `allowZero` is explicitly set for a revoke-to-zero approval
  *   - amount does not exceed `maxAllowance` when the caller supplies one
  *     (the user's persisted request intent — see assertQuoteMatchesRequest)
  *   - the encoded calldata is exactly 68 bytes (4-byte selector + two 32-byte
@@ -447,9 +459,10 @@ export function assertValidApprovalSpender(spender) {
  * @param {bigint|string|number} amount - Allowance in base units
  * @param {object} [opts]
  * @param {bigint|string|number} [opts.maxAllowance] - Hard cap from request intent
+ * @param {boolean} [opts.allowZero=false] - Allow encoding a zero-amount revoke approval
  * @returns {string} 0x-prefixed approve() calldata (exactly 68 bytes)
  */
-export function encodeApproveCalldata(spender, amount, { maxAllowance } = {}) {
+export function encodeApproveCalldata(spender, amount, { maxAllowance, allowZero = false } = {}) {
   assertValidApprovalSpender(spender);
 
   let amt;
@@ -458,7 +471,7 @@ export function encodeApproveCalldata(spender, amount, { maxAllowance } = {}) {
   } catch {
     throw new Error(`Approval amount is not an integer (${amount}). Refusing to sign an approval.`);
   }
-  if (amt <= 0n) {
+  if (amt < 0n || (amt === 0n && !allowZero)) {
     throw new Error(`Approval amount must be positive (got ${amt}). Refusing to sign an approval.`);
   }
   if (amt >= MAX_UINT256) {
@@ -544,6 +557,23 @@ export function approvalAmountForSwap({ inputAmount, swapMode, slippage }) {
   return amt;
 }
 
+// Existing allowances above this multiple of the current trade's scoped amount
+// are treated as stale/oversized rather than reusable dust from a prior swap.
+export const OVERSIZED_ALLOWANCE_MULTIPLIER = 10n;
+
+/**
+ * Decide whether an existing on-chain ERC-20 allowance should be revoked before
+ * granting the current trade's scoped approval.
+ *
+ * @param {bigint} existingAllowance - Current on-chain allowance
+ * @param {bigint} approveAmt - This trade's scoped approval amount
+ * @returns {boolean}
+ */
+export function needsAllowanceRevoke(existingAllowance, approveAmt) {
+  if (approveAmt <= 0n) return false;
+  return existingAllowance > approveAmt * OVERSIZED_ALLOWANCE_MULTIPLIER;
+}
+
 // ============= Quote vs. request-intent revalidation =============
 
 /**
@@ -552,7 +582,11 @@ export function approvalAmountForSwap({ inputAmount, swapMode, slippage }) {
  */
 function tokensEqual(a, b, chain) {
   if (!a || !b) return false;
-  if (chain === 'solana') return a === b;
+  if (chain === 'solana') {
+    // Both sides naming native SOL (in either spelling) is a match.
+    if (SOLANA_NATIVE_SOL_ALIASES.has(a) && SOLANA_NATIVE_SOL_ALIASES.has(b)) return true;
+    return a === b;
+  }
   return a.toLowerCase() === b.toLowerCase();
 }
 

package/src/trading.js

@@ -13,7 +13,7 @@ import { base58Decode } from './transfer.js';
 import { keccak256, signSecp256k1, rlpEncode } from './crypto.js';
 import { getWalletConnectAddress, sendTransactionViaWalletConnect, sendSolanaTransactionViaWalletConnect, sendApprovalViaWalletConnect } from './walletconnect-trading.js';
 import { retrievePassword } from './keychain.js';
-import { validateQuoteInput, validateBalance, resolvePercentAmount, validateGasBalance, encodeApproveCalldata, assertValidApprovalSpender, assertQuoteMatchesRequest, assertSwapCalldataNotBareTransfer, assertSwapOutcome, approvalAmountForSwap } from './trade-validation.js';
+import { validateQuoteInput, validateBalance, resolvePercentAmount, validateGasBalance, encodeApproveCalldata, assertValidApprovalSpender, assertQuoteMatchesRequest, assertSwapCalldataNotBareTransfer, assertSwapOutcome, approvalAmountForSwap, needsAllowanceRevoke, OVERSIZED_ALLOWANCE_MULTIPLIER } from './trade-validation.js';
 import { CHAIN_RPCS } from './rpc-urls.js';
 import { simulateAssetChanges, SwapSimulationError, hasSimulationRpc } from './swap-simulation.js';
 import { packageVersion, CommandError, telemetryHeaders, loadConfig } from './api.js';
@@ -451,11 +451,10 @@ export function cleanupQuotes() {
 
 // ============= Transaction Signing =============
 
-// ----------------------------------------------------------------
-// TODO: SECURITY REVIEW REQUIRED
-// The signing functions below construct and sign raw transactions.
-// They MUST be audited before any production/mainnet use.
-// ----------------------------------------------------------------
+// The signing functions below construct and sign raw transactions from quote
+// data. The authorization checks that make them safe to call live upstream:
+// assertQuoteMatchesRequest, assertSwapCalldataNotBareTransfer, scoped ERC-20
+// approvals, and the approval target/amount validators in trade-validation.js.
 
 /**
  * Sign a Solana transaction from quote data.
@@ -527,7 +526,8 @@ export function signSolanaTransaction(transactionBase64, privateKeyHex) {
  * @param {number} nonce - Account nonce
  * @returns {string} 0x-prefixed signed transaction hex
  */
-// ⚠️ SECURITY: EVM transaction signing - requires thorough review before production use
+// Pure EVM encode/sign primitive. Quote authorization and request-intent binding
+// happen upstream before this function receives transaction calldata.
 export function signEvmTransaction(txData, privateKeyHex, chain, nonce) {
   const chainConfig = CHAIN_MAP[chain];
   if (!chainConfig || chainConfig.type !== 'evm') {
@@ -802,26 +802,130 @@ export async function estimateEvmGas(chain, { from, to, data, value }) {
   }
 }
 
+/**
+ * Read the current on-chain ERC-20 allowance, throwing on any RPC failure
+ * instead of masking it. checkErc20Allowance below wraps this with a
+ * catch-to-0 fallback for the pre-trade check (safe there, since a follow-up
+ * approve() overwrites whatever the prior value was); post-action
+ * verification needs the raw, fail-closed read instead.
+ */
+async function readErc20AllowanceOrThrow(chain, tokenAddress, ownerAddress, spenderAddress) {
+  if (!CHAIN_RPCS[chain]) throw new Error(`no RPC configured for chain ${chain}`);
+  // allowance(address,address) selector = 0xdd62ed3e
+  const data = '0xdd62ed3e'
+    + ownerAddress.slice(2).toLowerCase().padStart(64, '0')
+    + spenderAddress.slice(2).toLowerCase().padStart(64, '0');
+  const result = await evmRpcCall(chain, 'eth_call', [{ to: tokenAddress, data }, 'latest']);
+  if (!/^0x[0-9a-fA-F]{64}$/.test(result || '')) {
+    throw new Error(`invalid allowance() return data: ${result || '<empty>'}`);
+  }
+  return BigInt(result);
+}
+
 /**
  * Check ERC-20 allowance for a given owner/spender pair.
  * Returns the allowance as a BigInt, or 0n on failure.
  */
 export async function checkErc20Allowance(chain, tokenAddress, ownerAddress, spenderAddress) {
-  if (!CHAIN_RPCS[chain]) return 0n;
-
   try {
-    // allowance(address,address) selector = 0xdd62ed3e
-    const data = '0xdd62ed3e'
-      + ownerAddress.slice(2).toLowerCase().padStart(64, '0')
-      + spenderAddress.slice(2).toLowerCase().padStart(64, '0');
-    const result = await evmRpcCall(chain, 'eth_call', [{ to: tokenAddress, data }, 'latest']);
-    if (!result) return 0n;
-    return BigInt(result);
-  } catch {
+    return await readErc20AllowanceOrThrow(chain, tokenAddress, ownerAddress, spenderAddress);
+  } catch (err) {
+    // Treat an unreadable allowance as 0 so the caller re-approves a fresh scoped
+    // amount (a normal approve() overwrites any real on-chain allowance) rather
+    // than trusting a value we couldn't verify. Surface it so a persistent RPC
+    // problem — which would otherwise silently skip the excessive-allowance
+    // revoke — isn't invisible.
+    process.stderr.write(`⚠️  Could not read ERC-20 allowance on ${chain} (${err.message}); treating as 0.\n`);
     return 0n;
   }
 }
 
+/**
+ * A successful receipt only proves the revoke/approval call didn't revert —
+ * not that approve() actually produced the allowance we expect (a
+ * non-standard token or a race with another approval could still leave the
+ * wrong value on-chain). Poll the allowance a few times before failing
+ * closed: an `eth_call` at 'latest' immediately after a receipt can hit an
+ * RPC node that hasn't caught up with the just-mined block yet and read
+ * stale pre-transaction state — confirmed live (PR #509 review follow-up)
+ * against a real Base approval that read back as unset for several seconds
+ * after its receipt landed, then correctly as the approved amount once the
+ * node caught up.
+ */
+const ALLOWANCE_VERIFY_ATTEMPTS = 5;
+const DEFAULT_ALLOWANCE_VERIFY_DELAY_MS = 1500;
+const DEFAULT_POST_ALLOWANCE_TX_PROPAGATION_MS = 2000;
+let allowanceVerifyDelayMs = DEFAULT_ALLOWANCE_VERIFY_DELAY_MS;
+let postAllowanceTxPropagationMs = DEFAULT_POST_ALLOWANCE_TX_PROPAGATION_MS;
+
+export function __setAllowanceTimingForTests({
+  verifyDelayMs = DEFAULT_ALLOWANCE_VERIFY_DELAY_MS,
+  propagationDelayMs = DEFAULT_POST_ALLOWANCE_TX_PROPAGATION_MS,
+} = {}) {
+  if (process.env.NODE_ENV !== 'test' && !process.env.VITEST) {
+    throw new Error('__setAllowanceTimingForTests is for tests only');
+  }
+  allowanceVerifyDelayMs = verifyDelayMs;
+  postAllowanceTxPropagationMs = propagationDelayMs;
+}
+
+async function waitForAllowanceTxPropagation() {
+  // The receipt + allowance poll verifies token state, but the following swap
+  // still goes through a broadcaster/load-balanced RPC path. Give that path a
+  // short propagation window before signing the next dependent transaction.
+  if (postAllowanceTxPropagationMs <= 0) return;
+  await new Promise(r => setTimeout(r, postAllowanceTxPropagationMs));
+}
+
+async function pollAllowanceUntil(chain, tokenAddress, ownerAddress, spenderAddress, isExpected) {
+  let allowance, lastErr;
+  for (let attempt = 0; attempt < ALLOWANCE_VERIFY_ATTEMPTS; attempt++) {
+    if (attempt > 0 && allowanceVerifyDelayMs > 0) {
+      await new Promise(r => setTimeout(r, allowanceVerifyDelayMs));
+    }
+    try {
+      allowance = await readErc20AllowanceOrThrow(chain, tokenAddress, ownerAddress, spenderAddress);
+      lastErr = undefined;
+      if (isExpected(allowance)) return allowance;
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  if (lastErr) throw lastErr;
+  throw new Error(
+    `allowance did not reach expected state after ${ALLOWANCE_VERIFY_ATTEMPTS} attempts (last read: ${allowance})`,
+  );
+}
+
+function allowanceRevokeRecoveryHint(txHash) {
+  const txHint = txHash ? ` Tx: ${txHash}.` : '';
+  return `${txHint} Check the transaction on-chain, then retry this execute command or re-quote if needed.`;
+}
+
+async function assertAllowanceRevoked(chain, tokenAddress, ownerAddress, spenderAddress) {
+  let allowance;
+  try {
+    allowance = await pollAllowanceUntil(chain, tokenAddress, ownerAddress, spenderAddress, a => a === 0n);
+  } catch (err) {
+    throw new Error(`could not verify the allowance was cleared (${err.message})`, { cause: err });
+  }
+  if (allowance !== 0n) {
+    throw new Error(`allowance is still ${allowance}, not 0`);
+  }
+}
+
+async function assertAllowanceAtLeast(chain, tokenAddress, ownerAddress, spenderAddress, minAmount) {
+  let allowance;
+  try {
+    allowance = await pollAllowanceUntil(chain, tokenAddress, ownerAddress, spenderAddress, a => a >= minAmount);
+  } catch (err) {
+    throw new Error(`could not verify the approval took effect (${err.message})`, { cause: err });
+  }
+  if (allowance < minAmount) {
+    throw new Error(`allowance is ${allowance}, below the ${minAmount} this trade requires`);
+  }
+}
+
 // approvalAmountForSwap now lives in trade-validation.js alongside the approval
 // encoder and the spend-ceiling check that both consume it, so the "how much can
 // leave the wallet" math has a single definition. Re-exported here because the
@@ -851,6 +955,21 @@ export function approvalCapForQuote(quoteData) {
   return quoteData?.swapMode === 'exactOut' ? undefined : quoteData?.request?.amount;
 }
 
+// Decide what to do with a pre-existing on-chain allowance before a swap.
+// `shouldRevoke` describes the allowance ("it's oversized"), NOT the action taken:
+// callers use it both to gate the actual revoke (in the !reuseAllowance branch)
+// and to warn when reuse is forced by --no-revoke-excessive-allowance (in the
+// reuseAllowance branch). Note shouldRevoke ⟹ existingAllowance > approveAmt*10 ⟹
+// existingAllowance >= approveAmt, so with the flag set reuseAllowance is always
+// true and the revoke/"after revoking (now 0)" paths (all in the else branch) are
+// never reached spuriously — keep that invariant if you add branches here.
+function resolveAllowanceAction(existingAllowance, approveAmt, noRevokeExcessiveAllowance) {
+  const shouldRevoke = existingAllowance > 0n && needsAllowanceRevoke(existingAllowance, approveAmt);
+  const reuseAllowance = existingAllowance >= approveAmt && existingAllowance > 0n
+    && (noRevokeExcessiveAllowance || !shouldRevoke);
+  return { shouldRevoke, reuseAllowance };
+}
+
 export function assertCompleteEvmRequestIntent(request) {
   if (!request) {
     throw new Error('Quote is missing request intent. Re-quote with this CLI version before executing an EVM swap. Refusing to sign.');
@@ -969,10 +1088,15 @@ export function assertUsableSpender(spenderAddress) {
  * @param {string|number} gasPrice - Legacy gas price
  * @param {bigint|string|number} amount - Allowance to grant, in base units (see approvalAmountForSwap)
  * @param {bigint|string|number} [maxAllowance] - Hard cap from persisted request intent
+ * @param {object} [opts]
+ * @param {boolean} [opts.allowZero=false] - Allow a zero-amount revoke approval
  * @returns {string} 0x-prefixed signed approval tx hex
  */
-// ⚠️ SECURITY: ERC-20 approval signing - requires thorough review
-export function buildApprovalTransaction(tokenAddress, spenderAddress, privateKeyHex, chain, nonce, gasPrice, amount, maxAllowance) {
+// Approval signing is intentionally narrow: callers pass either the scoped swap
+// amount from approvalAmountForSwap or, for excessive-allowance cleanup, an
+// explicit allowZero revoke. encodeApproveCalldata validates the spender,
+// amount, optional request cap, and final ABI width before signing.
+export function buildApprovalTransaction(tokenAddress, spenderAddress, privateKeyHex, chain, nonce, gasPrice, amount, maxAllowance, { allowZero = false } = {}) {
   const chainConfig = CHAIN_MAP[chain];
   if (!chainConfig) throw new Error(`Unsupported chain: ${chain}`);
 
@@ -980,7 +1104,7 @@ export function buildApprovalTransaction(tokenAddress, spenderAddress, privateKe
   // can drain at most this one trade, never the wallet's full token balance.
   // encodeApproveCalldata enforces a valid 20-byte spender, a bounded (< MAX)
   // amount within the request cap, and exactly-68-byte calldata.
-  const data = encodeApproveCalldata(spenderAddress, amount, { maxAllowance });
+  const data = encodeApproveCalldata(spenderAddress, amount, { maxAllowance, allowZero });
 
   const tx = {
     nonce,
@@ -996,7 +1120,8 @@ export function buildApprovalTransaction(tokenAddress, spenderAddress, privateKe
 }
 
 // ============= Legacy (Type 0) EVM Transaction Signing =============
-// ⚠️ SECURITY: Legacy EVM transaction signing - requires thorough review before production use
+// Low-level RLP/secp256k1 signing primitive used after upstream quote and
+// allowance validation has already bounded what the transaction can authorize.
 
 /**
  * Strip all leading zero bytes from a buffer.
@@ -1848,6 +1973,7 @@ CROSS-CHAIN NOTES (when using --to-chain):
       const quoteId = options.quote || options['quote-id'] || args[0];
       const walletName = options.wallet;
       const noSimulate = flags['no-simulate'];
+      const noRevokeExcessiveAllowance = flags['no-revoke-excessive-allowance'];
       const noVerifyOutcome = flags['no-verify-outcome'];
       const gasless = Boolean(flags.gasless);
       // Read the API key for the swap-outcome sim endpoint. It's optional (the
@@ -1869,6 +1995,8 @@ OPTIONS:
   --wallet <name>           Wallet name (default: default wallet)
   --no-simulate             Skip pre-broadcast simulation (the eth_call revert check)
   --no-verify-outcome       Skip EVM swap-outcome verification (balance-delta check)
+  --no-revoke-excessive-allowance
+                            Skip auto-revoking an oversized/legacy allowance before re-approving
   --gasless                 Relay-only: have Relay's solver pay gas (no WalletConnect)
 
 EXAMPLES:
@@ -2086,9 +2214,64 @@ EXAMPLES:
                   chain, currentQuote.inputMint, walletAddress, currentQuote.approvalAddress
                 );
 
-                if (existingAllowance >= approveAmt && existingAllowance > 0n) {
+                const { shouldRevoke, reuseAllowance } = resolveAllowanceAction(existingAllowance, approveAmt, noRevokeExcessiveAllowance);
+                if (reuseAllowance) {
+                  if (noRevokeExcessiveAllowance && shouldRevoke) {
+                    log(`  ⚠ Existing allowance (${existingAllowance}) for ${quoteName} is excessive (>${OVERSIZED_ALLOWANCE_MULTIPLIER}x this trade), but --no-revoke-excessive-allowance was set`);
+                  }
                   log(`  ✓ Sufficient allowance exists for ${quoteName}, skipping approval`);
                 } else {
+                  const approvalMaxFee = currentQuote.transaction?.maxFeePerGas || currentQuote.transaction?.gasPrice || '1000000';
+                  const approvalPriorityFee = currentQuote.transaction?.maxPriorityFeePerGas || '1000000';
+
+                  if (shouldRevoke) {
+                    log(`  ⚠ Existing allowance (${existingAllowance}) for ${quoteName} is excessive (>${OVERSIZED_ALLOWANCE_MULTIPLIER}x this trade) — revoking before re-approving`);
+                    const revokeNonce = await getEvmNonce(chain, walletAddress);
+                    const revokeData = encodeApproveCalldata(currentQuote.approvalAddress, 0n, { allowZero: true });
+                    const revokeSignResult = await privyClient.signEvmTransaction(evmWalletId, {
+                      to: currentQuote.inputMint,
+                      data: revokeData,
+                      value: '0x0',
+                      chain_id: chainConfig.chainId,
+                      nonce: toHex(revokeNonce),
+                      gas_limit: toHex(100000),
+                      max_fee_per_gas: toHex(approvalMaxFee),
+                      max_priority_fee_per_gas: toHex(approvalPriorityFee),
+                    });
+                    const signedRevoke = revokeSignResult.data?.signed_transaction || revokeSignResult.signed_transaction;
+                    if (!signedRevoke) {
+                      log(`  ❌ Allowance revoke failed for ${quoteName}: Privy returned no signed transaction`);
+                      if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                      lastQuoteError = `${quoteName} allowance revoke failed`;
+                      continue;
+                    }
+                    const revokeResult = await executeTransaction({ signedTransaction: signedRevoke, chain, simulate: !noSimulate });
+                    if (revokeResult.status !== 'Success') {
+                      log(`  ❌ Allowance revoke failed for ${quoteName}: ${revokeResult.error || 'unknown'}`);
+                      if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                      lastQuoteError = `${quoteName} allowance revoke failed`;
+                      continue;
+                    }
+                    log(`  Waiting for allowance revoke confirmation...`);
+                    try {
+                      const receipt = await waitForReceipt(chain, revokeResult.txHash);
+                      log(`  ✓ Allowance revoked in block ${parseInt(receipt.blockNumber, 16)}: ${revokeResult.txHash}`);
+                    } catch (receiptErr) {
+                      log(`  ❌ Allowance revoke may not have confirmed for ${quoteName}: ${receiptErr.message}.${allowanceRevokeRecoveryHint(revokeResult.txHash)}`);
+                      if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                      lastQuoteError = `${quoteName} allowance revoke unconfirmed`;
+                      continue;
+                    }
+                    try {
+                      await assertAllowanceRevoked(chain, currentQuote.inputMint, walletAddress, currentQuote.approvalAddress);
+                    } catch (pollErr) {
+                      log(`  ❌ Revoke tx confirmed but allowance was not cleared for ${quoteName}: ${pollErr.message}.${allowanceRevokeRecoveryHint(revokeResult.txHash)}`);
+                      if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                      lastQuoteError = `${quoteName} allowance revoke verification failed`;
+                      continue;
+                    }
+                    await waitForAllowanceTxPropagation();
+                  }
                   log(`  ⚠ Approval required → ${currentQuote.approvalAddress}`);
                   const approvalNonce = await getEvmNonce(chain, walletAddress);
                   // Scope the approval to this trade's input (see approvalAmountForSwap).
@@ -2097,8 +2280,6 @@ EXAMPLES:
                   const approvalData = encodeApproveCalldata(currentQuote.approvalAddress, approveAmt, {
                     maxAllowance: approvalCapForQuote(quoteData),
                   });
-                  const approvalMaxFee = currentQuote.transaction?.maxFeePerGas || currentQuote.transaction?.gasPrice || '1000000';
-                  const approvalPriorityFee = currentQuote.transaction?.maxPriorityFeePerGas || '1000000';
                   const approvalSignResult = await privyClient.signEvmTransaction(evmWalletId, {
                     to: currentQuote.inputMint,
                     data: approvalData,
@@ -2110,9 +2291,21 @@ EXAMPLES:
                     max_priority_fee_per_gas: toHex(approvalPriorityFee),
                   });
                   const signedApproval = approvalSignResult.data?.signed_transaction || approvalSignResult.signed_transaction;
+                  if (!signedApproval) {
+                    const revokedMsg = shouldRevoke
+                      ? ' after revoking the prior allowance (now 0)'
+                      : '';
+                    log(`  ❌ Approval failed for ${quoteName}${revokedMsg}: Privy returned no signed transaction`);
+                    if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                    lastQuoteError = `${quoteName} approval failed`;
+                    continue;
+                  }
                   const approvalResult = await executeTransaction({ signedTransaction: signedApproval, chain, simulate: !noSimulate });
                   if (approvalResult.status !== 'Success') {
-                    log(`  ❌ Approval failed for ${quoteName}: ${approvalResult.error || 'unknown'}`);
+                    const revokedMsg = shouldRevoke
+                      ? ' after revoking the prior allowance (now 0)'
+                      : '';
+                    log(`  ❌ Approval failed for ${quoteName}${revokedMsg}: ${approvalResult.error || 'unknown'}`);
                     if (qi + 1 < endIndex) log(`  Trying next quote...`);
                     lastQuoteError = `${quoteName} approval failed`;
                     continue;
@@ -2122,12 +2315,20 @@ EXAMPLES:
                     const receipt = await waitForReceipt(chain, approvalResult.txHash);
                     log(`  ✓ Approval confirmed in block ${parseInt(receipt.blockNumber, 16)}: ${approvalResult.txHash}`);
                   } catch (receiptErr) {
-                    log(`  ❌ Approval may not have confirmed: ${receiptErr.message}`);
+                    log(`  ❌ Approval may not have confirmed${shouldRevoke ? ' after revoking the prior allowance (now 0)' : ''}: ${receiptErr.message}`);
                     if (qi + 1 < endIndex) log(`  Trying next quote...`);
                     lastQuoteError = `${quoteName} approval unconfirmed`;
                     continue;
                   }
-                  await new Promise(r => setTimeout(r, 2000));
+                  try {
+                    await assertAllowanceAtLeast(chain, currentQuote.inputMint, walletAddress, currentQuote.approvalAddress, approveAmt);
+                  } catch (pollErr) {
+                    log(`  ❌ Approval tx confirmed but allowance did not reach the required amount for ${quoteName}${shouldRevoke ? ' after revoking the prior allowance (now 0)' : ''}: ${pollErr.message}`);
+                    if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                    lastQuoteError = `${quoteName} approval verification failed`;
+                    continue;
+                  }
+                  await waitForAllowanceTxPropagation();
                 }
               }
 
@@ -2335,11 +2536,71 @@ EXAMPLES:
                   chain, currentQuote.inputMint, wcAddress, currentQuote.approvalAddress
                 );
 
-                if (existingAllowance >= approveAmt && existingAllowance > 0n) {
+                const { shouldRevoke, reuseAllowance } = resolveAllowanceAction(existingAllowance, approveAmt, noRevokeExcessiveAllowance);
+                if (reuseAllowance) {
+                  if (noRevokeExcessiveAllowance && shouldRevoke) {
+                    log(`  ⚠ Existing allowance (${existingAllowance}) for ${quoteName} is excessive (>${OVERSIZED_ALLOWANCE_MULTIPLIER}x this trade), but --no-revoke-excessive-allowance was set`);
+                  }
                   log(`  ✓ Sufficient allowance exists for ${quoteName}, skipping approval`);
                 } else {
+                  if (shouldRevoke) {
+                    log(`  ⚠ Existing allowance (${existingAllowance}) for ${quoteName} is excessive (>${OVERSIZED_ALLOWANCE_MULTIPLIER}x this trade) — revoking before re-approving`);
+                    log(`  Sending allowance revocation via WalletConnect (you'll be asked to approve this separately)...`);
+                    let revokeTxHash;
+                    try {
+                      const revokeResult = await sendApprovalViaWalletConnect(
+                        currentQuote.inputMint,
+                        currentQuote.approvalAddress,
+                        chainConfig.chainId,
+                        0n,
+                        undefined,
+                        { allowZero: true },
+                      );
+                      revokeTxHash = revokeResult.txHash;
+                      if (!revokeTxHash && revokeResult.signedTransaction) {
+                        log(`  Broadcasting allowance revocation via Trading API...`);
+                        const broadcastResult = await executeTransaction({
+                          signedTransaction: revokeResult.signedTransaction,
+                          chain,
+                          simulate: !noSimulate,
+                        });
+                        if (broadcastResult.status !== 'Success') {
+                          throw new Error(broadcastResult.error || 'broadcast failed');
+                        }
+                        revokeTxHash = broadcastResult.txHash;
+                      }
+                      if (!revokeTxHash) {
+                        throw new Error('Allowance revoke returned no transaction hash and no signed transaction; cannot confirm allowance was cleared');
+                      }
+                    } catch (revokeErr) {
+                      log(`  ❌ Allowance revoke failed for ${quoteName}: ${revokeErr.message}.${allowanceRevokeRecoveryHint(revokeTxHash)}`);
+                      if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                      lastQuoteError = `${quoteName} allowance revoke failed`;
+                      continue;
+                    }
+                    log(`  Waiting for allowance revoke confirmation...`);
+                    try {
+                      const receipt = await waitForReceipt(chain, revokeTxHash);
+                      log(`  ✓ Allowance revoked in block ${parseInt(receipt.blockNumber, 16)}: ${revokeTxHash}`);
+                    } catch (receiptErr) {
+                      log(`  ❌ Allowance revoke may not have confirmed for ${quoteName}: ${receiptErr.message}.${allowanceRevokeRecoveryHint(revokeTxHash)}`);
+                      if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                      lastQuoteError = `${quoteName} allowance revoke unconfirmed`;
+                      continue;
+                    }
+                    try {
+                      await assertAllowanceRevoked(chain, currentQuote.inputMint, wcAddress, currentQuote.approvalAddress);
+                    } catch (pollErr) {
+                      log(`  ❌ Revoke tx confirmed but allowance was not cleared for ${quoteName}: ${pollErr.message}.${allowanceRevokeRecoveryHint(revokeTxHash)}`);
+                      if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                      lastQuoteError = `${quoteName} allowance revoke verification failed`;
+                      continue;
+                    }
+                    await waitForAllowanceTxPropagation();
+                  }
                   log(`  ⚠ Approval required → ${currentQuote.approvalAddress}`);
                   log(`  Sending approval via WalletConnect...`);
+                  let approvalTxHash;
                   try {
                     const approvalResult = await sendApprovalViaWalletConnect(
                       currentQuote.inputMint,
@@ -2348,7 +2609,7 @@ EXAMPLES:
                       approveAmt,
                       approvalCapForQuote(quoteData),
                     );
-                    let approvalTxHash = approvalResult.txHash;
+                    approvalTxHash = approvalResult.txHash;
                     if (!approvalTxHash && approvalResult.signedTransaction) {
                       // Wallet returned a signed tx instead of broadcasting — broadcast via Trading API
                       log(`  Broadcasting approval via Trading API...`);
@@ -2362,18 +2623,48 @@ EXAMPLES:
                       }
                       approvalTxHash = broadcastResult.txHash;
                     }
-                    if (approvalTxHash) {
-                      log(`  Waiting for approval confirmation...`);
-                      const receipt = await waitForReceipt(chain, approvalTxHash);
-                      log(`  ✓ Approval confirmed in block ${parseInt(receipt.blockNumber, 16)}: ${approvalTxHash}`);
+                    if (!approvalTxHash) {
+                      // Fail closed: the wallet returned neither a hash nor a
+                      // signed tx, so we can't confirm the approval landed —
+                      // never fall through to the swap (esp. after a revoke has
+                      // already zeroed the allowance). The catch adds the
+                      // "after revoking (now 0)" context.
+                      throw new Error('returned no transaction hash and no signed transaction; cannot confirm approval landed');
                     }
                   } catch (approvalErr) {
-                    log(`  ❌ Approval failed for ${quoteName}: ${approvalErr.message}`);
+                    const revokedMsg = shouldRevoke
+                      ? ' after revoking the prior allowance (now 0)'
+                      : '';
+                    log(`  ❌ Approval failed for ${quoteName}${revokedMsg}: ${approvalErr.message}`);
                     if (qi + 1 < endIndex) log(`  Trying next quote...`);
                     lastQuoteError = `${quoteName} approval failed`;
                     continue;
                   }
-                  await new Promise(r => setTimeout(r, 2000));
+                  log(`  Waiting for approval confirmation...`);
+                  try {
+                    const receipt = await waitForReceipt(chain, approvalTxHash);
+                    log(`  ✓ Approval confirmed in block ${parseInt(receipt.blockNumber, 16)}: ${approvalTxHash}`);
+                  } catch (receiptErr) {
+                    const revokedMsg = shouldRevoke
+                      ? ' after revoking the prior allowance (now 0)'
+                      : '';
+                    log(`  ❌ Approval may not have confirmed${revokedMsg}: ${receiptErr.message}`);
+                    if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                    lastQuoteError = `${quoteName} approval unconfirmed`;
+                    continue;
+                  }
+                  try {
+                    await assertAllowanceAtLeast(chain, currentQuote.inputMint, wcAddress, currentQuote.approvalAddress, approveAmt);
+                  } catch (pollErr) {
+                    const revokedMsg = shouldRevoke
+                      ? ' after revoking the prior allowance (now 0)'
+                      : '';
+                    log(`  ❌ Approval tx confirmed but allowance did not reach the required amount for ${quoteName}${revokedMsg}: ${pollErr.message}`);
+                    if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                    lastQuoteError = `${quoteName} approval verification failed`;
+                    continue;
+                  }
+                  await waitForAllowanceTxPropagation();
                   log('');
                 }
               }
@@ -2561,14 +2852,68 @@ EXAMPLES:
                   chain, currentQuote.inputMint, walletAddress, currentQuote.approvalAddress
                 );
 
-                if (existingAllowance >= approveAmt && existingAllowance > 0n) {
+                const { shouldRevoke, reuseAllowance } = resolveAllowanceAction(existingAllowance, approveAmt, noRevokeExcessiveAllowance);
+                if (reuseAllowance) {
+                  if (noRevokeExcessiveAllowance && shouldRevoke) {
+                    log(`  ⚠ Existing allowance (${existingAllowance}) for ${quoteName} is excessive (>${OVERSIZED_ALLOWANCE_MULTIPLIER}x this trade), but --no-revoke-excessive-allowance was set`);
+                  }
                   log(`  ✓ Sufficient allowance exists for ${quoteName}, skipping approval`);
                 } else {
+                  const approvalGasPrice = currentQuote.transaction?.gasPrice || currentQuote.transaction?.maxFeePerGas || '1000000';
+
+                  if (shouldRevoke) {
+                    log(`  ⚠ Existing allowance (${existingAllowance}) for ${quoteName} is excessive (>${OVERSIZED_ALLOWANCE_MULTIPLIER}x this trade) — revoking before re-approving`);
+                    log(`  Sending allowance revocation tx...`);
+                    const revokeNonce = await getEvmNonce(chain, walletAddress);
+                    const revokeTxHex = buildApprovalTransaction(
+                      currentQuote.inputMint,
+                      currentQuote.approvalAddress,
+                      exported.evm.privateKey,
+                      chain,
+                      revokeNonce,
+                      approvalGasPrice,
+                      0n,
+                      undefined,
+                      { allowZero: true },
+                    );
+
+                    const revokeResult = await executeTransaction({
+                      signedTransaction: revokeTxHex,
+                      chain,
+                      simulate: !noSimulate,
+                    });
+
+                    if (revokeResult.status !== 'Success') {
+                      log(`  ❌ Allowance revoke failed for ${quoteName}: ${revokeResult.error || 'unknown error'}`);
+                      if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                      lastQuoteError = `${quoteName} allowance revoke failed`;
+                      continue;
+                    }
+
+                    log(`  Waiting for allowance revoke confirmation...`);
+                    try {
+                      const receipt = await waitForReceipt(chain, revokeResult.txHash);
+                      log(`  ✓ Allowance revoked in block ${parseInt(receipt.blockNumber, 16)}: ${revokeResult.txHash}`);
+                    } catch (receiptErr) {
+                      log(`  ❌ Allowance revoke may not have confirmed for ${quoteName}: ${receiptErr.message}.${allowanceRevokeRecoveryHint(revokeResult.txHash)}`);
+                      if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                      lastQuoteError = `${quoteName} allowance revoke unconfirmed`;
+                      continue;
+                    }
+                    try {
+                      await assertAllowanceRevoked(chain, currentQuote.inputMint, walletAddress, currentQuote.approvalAddress);
+                    } catch (pollErr) {
+                      log(`  ❌ Revoke tx confirmed but allowance was not cleared for ${quoteName}: ${pollErr.message}.${allowanceRevokeRecoveryHint(revokeResult.txHash)}`);
+                      if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                      lastQuoteError = `${quoteName} allowance revoke verification failed`;
+                      continue;
+                    }
+                    await waitForAllowanceTxPropagation();
+                  }
                   log(`  ⚠ Approval required → ${currentQuote.approvalAddress}`);
                   log(`  Sending approval tx...`);
                   const approvalNonce = await getEvmNonce(chain, walletAddress);
 
-                  const approvalGasPrice = currentQuote.transaction?.gasPrice || currentQuote.transaction?.maxFeePerGas || '1000000';
                   const approvalTxHex = buildApprovalTransaction(
                     currentQuote.inputMint,
                     currentQuote.approvalAddress,
@@ -2587,7 +2932,10 @@ EXAMPLES:
                   });
 
                   if (approvalResult.status !== 'Success') {
-                    log(`  ❌ Approval failed for ${quoteName}: ${approvalResult.error || 'unknown error'}`);
+                    const revokedMsg = shouldRevoke
+                      ? ' after revoking the prior allowance (now 0)'
+                      : '';
+                    log(`  ❌ Approval failed for ${quoteName}${revokedMsg}: ${approvalResult.error || 'unknown error'}`);
                     if (qi + 1 < endIndex) log(`  Trying next quote...`);
                     lastQuoteError = `${quoteName} approval failed`;
                     continue;
@@ -2598,13 +2946,20 @@ EXAMPLES:
                     const receipt = await waitForReceipt(chain, approvalResult.txHash);
                     log(`  ✓ Approval confirmed in block ${parseInt(receipt.blockNumber, 16)}: ${approvalResult.txHash}`);
                   } catch (receiptErr) {
-                    log(`  ❌ Approval may not have confirmed: ${receiptErr.message}`);
+                    log(`  ❌ Approval may not have confirmed${shouldRevoke ? ' after revoking the prior allowance (now 0)' : ''}: ${receiptErr.message}`);
                     if (qi + 1 < endIndex) log(`  Trying next quote...`);
                     lastQuoteError = `${quoteName} approval unconfirmed`;
                     continue;
                   }
-                  // Wait for RPC state propagation after approval
-                  await new Promise(r => setTimeout(r, 2000));
+                  try {
+                    await assertAllowanceAtLeast(chain, currentQuote.inputMint, walletAddress, currentQuote.approvalAddress, approveAmt);
+                  } catch (pollErr) {
+                    log(`  ❌ Approval tx confirmed but allowance did not reach the required amount for ${quoteName}${shouldRevoke ? ' after revoking the prior allowance (now 0)' : ''}: ${pollErr.message}`);
+                    if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                    lastQuoteError = `${quoteName} approval verification failed`;
+                    continue;
+                  }
+                  await waitForAllowanceTxPropagation();
                   log('');
                 }
               }

package/src/transfer.js

@@ -120,9 +120,31 @@ async function buildEvmTransaction({ to, amount, token, privateKey, chain, max =
   const privBuf = Buffer.from(privateKey, 'hex');
   const from = deriveEvmAddress(privateKey);
 
-  // Nonce
-  const nonceHex = await rpcCall(rpcUrl, 'eth_getTransactionCount', [from, 'latest']);
-  const nonce = BigInt(nonceHex);
+  // Fetch both pending and latest nonce counts. 'pending' is used so mempool-
+  // queued transactions are counted — 'latest' alone would assign the same
+  // nonce to back-to-back sends, causing one to fail or silently replace the
+  // other. The gap check mirrors trading.js's getEvmNonce: if more than 2
+  // transactions are already queued, signing another would silently stack
+  // behind them and sit unexecutable until they clear or get replaced.
+  const MAX_PENDING_NONCE_GAP = 2;
+  const [pendingHex, latestHex] = await Promise.all([
+    rpcCall(rpcUrl, 'eth_getTransactionCount', [from, 'pending']),
+    rpcCall(rpcUrl, 'eth_getTransactionCount', [from, 'latest']),
+  ]);
+  const nonce = BigInt(pendingHex);
+  const latestNonce = BigInt(latestHex);
+  const gap = Number(nonce - latestNonce);
+  if (gap > MAX_PENDING_NONCE_GAP) {
+    // wallet send has no --nonce/--priority-fee, so don't tell the user to
+    // replace via this CLI. Also note the two-RPC race on load-balanced
+    // endpoints (same caveat as trading.js getEvmNonce).
+    throw new Error(
+      `${from} has ${gap} unmined transactions queued on ${chain} (next mined nonce ${latestNonce}, next pending ${nonce}). ` +
+      `Signing another would queue behind them and stay unexecutable until they clear. ` +
+      `Wait for them to clear (or replace them with a higher fee from where they were sent) before retrying. ` +
+      `Note that a load-balanced public RPC may report a transaction it isn't actually holding, so don't diagnose from a single endpoint.`,
+    );
+  }
 
   // Fees — dynamic priority fee
   const feeHistory = await rpcCall(rpcUrl, 'eth_feeHistory', [4, 'latest', [50]]);

package/src/walletconnect-trading.js

@@ -114,13 +114,15 @@ export async function sendTransactionViaWalletConnect(txData, timeoutMs = 120000
  * @param {number} chainId - EIP-155 chain ID
  * @param {bigint|string|number} amount - Allowance to grant, in base units
  * @param {bigint|string|number} [maxAllowance] - Hard cap from persisted request intent
+ * @param {object} [opts]
+ * @param {boolean} [opts.allowZero=false] - Allow a zero-amount revoke approval
  * @returns {{ txHash?: string, signedTransaction?: string }}
  */
-export async function sendApprovalViaWalletConnect(tokenAddress, spenderAddress, chainId, amount, maxAllowance) {
+export async function sendApprovalViaWalletConnect(tokenAddress, spenderAddress, chainId, amount, maxAllowance, { allowZero = false } = {}) {
   // encodeApproveCalldata enforces a valid 20-byte spender, a bounded (< MAX)
   // amount within the request cap, and exactly-68-byte calldata — so a
   // malformed or tampered spender/amount can't reshape the ABI word layout.
-  const data = encodeApproveCalldata(spenderAddress, amount, { maxAllowance });
+  const data = encodeApproveCalldata(spenderAddress, amount, { maxAllowance, allowZero });
 
   return sendTransactionViaWalletConnect({
     to: tokenAddress,