nansen-cli 1.38.0 → 1.39.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.39.0
+
+### Minor Changes
+
+- [#495](https://github.com/nansen-ai/nansen-cli/pull/495) [`3306897`](https://github.com/nansen-ai/nansen-cli/commit/3306897c1aaae594f4401fd4656b2451ab375d78) Thanks [@kome12](https://github.com/kome12)! - Add EVM swap-outcome verification to `trade execute`. Before broadcasting a swap on an EVM chain (Base), the CLI now simulates the transaction and confirms the wallet's balance changes match the quote — the input is spent within your maximum, at least the expected output is received, and no other token or NFT leaves the wallet — refusing to sign when they don't. This runs on top of the existing pre-broadcast checks and needs a simulation-capable RPC (`NANSEN_BASE_SIM_RPC`); when none is available it degrades with a warning rather than blocking the trade. Skip it with `--no-verify-outcome`. Solana is unaffected.
+
+### Patch Changes
+
+- [#495](https://github.com/nansen-ai/nansen-cli/pull/495) [`e8cf217`](https://github.com/nansen-ai/nansen-cli/commit/e8cf217feaa9e7c8f68f4f3c3c2a49adcda07101) Thanks [@kome12](https://github.com/kome12)! - Harden swap-outcome verification error handling: a revert reported by the simulation endpoint as a top-level JSON-RPC error (rather than a per-call status) now fails closed (blocks the swap) instead of degrading, and a non-2xx simulation response (e.g. HTTP 401 "Invalid API key") now degrades with the real status and message instead of a misleading "returned no call result" warning.
+
+- [#499](https://github.com/nansen-ai/nansen-cli/pull/499) [`de0bcc5`](https://github.com/nansen-ai/nansen-cli/commit/de0bcc562bcd20a80edd3ab2f486870b80629c83) Thanks [@gulshngill](https://github.com/gulshngill)! - Fix `profiler labels`: call `/api/v1/profiler/address/labels` with its v1 request body — the beta endpoint previously used was removed from the Nansen API. `profiler batch --include labels` now returns the label array itself instead of the raw `{pagination, data}` envelope.
+
+- [#506](https://github.com/nansen-ai/nansen-cli/pull/506) [`f407edb`](https://github.com/nansen-ai/nansen-cli/commit/f407edb19444d6b5a1a631d29b4c4fb9bd280708) Thanks [@gulshngill](https://github.com/gulshngill)! - Add a canonical MCP setup section to the README — endpoint `https://mcp.nansen.ai/ra/mcp`, `NANSEN-API-KEY` auth, per-client setup paths for Claude Code, Claude Tag, and generic or stdio-only clients, plus a pointer to the connection docs for Claude Desktop and Cursor — and point the out-of-credits and low-credit warnings at the credits tab of the billing page, `app.nansen.ai/api?tab=api`, instead of the bare `app.nansen.ai/api`.
+
+- [#500](https://github.com/nansen-ai/nansen-cli/pull/500) [`9ccf8a2`](https://github.com/nansen-ai/nansen-cli/commit/9ccf8a20841a9ca01a2627ccf5de2575bf016a46) Thanks [@gulshngill](https://github.com/gulshngill)! - Document global pagination options in `nansen schema`.
+
 ## 1.38.0
 
 ### Minor Changes

package/README.md

@@ -51,6 +51,61 @@ nansen schema [command] [--pretty]    # full command reference (no API key neede
 
 Run `nansen schema --pretty` for the full subcommand and field reference.
 
+## MCP
+
+Connect any MCP client to Nansen's streamable HTTP server:
+
+- **Endpoint:** `https://mcp.nansen.ai/ra/mcp`
+- **Authentication:** `NANSEN-API-KEY` header
+- **API key:** [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/agent-setup)
+
+**Claude Desktop and Cursor:** setup instructions for both — the Claude Desktop `.dxt` bundle and the Cursor install deep link — are in the connection docs: [docs.nansen.ai/mcp/connecting](https://docs.nansen.ai/mcp/connecting).
+
+**One-command (Claude Code):**
+
+```bash
+claude mcp add --transport http nansen https://mcp.nansen.ai/ra/mcp --header "NANSEN-API-KEY: <your-key>"
+```
+
+**Manual (any streamable-HTTP client):** for example, add this to Cursor's `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "nansen": {
+      "url": "https://mcp.nansen.ai/ra/mcp",
+      "headers": {
+        "NANSEN-API-KEY": "<your-key>"
+      }
+    }
+  }
+}
+```
+
+**Manual (stdio-only clients):** use `mcp-remote` as a bridge. Keep the header as one argument with no space after the colon:
+
+```json
+{
+  "mcpServers": {
+    "nansen": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "https://mcp.nansen.ai/ra/mcp",
+        "--header",
+        "NANSEN-API-KEY:${NANSEN_API_KEY}"
+      ],
+      "env": {
+        "NANSEN_API_KEY": "<your-key>"
+      }
+    }
+  }
+}
+```
+
+**Claude Tag (Claude in Slack):** an admin must attach a plugin whose `.mcp.json` points at `https://mcp.nansen.ai/ra/mcp` and add a custom credential allowing the host `mcp.nansen.ai`. See the [Claude Tag custom-connections documentation](https://claude.com/docs/claude-tag/admins/connections/custom). Per-user fallback: use Claude Code or Claude Desktop.
+
 ## Trading
 
 DEX swaps on `solana` and `base`. Two-step: quote then execute.
@@ -216,7 +271,7 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
 
 | Code | Action |
 |------|--------|
-| `CREDITS_EXHAUSTED` | Stop all API calls immediately. `details.credits.remaining` is your actual balance. Top up at [app.nansen.ai/api](https://app.nansen.ai/api). |
+| `CREDITS_EXHAUSTED` | Stop all API calls immediately. `details.credits.remaining` is your actual balance. Top up at [app.nansen.ai/api?tab=api](https://app.nansen.ai/api?tab=api). |
 | `UNAUTHORIZED` | Wrong or missing key. Re-auth. |
 | `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
 | `UNSUPPORTED_FILTER` | Remove the filter and retry. |

package/package.json

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

package/skills/nansen-wallet-batch/SKILL.md

@@ -19,7 +19,7 @@ allowed-tools: Bash(nansen:*)
 ADDRESSES="0xaddr1,0xaddr2,0xaddr3,..." CHAIN=ethereum
 nansen research profiler batch --addresses "$ADDRESSES" --chain $CHAIN --include labels,balance
 # → .data.{total, completed, results[]: {address, chain, labels[], balance, error}}
-# labels[]: {label, category ("smart_money","fund","social","behavioral","others"), fullname}
+# labels[]: {label, category ("smart_money","fund","social","behavioral","others"), kind[]}
 # balance: {data[]: {token_symbol, token_amount, price_usd, value_usd}}
 ```
 Check .error per result — invalid addresses return an error message, not a crash. Skip those.

package/skills/nansen-wallet-profiler/SKILL.md

@@ -92,7 +92,7 @@ nansen research profiler compare --addresses "0xabc,0xdef" --chain ethereum
 
 - `pnl-summary` has no pagination support (returns aggregate stats, not a list).
 - `perp-positions` has no pagination support.
-- `labels` has no pagination support — the API ignores `per_page` and always returns all labels for the address. `--limit` is not available for this sub-command.
+- `labels` supports pagination — `--limit`/`--page` are honoured and the response is `{pagination: {page, per_page, is_last_page}, data[]: {label, category, kind[]}}`.
 - `transactions` caps at per_page=100 (API limit).
 - `trace` makes many API calls — use `--width` conservatively.
 - `batch` accepts `--file <path>` with one address per line as alternative to `--addresses`.

package/src/api.js

@@ -393,7 +393,7 @@ function requireValidToken(tokenAddress, chain) {
   if (!v.valid) throw new NansenError(v.error, v.code);
 }
 
-function loadConfig() {
+export function loadConfig() {
   // Base config from files, then env vars override individual fields
   let config = null;
 
@@ -908,8 +908,9 @@ export class NansenAPI {
   async addressLabels(params = {}) {
     const { address, chain = 'ethereum', pagination = { page: 1, per_page: 100 } } = params;
     if (address) requireValidAddress(address, chain);
-    return this.request('/api/beta/profiler/address/labels', {
-      parameters: { address, chain },
+    return this.request('/api/v1/profiler/address/labels', {
+      address,
+      chain,
       pagination
     });
   }

package/src/cli.js

@@ -489,7 +489,9 @@ async function enrichTransfers(result, apiInstance, chain) {
   for (const addr of addrs) {
     try {
       const labelsResult = await apiInstance.addressLabels({ address: addr, chain });
-      labelMap[addr] = labelsResult?.labels || labelsResult?.data?.results || [];
+      labelMap[addr] = Array.isArray(labelsResult?.data)
+        ? labelsResult.data.map(item => item.label)
+        : labelsResult?.labels || [];
     } catch {
       labelMap[addr] = [];
     }
@@ -568,7 +570,10 @@ export async function batchProfile(api, params = {}) {
     }
     try {
       if (include.includes('labels')) {
-        entry.labels = await api.addressLabels({ address, chain });
+        const labelsResult = await api.addressLabels({ address, chain });
+        entry.labels = Array.isArray(labelsResult?.data)
+          ? labelsResult.data
+          : labelsResult?.labels || [];
       }
       if (include.includes('balance')) {
         entry.balance = await api.addressBalance({ address, chain });

package/src/response-meta.js

@@ -118,12 +118,12 @@ export function creditWarning(meta) {
   const { used, remaining, cost } = credits;
   if (remaining === null) return null;
   if (remaining === 0) {
-    return '⚠️  Out of API credits. Top up at https://app.nansen.ai/api';
+    return '⚠️  Out of API credits. Top up at https://app.nansen.ai/api?tab=api';
   }
   // The cost header is the authoritative charge; used is the fallback.
   const charged = cost ?? used;
   if (charged !== null && charged > 0 && remaining < charged) {
-    return `⚠️  ${remaining} API credit${remaining === 1 ? '' : 's'} left — less than this call cost (${charged}). Top up at https://app.nansen.ai/api`;
+    return `⚠️  ${remaining} API credit${remaining === 1 ? '' : 's'} left — less than this call cost (${charged}). Top up at https://app.nansen.ai/api?tab=api`;
   }
   return null;
 }

package/src/rpc-urls.js

@@ -11,6 +11,23 @@
  *   NANSEN_BSC_RPC        Custom BNB Smart Chain RPC
  *   NANSEN_XLAYER_RPC     Custom X Layer RPC
  *   NANSEN_SOLANA_RPC     Custom Solana RPC
+ *   NANSEN_BASE_SIM_RPC   Custom Base simulation RPC (see SIMULATION_RPCS below)
+ *
+ * Simulation RPCs (SIMULATION_RPCS) are a SEPARATE registry from the cheap
+ * defaults above. Swap-outcome verification (src/swap-simulation.js) needs an
+ * endpoint that supports state-changing simulation with asset-transfer tracing
+ * (`eth_simulateV1` / `debug_traceCall`), which the free public defaults in
+ * CHAIN_RPCS deliberately DISABLE. Keeping the two registries apart means only
+ * the (pricey) simulation calls hit the trace-capable endpoint; ordinary reads
+ * (nonce, balance, allowance, eth_call revert check) stay on the cheap default.
+ *
+ * The shipped simulation endpoint is a Nansen-hosted service authenticated with
+ * the user's existing Nansen API key (no secret in this public package): the
+ * trace-capable upstream is reached server-side, so the baked default carries no
+ * credential. With no NANSEN_BASE_SIM_RPC override, swap-outcome verification
+ * uses this default; if the service is ever unreachable it degrades with a
+ * warning rather than blocking the trade. To use your own endpoint (or for local
+ * dev/e2e), point NANSEN_BASE_SIM_RPC at any trace-capable RPC in a gitignored .env.
  *
  * Backward-compat aliases (deprecated — prefer the forms above):
  *   NANSEN_RPC_BASE       Old name for NANSEN_BASE_RPC; trading.js previously read this
@@ -40,3 +57,53 @@ export const CHAIN_RPCS = {
   polygon:  process.env.NANSEN_POLYGON_RPC  || DEFAULT_POLYGON_RPC,
   bnb:      process.env.NANSEN_BNB_RPC      || DEFAULT_BNB_RPC,
 };
+
+// Zero-config default for the shipped Nansen-hosted simulation endpoint. It
+// authenticates with the user's existing Nansen API key (attached automatically
+// by swap-simulation.js), and the trace-capable upstream is reached server-side —
+// so this URL carries no secret and is safe to bake into a public package. Never
+// embed an RPC URL that carries an inline token here; any embedded secret would
+// leak on publish.
+const DEFAULT_BASE_SIM_RPC = 'https://api.nansen.ai/api/v1/trade/simulate-swap';
+
+// Separate registry for swap-outcome simulation (src/swap-simulation.js). These
+// endpoints must support state-changing simulation with asset-transfer tracing
+// (`eth_simulateV1` / `debug_traceCall`), which the CHAIN_RPCS public defaults
+// disable. Only outcome verification reads this registry; every other RPC call
+// stays on the cheap CHAIN_RPCS default. A null entry (no baked default and no
+// override) signals "no sim-capable endpoint" to the caller, which degrades.
+//
+// Intentionally a mutable export: unit tests override an entry in-place (e.g.
+// `SIMULATION_RPCS.base = ...`) to point at a mock or to null out the endpoint,
+// restoring it in afterEach. Runtime code only ever reads it.
+export const SIMULATION_RPCS = {
+  base: process.env.NANSEN_BASE_SIM_RPC || DEFAULT_BASE_SIM_RPC,
+};
+
+// Nansen hosts the API key may be forwarded to. Kept to an explicit allowlist
+// (not a `*.nansen.ai` wildcard): the key only ever authenticates the sim proxy
+// on api.nansen.ai, and a wildcard would forward it to any subdomain that
+// resolves — including a misconfigured or compromised one. Add new sim hosts
+// here deliberately if one is ever introduced.
+const NANSEN_HOSTED_SIM_HOSTS = new Set(['api.nansen.ai']);
+
+/**
+ * Whether a simulation URL is a Nansen-hosted endpoint that may receive the
+ * user's Nansen API key. The key authenticates the shipped default proxy
+ * (DEFAULT_BASE_SIM_RPC); a NANSEN_BASE_SIM_RPC override can point at ANY host
+ * (dev node, third-party trace RPC), and forwarding the credential there would
+ * leak it. So the key is attached ONLY when this returns true — every other
+ * endpoint is called anonymously.
+ *
+ * Trust is: https + hostname is one of NANSEN_HOSTED_SIM_HOSTS. Anything else
+ * (http, other host, unparseable) is untrusted and gets no key.
+ */
+export function isNansenHostedUrl(url) {
+  try {
+    const u = new URL(url);
+    if (u.protocol !== 'https:') return false;
+    return NANSEN_HOSTED_SIM_HOSTS.has(u.hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}

package/src/schema.json

@@ -1620,7 +1620,11 @@
             },
             "no-simulate": {
               "type": "boolean",
-              "description": "Skip the pre-broadcast simulation."
+              "description": "Skip the pre-broadcast simulation (the eth_call revert check)."
+            },
+            "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."
             }
           }
         },
@@ -1968,6 +1972,15 @@
       "type": "string",
       "description": "Comma-separated list of fields to include in output"
     },
+    "limit": {
+      "type": "number",
+      "description": "Maximum results per page for list-returning research commands; maps to pagination.per_page. General endpoints default to 10 (max 1000), while profiler address endpoints default to 20 (max 100). Supported by smart-money, profiler, token, perp, points, prediction-market, and supported research historical-* commands. Commands that declare their own limit option (search, token top-tokens, trade limit-order list) use those command-specific semantics instead; token ohlcv, profiler perp-positions, and historical-token-flow-summary do not support pagination. profiler labels defaults to 100 when omitted."
+    },
+    "page": {
+      "type": "number",
+      "default": 1,
+      "description": "1-based page number for list-returning research commands; maps to pagination.page. Supported by smart-money, profiler, token, perp, points, prediction-market, and supported research historical-* commands. Trade, wallet, and operational commands ignore it; token ohlcv, profiler perp-positions, and historical-token-flow-summary do not support pagination. profiler labels defaults to page 1 when omitted."
+    },
     "no-retry": {
       "type": "boolean",
       "description": "Disable automatic retry on rate limits/errors"

package/src/swap-simulation.js

@@ -0,0 +1,477 @@
+/**
+ * Swap-outcome simulation: run a swap transaction through a trace-capable RPC
+ * and report the asset changes it would cause to the sender's wallet.
+ *
+ * This is a defence-in-depth check that complements the static checks in
+ * trade-validation.js: instead of only inspecting the swap calldata, it
+ * simulates the call so assertSwapOutcome can confirm the resulting balance
+ * changes match what the user asked for, failing closed on any mismatch.
+ *
+ * The endpoint returns the RAW simulation result and all delta math runs here,
+ * client-side, so the verification stays independent of the service that built
+ * the quote. See src/rpc-urls.js SIMULATION_RPCS for why this needs a separate,
+ * trace-capable endpoint.
+ *
+ * EVM-only: Solana signs the aggregator transaction verbatim and is out of scope.
+ */
+
+import { SIMULATION_RPCS, isNansenHostedUrl } from './rpc-urls.js';
+
+// keccak256("Transfer(address,address,uint256)") — shared by ERC-20 and ERC-721.
+// ERC-20 indexes (from, to) and carries value in `data` (3 topics); ERC-721 also
+// indexes the tokenId (4 topics). We distinguish them by topic count below.
+const TRANSFER_TOPIC = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
+// keccak256("Approval(address,address,uint256)") — shared by ERC-20 and ERC-721.
+// ERC-20 indexes (owner, spender) with the value in `data` (3 topics); ERC-721
+// also indexes the tokenId (4 topics), granting control of one specific NFT.
+const APPROVAL_TOPIC = '0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925';
+// keccak256("ApprovalForAll(address,address,bool)") — ERC-721 AND ERC-1155. Grants
+// an operator control of the owner's ENTIRE collection; `data` is the bool flag.
+const APPROVAL_FOR_ALL_TOPIC = '0x17307eab39ab6107e8899845ad3d59bd9653f200f220920489ca2b5937696c31';
+// keccak256("TransferSingle(address,address,address,uint256,uint256)") — ERC-1155
+const ERC1155_SINGLE_TOPIC = '0xc3d58168c5ae7397731d063d5bbf3d657854427343f4c083240f7aacaa2d0f62';
+// keccak256("TransferBatch(address,address,address,uint256[],uint256[])") — ERC-1155
+const ERC1155_BATCH_TOPIC = '0x4a39dc06d4c0dbc64b70af90fd698a233a518aa5d07e595d983b8c0526c8f7fb';
+
+// The CLI's EVM native-asset sentinel (mirrors EVM_NATIVE in trading.js and
+// NATIVE_TOKEN_ADDRESSES in trade-validation.js). Native ETH movements surface
+// in traces either as synthetic Transfer logs from the zero address
+// (eth_simulateV1 traceTransfers) or as call-frame `value` fields (callTracer);
+// both are normalised to this sentinel so the caller can compare native deltas
+// against a quote's inputMint/outputMint uniformly with ERC-20 deltas.
+export const EVM_NATIVE_SENTINEL = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+
+// callTracer frame types that can actually move ETH. STATICCALL forbids value
+// and DELEGATECALL runs in the caller's context (its `value` mirrors the parent
+// frame rather than being a transfer), so both must be excluded from native
+// delta accounting — some nodes populate their `value` field regardless, which
+// would otherwise double-count or invent ETH movement.
+//
+// SELFDESTRUCT is deliberately excluded too. The wallet is the EOA signer, so it
+// can never itself SELFDESTRUCT — its real native outflow is always a top-level
+// CALL. Some nodes additionally surface a SELFDESTRUCT refund frame whose value
+// lands on the wallet; counting that as an inflow can cancel or partially offset
+// the wallet's real CALL outflow, letting the balance-delta assertion pass for a
+// mismatched result. Dropping it means we may under-count a genuine selfdestruct
+// refund into the wallet (rare, and largely neutered by EIP-6780), which only
+// makes the net native delta stricter — fail-closed, never the reverse.
+const ETH_MOVING_FRAME_TYPES = new Set(['CALL', 'CALLCODE', 'CREATE', 'CREATE2']);
+
+/**
+ * A simulation error the caller can distinguish from a genuine outcome mismatch.
+ * `code` is one of:
+ *   NO_SIM_RPC        - no simulation endpoint configured for the chain
+ *   NOT_SIM_CAPABLE   - endpoint reachable but does not support any trace method
+ *   SIM_RPC_ERROR     - transport/parse failure talking to the endpoint
+ *   SIM_REVERTED      - the swap call itself reverted in simulation
+ * The first three are degrade conditions (warn, proceed per policy); the caller
+ * decides. SIM_REVERTED is an outcome problem and should not be silently ignored.
+ */
+export class SwapSimulationError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'SwapSimulationError';
+    this.code = code;
+  }
+}
+
+/** Whether a sim-capable endpoint is configured for this chain. */
+export function hasSimulationRpc(chain) {
+  return Boolean(SIMULATION_RPCS[chain]);
+}
+
+/** Last 20 bytes of a 32-byte topic, as a lowercased 0x address. */
+function topicToAddress(topic) {
+  if (typeof topic !== 'string') return null;
+  const hex = topic.replace(/^0x/, '').padStart(64, '0');
+  return '0x' + hex.slice(-40).toLowerCase();
+}
+
+/** Parse a hex data field as a uint256; returns 0n on anything unparseable. */
+function hexToBigInt(hex) {
+  if (typeof hex !== 'string' || hex === '0x' || hex === '') return 0n;
+  try {
+    return BigInt(hex.startsWith('0x') ? hex : '0x' + hex);
+  } catch {
+    return 0n;
+  }
+}
+
+/** Normalise a token address, mapping the zero address (native) to the sentinel. */
+function normalizeToken(addr) {
+  if (typeof addr !== 'string') return null;
+  const lower = addr.toLowerCase();
+  return lower === ZERO_ADDRESS ? EVM_NATIVE_SENTINEL : lower;
+}
+
+/**
+ * Fold a flat list of logs into per-token deltas for `wallet`, the ERC-20
+ * Approvals the wallet granted, any non-fungible (ERC-721/ERC-1155) transfer OUT
+ * of the wallet, and any non-fungible approval the wallet GRANTED. `deltas` is
+ * signed: positive = received, negative = sent. Tokens with a net-zero delta are
+ * dropped.
+ *
+ * `nftOut` / `nftApprovals` exist because the fungible `deltas` (and the ERC-20
+ * `approvals`) map cannot represent an NFT: a DEX swap should only move native
+ * currency and ERC-20 tokens, so an ERC-721 / ERC-1155 leaving the wallet OR the
+ * wallet granting an NFT operator approval is an out-of-scope, asset-endangering
+ * event the caller must fail closed on (assertSwapOutcome) rather than silently
+ * ignore. A single-NFT Approval carries empty `data`, so it would otherwise fold
+ * into `approvals` as amount 0n and be mistaken for a harmless revoke; an
+ * ApprovalForAll is not an ERC-20 Approval at all and would be dropped entirely.
+ * Inbound NFTs, self-transfers, and NFT revokes are harmless and not recorded.
+ *
+ * @param {Array} logs - [{ address, topics, data }]
+ * @param {string} wallet - the sender whose balance changes we care about
+ */
+function foldLogs(logs, wallet) {
+  const w = wallet.toLowerCase();
+  const deltas = {}; // token -> bigint (signed)
+  const approvals = []; // { token, spender, amount } — ERC-20 approvals
+  const nftOut = []; // { standard, token } — non-fungible transfers leaving `w`
+  const nftApprovals = []; // { standard, token, operator } — NFT approvals `w` granted
+
+  for (const lg of logs || []) {
+    const topics = lg?.topics || [];
+    const topic0 = (topics[0] || '').toLowerCase();
+
+    if (topic0 === TRANSFER_TOPIC && topics.length >= 4) {
+      // ERC-721: shares the ERC-20 Transfer signature but indexes the tokenId as
+      // a 4th topic. Flag only when the NFT leaves the wallet for someone else (a
+      // self-transfer is a no-op, mirroring the ERC-20 net-zero cleanup).
+      const from = topicToAddress(topics[1]);
+      const to = topicToAddress(topics[2]);
+      if (from === w && to !== w) nftOut.push({ standard: 'ERC-721', token: normalizeToken(lg.address) });
+    } else if (topic0 === TRANSFER_TOPIC && topics.length >= 3) {
+      const from = topicToAddress(topics[1]);
+      const to = topicToAddress(topics[2]);
+      // eth_simulateV1 emits native transfers from the zero address; those carry
+      // the moved value in `data` and their log `address` is 0x0 too — both
+      // normalise to the native sentinel.
+      const token = normalizeToken(lg.address);
+      const amount = hexToBigInt(lg.data);
+      if (!token || amount === 0n) continue;
+      if (to === w) deltas[token] = (deltas[token] || 0n) + amount;
+      if (from === w) deltas[token] = (deltas[token] || 0n) - amount;
+    } else if ((topic0 === ERC1155_SINGLE_TOPIC || topic0 === ERC1155_BATCH_TOPIC) && topics.length >= 4) {
+      // ERC-1155 TransferSingle/Batch index (operator, from, to); `from` is the
+      // 3rd topic, `to` the 4th. Flag only a real outbound transfer.
+      const from = topicToAddress(topics[2]);
+      const to = topicToAddress(topics[3]);
+      if (from === w && to !== w) nftOut.push({ standard: 'ERC-1155', token: normalizeToken(lg.address) });
+    } else if (topic0 === APPROVAL_TOPIC && topics.length >= 4) {
+      // ERC-721 single-token Approval (owner, approved, tokenId indexed; empty
+      // data). Approving the zero address is a revoke and grants nothing.
+      const owner = topicToAddress(topics[1]);
+      const approved = topicToAddress(topics[2]);
+      if (owner === w && approved && approved !== ZERO_ADDRESS) {
+        nftApprovals.push({ standard: 'ERC-721', token: normalizeToken(lg.address), operator: approved });
+      }
+    } else if (topic0 === APPROVAL_TOPIC && topics.length >= 3) {
+      const owner = topicToAddress(topics[1]);
+      const spender = topicToAddress(topics[2]);
+      if (owner === w) {
+        approvals.push({
+          token: normalizeToken(lg.address),
+          spender,
+          amount: hexToBigInt(lg.data),
+        });
+      }
+    } else if (topic0 === APPROVAL_FOR_ALL_TOPIC && topics.length >= 3) {
+      // ERC-721/ERC-1155 ApprovalForAll(owner, operator indexed; bool in data).
+      // data == 0 is a revoke (grants nothing); any non-zero flag is a grant of
+      // control over the wallet's whole collection.
+      const owner = topicToAddress(topics[1]);
+      const operator = topicToAddress(topics[2]);
+      if (owner === w && hexToBigInt(lg.data) !== 0n) {
+        nftApprovals.push({ standard: 'ERC-721/1155 (all)', token: normalizeToken(lg.address), operator });
+      }
+    }
+  }
+
+  for (const t of Object.keys(deltas)) {
+    if (deltas[t] === 0n) delete deltas[t];
+  }
+  return { deltas, approvals, nftOut, nftApprovals };
+}
+
+// ============= eth_simulateV1 (primary) =============
+
+function buildSimRpcBody(method, params) {
+  return JSON.stringify({ jsonrpc: '2.0', id: 1, method, params });
+}
+
+async function postSim(rpcUrl, apiKey, method, params, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    // Attach the Nansen API key ONLY when the endpoint is Nansen-hosted. A
+    // NANSEN_BASE_SIM_RPC override can point at any host (dev node, third-party
+    // trace RPC); forwarding the user's credential there would leak it, so an
+    // untrusted endpoint is always called anonymously (see isNansenHostedUrl).
+    const sendApiKey = Boolean(apiKey) && isNansenHostedUrl(rpcUrl);
+    const res = await fetch(rpcUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(sendApiKey ? { apikey: apiKey } : {}),
+      },
+      body: buildSimRpcBody(method, params),
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      throw new SwapSimulationError(
+        'SIM_RPC_ERROR',
+        `Simulation RPC returned non-JSON (HTTP ${res.status}) for ${method}: ${text.slice(0, 120)}`,
+      );
+    }
+    // A non-2xx is a transport/auth failure (e.g. 401 from the hosted proxy when
+    // the API key is missing/invalid), not a simulation outcome. The proxy phrases
+    // these as `{message}` — not a JSON-RPC `{error}` — so without this check the
+    // body flows on, yields no `result.calls[0]`, and degrades with a misleading
+    // "returned no call result". Surface the real status + message so the warning
+    // is actionable (per the repo's actionable-errors rule); still SIM_RPC_ERROR,
+    // so the caller degrades (warn + proceed) rather than blocking the trade.
+    const ok = res.ok ?? (res.status >= 200 && res.status < 300);
+    if (!ok) {
+      const detail =
+        body?.error?.message ||
+        body?.message ||
+        (typeof body?.error === 'string' ? body.error : null) ||
+        text.slice(0, 120);
+      throw new SwapSimulationError('SIM_RPC_ERROR', `Simulation RPC HTTP ${res.status} for ${method}: ${detail}`);
+    }
+    return body;
+  } catch (e) {
+    if (e instanceof SwapSimulationError) throw e;
+    if (e.name === 'AbortError') {
+      throw new SwapSimulationError('SIM_RPC_ERROR', `Simulation RPC timed out after ${timeoutMs}ms (${method})`);
+    }
+    throw new SwapSimulationError('SIM_RPC_ERROR', `Simulation RPC request failed (${method}): ${e.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * True when an RPC error indicates the method itself is unavailable, as opposed
+ * to a normal execution failure. We only fall back to another trace method on
+ * "unsupported", never on a genuine revert or bad-params error.
+ */
+function isMethodUnsupported(rpcError) {
+  const msg = (rpcError?.message || '').toLowerCase();
+  const code = rpcError?.code;
+  // -32601 = method not found (JSON-RPC). Providers also phrase disabled trace
+  // methods as "method ... not supported"/"not available"/"not enabled".
+  return (
+    code === -32601 ||
+    msg.includes('method not found') ||
+    msg.includes('not supported') ||
+    msg.includes('not available') ||
+    msg.includes('not enabled') ||
+    msg.includes('unsupported method')
+  );
+}
+
+/**
+ * True when a top-level JSON-RPC error denotes an in-EVM revert rather than a
+ * transport/params problem. The conformant eth_simulateV1 / callTracer shapes
+ * report a revert per-call (`calls[0].status === '0x0'` or a frame `error`), but
+ * a proxy may instead collapse a reverting simulation into a top-level `error`.
+ * Classifying that as SIM_RPC_ERROR would DEGRADE (warn + proceed), waving a
+ * reverting swap through; treat it as SIM_REVERTED so it blocks (fail closed).
+ * Checked only AFTER isMethodUnsupported, so a "method not available" error is
+ * never misread as a revert.
+ */
+function isRevertError(rpcError) {
+  // EIP-1474: code 3 is the execution (revert) error. Also match the standard
+  // geth phrasing, but NOT a bare "revert": messages like "gas estimation would
+  // revert" or "request reverted by upstream policy" are estimation/transport
+  // noise, and treating those as a revert would hard-block (skip the quote)
+  // instead of degrading. Checked only AFTER isMethodUnsupported.
+  if (rpcError?.code === 3) return true;
+  return (rpcError?.message || '').toLowerCase().includes('execution reverted');
+}
+
+async function simulateViaEthSimulateV1(rpcUrl, apiKey, { from, to, data, value }, timeoutMs) {
+  const params = [
+    {
+      blockStateCalls: [
+        {
+          calls: [{ from, to, data: data || '0x', value: value || '0x0' }],
+        },
+      ],
+      // Surface native ETH movements as synthetic Transfer logs, and don't let
+      // validation (nonce/balance) reject the pre-broadcast sim.
+      traceTransfers: true,
+      validation: false,
+    },
+    'latest',
+  ];
+  const body = await postSim(rpcUrl, apiKey, 'eth_simulateV1', params, timeoutMs);
+  if (body.error) {
+    if (isMethodUnsupported(body.error)) {
+      throw new SwapSimulationError('NOT_SIM_CAPABLE', `eth_simulateV1 unavailable: ${body.error.message}`);
+    }
+    if (isRevertError(body.error)) {
+      throw new SwapSimulationError('SIM_REVERTED', `Swap reverts in simulation: ${body.error.message}`);
+    }
+    throw new SwapSimulationError('SIM_RPC_ERROR', `eth_simulateV1 error: ${body.error.message}`);
+  }
+  const blockResult = Array.isArray(body.result) ? body.result[0] : body.result;
+  const call = blockResult?.calls?.[0];
+  if (!call) {
+    throw new SwapSimulationError('SIM_RPC_ERROR', 'eth_simulateV1 returned no call result');
+  }
+  // status is '0x1' on success, '0x0' on revert. A non-conformant bare '0x'/''
+  // (no hex digits) is indeterminate: BigInt('0x') would throw a TypeError that
+  // is NOT a SwapSimulationError, so verifySwapOutcome would misclassify it as a
+  // hard block (proceed:false) with an opaque message instead of degrading.
+  // Skip the status check for those and let the balance-delta assertions judge
+  // the real outcome (a swap that truly delivered nothing still fails assertion
+  // 2). Numeric statuses stay handled by BigInt via the plain constructor.
+  if (call.status != null && call.status !== '0x' && call.status !== '' && BigInt(call.status) === 0n) {
+    throw new SwapSimulationError(
+      'SIM_REVERTED',
+      `Swap reverts in simulation${call.error?.message ? `: ${call.error.message}` : ''}`,
+    );
+  }
+  const { deltas, approvals, nftOut, nftApprovals } = foldLogs(call.logs, from);
+  return { deltas, approvals, nftOut, nftApprovals, method: 'eth_simulateV1' };
+}
+
+// ============= debug_traceCall + callTracer (fallback) =============
+
+/** Depth-first flatten a callTracer frame tree into { logs, frames }. */
+function flattenFrames(root) {
+  const logs = [];
+  const frames = [];
+  const stack = [root];
+  while (stack.length) {
+    const f = stack.pop();
+    if (!f) continue;
+    frames.push(f);
+    for (const lg of f.logs || []) logs.push(lg);
+    for (const child of f.calls || []) stack.push(child);
+  }
+  return { logs, frames };
+}
+
+async function simulateViaDebugTraceCall(rpcUrl, apiKey, { from, to, data, value }, timeoutMs) {
+  const params = [
+    { from, to, data: data || '0x', value: value || '0x0' },
+    'latest',
+    { tracer: 'callTracer', tracerConfig: { withLog: true } },
+  ];
+  const body = await postSim(rpcUrl, apiKey, 'debug_traceCall', params, timeoutMs);
+  if (body.error) {
+    if (isMethodUnsupported(body.error)) {
+      throw new SwapSimulationError('NOT_SIM_CAPABLE', `debug_traceCall unavailable: ${body.error.message}`);
+    }
+    if (isRevertError(body.error)) {
+      throw new SwapSimulationError('SIM_REVERTED', `Swap reverts in simulation: ${body.error.message}`);
+    }
+    throw new SwapSimulationError('SIM_RPC_ERROR', `debug_traceCall error: ${body.error.message}`);
+  }
+  const root = body.result;
+  if (!root) throw new SwapSimulationError('SIM_RPC_ERROR', 'debug_traceCall returned no result');
+  if (root.error) {
+    throw new SwapSimulationError('SIM_REVERTED', `Swap reverts in simulation: ${root.error}`);
+  }
+
+  const { logs, frames } = flattenFrames(root);
+  const { deltas, approvals, nftOut, nftApprovals } = foldLogs(logs, from);
+
+  // callTracer does NOT emit synthetic logs for native ETH, so derive native
+  // movement from the `value` on each frame: value the wallet sends is an
+  // outflow, value it receives is an inflow. Mirrors traceTransfers semantics.
+  //
+  // Only value-carrying opcodes actually move ETH: skip STATICCALL (value
+  // forbidden) and DELEGATECALL (runs in the caller's context, its `value`
+  // mirrors the parent rather than transferring) so a node that populates their
+  // `value` field anyway can't invent or double-count native flow. A frame with
+  // no `type` (unusual) is treated as non-moving and skipped.
+  const w = from.toLowerCase();
+  let native = 0n;
+  for (const f of frames) {
+    if (!ETH_MOVING_FRAME_TYPES.has((f.type || '').toUpperCase())) continue;
+    const v = hexToBigInt(f.value);
+    if (v === 0n) continue;
+    if ((f.to || '').toLowerCase() === w) native += v;
+    if ((f.from || '').toLowerCase() === w) native -= v;
+  }
+  if (native !== 0n) {
+    deltas[EVM_NATIVE_SENTINEL] = (deltas[EVM_NATIVE_SENTINEL] || 0n) + native;
+    if (deltas[EVM_NATIVE_SENTINEL] === 0n) delete deltas[EVM_NATIVE_SENTINEL];
+  }
+
+  // callTracer only sets `error` on the frame that reverted; a top-level call can
+  // "succeed" while a sub-call reverts silently, moving nothing. If the trace
+  // yielded no deltas and no approvals but some frame errored, surface that as a
+  // revert — clearer than letting an all-zero outcome fail downstream as a
+  // mismatch. (The primary eth_simulateV1 path reports status directly.)
+  //
+  // Deliberately scoped to the moved-nothing case: DO NOT widen this to throw on
+  // any errored frame. Aggregators routinely make sub-calls that revert and are
+  // caught (probe pool A, revert, fall back to pool B) inside an otherwise
+  // successful swap, so those frame errors are normal. When tokens actually
+  // moved, assertSwapOutcome judges the real outcome (a partial swap that failed
+  // to deliver the output still fails assertion 2), so an errored frame there is
+  // not a reliable revert signal and would false-positive on legitimate swaps.
+  if (
+    Object.keys(deltas).length === 0 &&
+    approvals.length === 0 &&
+    nftOut.length === 0 &&
+    nftApprovals.length === 0
+  ) {
+    const errored = frames.find((f) => f.error);
+    if (errored) {
+      throw new SwapSimulationError('SIM_REVERTED', `Swap reverts in simulation: ${errored.error}`);
+    }
+  }
+  return { deltas, approvals, nftOut, nftApprovals, method: 'debug_traceCall' };
+}
+
+// ============= public entry point =============
+
+/**
+ * Simulate a single swap transaction and return the normalised asset changes it
+ * causes to `from`'s wallet.
+ *
+ * Placement: call this on the swap call alone, AFTER any required approval is
+ * confirmed on-chain, so the live allowance is reflected on `latest` and a
+ * single-transaction simulation matches what the broadcast swap will do.
+ *
+ * @param {string} chain - chain key (only 'base' is wired today)
+ * @param {{ to: string, data: string, value?: string }} swapCall - the swap tx
+ * @param {{ from: string, apiKey?: string|null, timeoutMs?: number }} opts
+ * @returns {Promise<{ deltas: Record<string,bigint>, approvals: Array<{token,spender,amount}>, nftOut: Array<{standard,token}>, nftApprovals: Array<{standard,token,operator}>, method: string }>}
+ * @throws {SwapSimulationError} on any degrade condition or an in-sim revert.
+ */
+export async function simulateAssetChanges(chain, swapCall, { from, apiKey = null, timeoutMs = 20000 } = {}) {
+  const rpcUrl = SIMULATION_RPCS[chain];
+  if (!rpcUrl) {
+    throw new SwapSimulationError('NO_SIM_RPC', `No simulation RPC configured for chain '${chain}'.`);
+  }
+  if (!from) {
+    throw new SwapSimulationError('SIM_RPC_ERROR', 'simulateAssetChanges requires a `from` address.');
+  }
+
+  const call = { from, to: swapCall.to, data: swapCall.data, value: swapCall.value };
+
+  // Primary: eth_simulateV1 (native transfers as synthetic logs, single round
+  // trip). Fall back to debug_traceCall only when eth_simulateV1 is unavailable.
+  try {
+    return await simulateViaEthSimulateV1(rpcUrl, apiKey, call, timeoutMs);
+  } catch (e) {
+    if (e instanceof SwapSimulationError && e.code === 'NOT_SIM_CAPABLE') {
+      return await simulateViaDebugTraceCall(rpcUrl, apiKey, call, timeoutMs);
+    }
+    throw e;
+  }
+}

package/src/trade-validation.js

@@ -821,9 +821,11 @@ const BARE_ERC20_OUTER_SELECTORS = {
 };
 
 /**
- * Reject a same-chain swap whose transaction calldata is a bare ERC-20
- * transfer/approve/transferFrom rather than a router call. No-op when the
- * calldata is absent or too short to carry a 4-byte selector.
+ * Reject a swap or bridge whose transaction calldata is a bare ERC-20
+ * transfer/approve/transferFrom rather than a router call. Applies to both
+ * same-chain and cross-chain EVM quotes (a legit bridge also routes through a
+ * router). No-op when the calldata is absent or too short to carry a 4-byte
+ * selector.
  *
  * @param {string} data - The swap transaction's calldata (quote.transaction.data)
  */
@@ -837,3 +839,213 @@ export function assertSwapCalldataNotBareTransfer(data) {
     );
   }
 }
+
+// ============= Swap-outcome verification (balance-delta simulation) =============
+
+/**
+ * Assert that a SIMULATED swap's asset changes match the user's intent, failing
+ * closed on any mismatch. This is a defence-in-depth outcome check that
+ * complements the static calldata checks (validateSwapTarget /
+ * assertSwapCalldataNotBareTransfer): it verifies what the swap actually does to
+ * the wallet's balances, not just what the calldata looks like.
+ *
+ * Run it on the swap-call-alone simulation AFTER any required approval is
+ * confirmed on-chain, so the live allowance is reflected on `latest` and a
+ * single-transaction sim matches the broadcast swap (see swap-simulation.js).
+ *
+ * Four assertions, all derived from the persisted request intent + the quote:
+ *   1. the input token leaves the wallet by no MORE than maxInputAmount. Native
+ *      input excludes gas: the sim deltas are log-based, so gas (not a transfer
+ *      log) is never counted.
+ *   2. the output token arrives by AT LEAST minOut — exactOut: >= the requested
+ *      output; exactIn: the quoted output reduced by the slippage in effect.
+ *   3. NO token other than the input leaves the wallet.
+ *   4. the wallet grants no Approval to a spender outside `expectedSpenders`.
+ *
+ * @param {object} request - persisted intent (quoteData.request); required
+ * @param {object} quote - the quote being executed
+ * @param {{deltas: Record<string, bigint|string|number>, approvals?: Array<{token?:string, spender?:string, amount?:any}>}} sim
+ *   - the normalised result from simulateAssetChanges()
+ * @param {object} [ctx]
+ * @param {number} [ctx.slippage] - slippage fraction in effect (quoteData.slippage);
+ *   defaults to 3% to match approvalAmountForSwap when omitted
+ * @param {Set<string>|string[]} [ctx.expectedSpenders] - spenders the wallet may
+ *   legitimately (re)approve during the swap (e.g. the approval target and the
+ *   router); anything else fails assertion 4. Compared case-insensitively.
+ * @param {bigint} [ctx.siblingDustThreshold=0n] - non-input outflow tolerated
+ *   before assertion 3 fires (for fee-on-transfer / rounding). Strict 0 default.
+ * @throws {Error} with `code = 'SWAP_OUTCOME_MISMATCH'` on any failed assertion.
+ */
+export function assertSwapOutcome(request, quote, sim, { slippage, expectedSpenders, siblingDustThreshold = 0n } = {}) {
+  const fail = (detail) => {
+    const e = new Error(`Swap outcome mismatch (SWAP_OUTCOME_MISMATCH): ${detail} Refusing to sign.`);
+    e.code = 'SWAP_OUTCOME_MISMATCH';
+    return e;
+  };
+
+  if (!request) throw fail('no request intent to verify the outcome against.');
+  if (!sim || typeof sim !== 'object' || sim.deltas == null) {
+    throw fail('simulation returned no asset changes to verify.');
+  }
+
+  // Normalise deltas to a lowercased-key BigInt map. A non-integer delta is a
+  // corrupt sim result — fail closed rather than coerce it to 0.
+  const deltas = {};
+  for (const [k, v] of Object.entries(sim.deltas)) {
+    let amt;
+    try {
+      amt = typeof v === 'bigint' ? v : BigInt(v);
+    } catch {
+      throw fail(`simulated delta for ${k} (${v}) is not an integer.`);
+    }
+    deltas[k.toLowerCase()] = amt;
+  }
+
+  const inputToken = quote?.inputMint ? String(quote.inputMint).toLowerCase() : null;
+  const outputToken = quote?.outputMint ? String(quote.outputMint).toLowerCase() : null;
+  if (!inputToken || !outputToken) {
+    throw fail('quote is missing the input or output token address.');
+  }
+  // Fail closed on a same-token quote: assertion 3 skips the input token, so if
+  // output == input a drain of that token would slip past unverified. A real
+  // swap never sells and buys the same token (also rejected upstream).
+  if (inputToken === outputToken) {
+    throw fail(`quote input and output tokens are the same (${inputToken}); refusing to verify.`);
+  }
+
+  // --- Assertion 1: input outflow within the spend ceiling ---
+  // This bounds the outflow by maxInputAmount (the slippage-buffered ceiling),
+  // NOT the exact expected input: for exactOut the aggregator may legitimately
+  // pull anywhere up to that ceiling. The tighter exactIn bound (outflow ==
+  // request.amount) is enforced by assertQuoteMatchesRequest, which the execute
+  // paths run earlier in the same iteration. Keep that call ahead of this one on
+  // any new signing path — Assertion 1 alone does not re-check exactIn inflation.
+  if (request.maxInputAmount == null) {
+    throw fail('request has no maximum input to bound the outflow against.');
+  }
+  let cap;
+  try {
+    cap = BigInt(request.maxInputAmount);
+  } catch {
+    throw fail(`maximum input (${request.maxInputAmount}) is not an integer.`);
+  }
+  const inputDelta = deltas[inputToken] || 0n;
+  const outflow = inputDelta < 0n ? -inputDelta : 0n;
+  if (outflow > cap) {
+    throw fail(`the input token (${inputToken}) left the wallet by ${outflow}, exceeding your maximum input (${cap}).`);
+  }
+
+  // --- Assertion 2: output arrives at or above the minimum acceptable ---
+  const swapMode = request.swapMode ?? 'exactIn';
+  const outputDelta = deltas[outputToken] || 0n;
+  let minOut;
+  if (swapMode === 'exactOut') {
+    if (request.amount == null) throw fail('exactOut request is missing the requested output amount.');
+    try {
+      minOut = BigInt(request.amount);
+    } catch {
+      throw fail(`requested output amount (${request.amount}) is not an integer.`);
+    }
+    // Mirror the exactIn non-positive guard: a zero/negative requested output
+    // makes minOut <= 0 and turns assertion 2 into a no-op (outputDelta >= 0
+    // always holds), so a swap delivering nothing would pass. Upstream rejects
+    // zero amounts, but this helper is a self-contained fail-closed boundary.
+    if (minOut <= 0n) {
+      throw fail(`exactOut request has a non-positive output amount (${minOut}); cannot compute a minimum acceptable output.`);
+    }
+  } else {
+    const quotedRaw = quote.outAmount ?? quote.outputAmount;
+    if (quotedRaw == null) {
+      throw fail('quote is missing the quoted output amount; cannot compute the minimum acceptable output.');
+    }
+    let quoted;
+    try {
+      quoted = BigInt(quotedRaw);
+    } catch {
+      throw fail(`quoted output amount (${quotedRaw}) is not an integer.`);
+    }
+    // A non-positive quoted output makes minOut <= 0, so a sim receiving nothing
+    // (or losing the output token) would pass assertion 2 (outputDelta < minOut is
+    // false when minOut <= 0). exactIn has no upstream positive-output guard
+    // (unlike exactOut), so a rogue outAmount of "0" or a negative value would
+    // otherwise slip through.
+    if (quoted <= 0n) {
+      throw fail(`quote has a non-positive output amount (${quoted}); cannot compute a minimum acceptable output.`);
+    }
+    // Floor of quoted × (1 − slippage), in basis points to stay in BigInt. This
+    // mirrors the slippage the user actually set (quoteData.slippage), defaulting
+    // to 3% to match approvalAmountForSwap when it wasn't supplied.
+    //
+    // Cap the slippage used HERE at 50%, independent of what the user accepted:
+    // the upstream quote command allows --slippage up to 1.0 (100%), which would
+    // make minOut 0 and neuter this assertion — a route delivering nothing would
+    // pass (outputDelta >= 0). This is a defence-in-depth floor, not the user's
+    // execution tolerance; a real swap never loses more than half the quoted
+    // output, so requiring at least 50% keeps the guard meaningful while leaving
+    // enormous headroom over a normal few-percent deviation.
+    const rawSlip = Number.isFinite(slippage) && slippage >= 0 ? slippage : 0.03;
+    const slip = Math.min(rawSlip, 0.5);
+    const bps = BigInt(Math.min(10000, Math.round(slip * 10000)));
+    minOut = (quoted * (10000n - bps)) / 10000n;
+  }
+  if (outputDelta < minOut) {
+    throw fail(`the output token (${outputToken}) increased by only ${outputDelta}, below the minimum acceptable output (${minOut}).`);
+  }
+
+  // --- Assertion 3: no token other than the input leaves the wallet ---
+  const dust = siblingDustThreshold > 0n ? siblingDustThreshold : 0n;
+  for (const [token, delta] of Object.entries(deltas)) {
+    if (token === inputToken) continue; // its outflow is bounded by assertion 1
+    if (delta < 0n && -delta > dust) {
+      throw fail(`a token other than the one you are selling (${token}) left the wallet (delta ${delta}); a swap must not move any token except the input.`);
+    }
+  }
+
+  // --- Assertion 3b: no non-fungible asset leaves the wallet ---
+  // The signed `deltas` map only models native + ERC-20 balances, so an NFT
+  // drain is invisible to assertion 3. A DEX swap should never move an ERC-721 or
+  // ERC-1155 out of the wallet, so fail closed if the sim surfaced one. (Inbound
+  // NFTs are harmless and are not recorded by foldLogs.)
+  for (const nft of sim.nftOut || []) {
+    throw fail(
+      `a non-fungible asset (${nft.standard}${nft.token ? ` ${nft.token}` : ''}) left the wallet; a swap must not transfer any NFT.`,
+    );
+  }
+
+  // --- Assertion 3c: no non-fungible approval is granted ---
+  // A DEX swap never needs to approve an NFT, so any ERC-721 / ERC-1155 approval
+  // the wallet grants (single-token Approval or ApprovalForAll) is fail-closed —
+  // it would let the operator move the NFT out AFTER the swap, invisibly to the
+  // transfer checks above. The ERC-20 spender allowlist (assertion 4) does NOT
+  // cover these: a single-NFT Approval folds in as a zero-amount "revoke" and an
+  // ApprovalForAll is not an ERC-20 Approval at all.
+  for (const ap of sim.nftApprovals || []) {
+    throw fail(
+      `the swap grants a non-fungible approval (${ap.standard}${ap.token ? ` ${ap.token}` : ''}) to ${ap.operator || 'an operator'}; a swap must not approve any NFT.`,
+    );
+  }
+
+  // --- Assertion 4: no approval to an unexpected spender ---
+  const allowed = new Set(
+    (expectedSpenders instanceof Set ? [...expectedSpenders] : expectedSpenders || [])
+      .filter(Boolean)
+      .map((s) => String(s).toLowerCase()),
+  );
+  for (const ap of sim.approvals || []) {
+    if (!ap || !ap.spender) continue;
+    // A revoke (approve to 0) grants no allowance, so it is never a concern.
+    if (ap.amount != null) {
+      try {
+        if (BigInt(ap.amount) === 0n) continue;
+      } catch { /* non-integer amount → treat as a real approval below */ }
+    }
+    const spender = String(ap.spender).toLowerCase();
+    if (!allowed.has(spender)) {
+      throw fail(
+        `the swap grants an approval to an unexpected spender (${spender}); a swap should only (re)approve ${allowed.size ? [...allowed].join(', ') : 'nothing'}.`,
+      );
+    }
+  }
+
+  return { verified: true };
+}

package/src/trading.js

@@ -13,9 +13,10 @@ 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, approvalAmountForSwap } from './trade-validation.js';
+import { validateQuoteInput, validateBalance, resolvePercentAmount, validateGasBalance, encodeApproveCalldata, assertValidApprovalSpender, assertQuoteMatchesRequest, assertSwapCalldataNotBareTransfer, assertSwapOutcome, approvalAmountForSwap } from './trade-validation.js';
 import { CHAIN_RPCS } from './rpc-urls.js';
-import { packageVersion, CommandError, telemetryHeaders } from './api.js';
+import { simulateAssetChanges, SwapSimulationError, hasSimulationRpc } from './swap-simulation.js';
+import { packageVersion, CommandError, telemetryHeaders, loadConfig } from './api.js';
 
 // ============= Constants =============
 
@@ -700,6 +701,92 @@ export async function simulateEvmCall(chain, { from, to, data, value, gas }) {
   }
 }
 
+/**
+ * Normalise an aggregator's transaction `value` to a 0x-hex string the RPC
+ * accepts. The field may be a decimal string ('1000000'), a 0x-hex string, a
+ * bare '0x' (no digits — `BigInt('0x')` throws), or absent. Anything unparseable
+ * becomes '0x0' rather than throwing, so a malformed value can't crash the
+ * degrade path or misfire as an outcome mismatch. Note: unlike swap-simulation's
+ * hexToBigInt, this keeps BigInt's decimal parsing (tx.value is often decimal).
+ */
+function toRpcHexValue(value) {
+  if (!value || value === '0x') return '0x0';
+  try {
+    return '0x' + BigInt(value).toString(16);
+  } catch {
+    return '0x0';
+  }
+}
+
+/**
+ * Verify — via balance-delta simulation — that a swap does to the wallet what
+ * the user asked and no more. Defence-in-depth on top of the static calldata
+ * guards: the cheap eth_call sim answers "will it revert", this answers "does the
+ * outcome match intent" (see assertSwapOutcome in trade-validation.js).
+ *
+ * EVM-only, and on its own gate independent of --no-simulate/gasless. Skipped
+ * for cross-chain bridges (the output lands on the destination chain, so a
+ * source-chain simulation can't observe it). When no simulation-capable endpoint
+ * is configured it DEGRADES — logs a warning, then proceeds — so a simulation
+ * outage never blocks trading. --no-verify-outcome skips it entirely.
+ *
+ * Returns { proceed, reason }. proceed=false means this quote failed
+ * verification: the caller should fall through to the next candidate WITHOUT
+ * signing or broadcasting the swap. proceed=true covers a clean pass AND a
+ * degrade (the warning is logged here).
+ *
+ * @param {object} args
+ * @param {string} args.chain
+ * @param {string} args.from - the wallet that will sign (the sender simulated)
+ * @param {object} args.quote - the quote about to be executed (currentQuote)
+ * @param {object} args.quoteData - the loaded quote record (.request, .slippage)
+ * @param {string|null} [args.apiKey] - Nansen API key for the hosted endpoint
+ * @param {function} [args.log]
+ */
+export async function verifySwapOutcome({ chain, from, quote, quoteData, apiKey = null, log = () => {} }) {
+  if (CHAIN_MAP[chain?.toLowerCase()]?.type !== 'evm') return { proceed: true }; // EVM-only
+  // Cross-chain: the output token settles on the destination chain, so it can
+  // never appear in a source-chain simulation and the output-received assertion
+  // would always fail. The source-chain leg only spends/locks the input here;
+  // skip outcome verification for bridges (mirrors the bridge branch below).
+  if (quoteData?.toChain && quoteData.toChain !== quoteData.chain) return { proceed: true };
+  // No request intent recorded (a pre-intent quote): assertSwapOutcome has
+  // nothing to compare the simulated deltas against and would raise a misleading
+  // SWAP_OUTCOME_MISMATCH. Degrade cleanly — the static guards still ran, and a
+  // re-quote re-enables this check.
+  if (!quoteData?.request) {
+    log('  ⚠ Swap-outcome verification skipped (no request intent — re-quote to enable it).');
+    return { proceed: true };
+  }
+  if (!hasSimulationRpc(chain)) {
+    log(`  ⚠ Swap-outcome verification unavailable (no simulation endpoint for ${chain}); proceeding without it.`);
+    return { proceed: true };
+  }
+  const tx = quote?.transaction || {};
+  // Spenders the wallet may legitimately (re)approve mid-swap: the approval
+  // target and the router it routes through. Anything else fails assertion 4.
+  const expectedSpenders = [quote?.approvalAddress, tx.to].filter(Boolean);
+  try {
+    const sim = await simulateAssetChanges(
+      chain,
+      { to: tx.to, data: tx.data, value: toRpcHexValue(tx.value) },
+      { from, apiKey },
+    );
+    assertSwapOutcome(quoteData.request, quote, sim, { slippage: quoteData.slippage, expectedSpenders });
+    log(`  ✓ Swap outcome verified (via ${sim.method}).`);
+    return { proceed: true };
+  } catch (e) {
+    // Degrade (warn + proceed) when the simulation itself could not run; block
+    // (fall through to the next quote) when the outcome did not match or the
+    // swap reverts in simulation.
+    if (e instanceof SwapSimulationError && ['NO_SIM_RPC', 'NOT_SIM_CAPABLE', 'SIM_RPC_ERROR'].includes(e.code)) {
+      log(`  ⚠ Swap-outcome verification could not run (${e.message}); proceeding without it.`);
+      return { proceed: true };
+    }
+    return { proceed: false, reason: e.message };
+  }
+}
+
 /**
  * Estimate gas for an EVM transaction. Returns the gas estimate or null on failure.
  * Used to fix under-gassed quotes from aggregators.
@@ -1761,7 +1848,18 @@ 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 noVerifyOutcome = flags['no-verify-outcome'];
       const gasless = Boolean(flags.gasless);
+      // Read the API key for the swap-outcome sim endpoint. It's optional (the
+      // check degrades to a warning if the endpoint can't authenticate), so a
+      // malformed config must not crash an in-progress trade — fall back to null.
+      const apiKey = (() => {
+        try {
+          return loadConfig().apiKey;
+        } catch {
+          return null;
+        }
+      })();
 
       if (!quoteId) {
         throw new CommandError(`Usage: nansen trade execute --quote <quoteId> [options]
@@ -1769,7 +1867,8 @@ CROSS-CHAIN NOTES (when using --to-chain):
 OPTIONS:
   --quote <id>              Quote ID from 'nansen quote'
   --wallet <name>           Wallet name (default: default wallet)
-  --no-simulate             Skip pre-broadcast simulation
+  --no-simulate             Skip pre-broadcast simulation (the eth_call revert check)
+  --no-verify-outcome       Skip EVM swap-outcome verification (balance-delta check)
   --gasless                 Relay-only: have Relay's solver pay gas (no WalletConnect)
 
 EXAMPLES:
@@ -1939,15 +2038,15 @@ EXAMPLES:
               assertCompleteEvmRequestIntent(quoteData.request);
               assertQuoteMatchesRequest(quoteData.request, currentQuote, { chain, walletAddress, slippage: quoteData.slippage });
 
-              // Same-chain only: a legit swap's outer call is a router method,
-              // never a bare ERC-20 transfer/approve. Reject that drain shape.
-              // Cross-chain routes skip THIS selector check, but a bare transfer
-              // still targets the token contract, so validateSwapTarget's
-              // `to === inputMint` gate above already refuses it on both paths —
-              // cross-chain bare transfers are not actually waved through here.
-              if (!quoteData.toChain) {
-                assertSwapCalldataNotBareTransfer(currentQuote.transaction.data);
-              }
+              // Reject a bare ERC-20 transfer/approve/transferFrom as the outer
+              // call: a real swap or bridge routes through an aggregator/router,
+              // never a direct token method. Runs on cross-chain too — the
+              // validateSwapTarget gate above only refuses `to === inputMint`, so
+              // a bare transfer to a SIBLING token the wallet holds would
+              // otherwise slip through the bridge path (which doesn't parse the
+              // calldata recipient) and drain it. Legitimate bridges route through
+              // a router selector, so this never fires on a real cross-chain quote.
+              assertSwapCalldataNotBareTransfer(currentQuote.transaction.data);
 
               // Validate transaction.value (same checks as local wallet)
               const isNative = isNativeToken(currentQuote.inputMint);
@@ -2048,6 +2147,20 @@ EXAMPLES:
                 }
               }
 
+              // Verify the swap's simulated on-chain outcome matches intent.
+              // Its own gate (runs even when --no-simulate/gasless skip the
+              // cheap revert check above); degrades with a warning if no
+              // simulation endpoint is available.
+              if (!noVerifyOutcome) {
+                const outcome = await verifySwapOutcome({ chain, from: walletAddress, quote: currentQuote, quoteData, apiKey, log });
+                if (!outcome.proceed) {
+                  log(`  ❌ ${quoteName} failed swap-outcome verification: ${outcome.reason}`);
+                  if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                  lastQuoteError = `${quoteName} outcome verification failed: ${outcome.reason}`;
+                  continue;
+                }
+              }
+
               // Gas resolution — fall back to eth_estimateGas if quote has no gas
               const txData = currentQuote.transaction;
               const apiGas = parseInt(currentQuote.gas || '0');
@@ -2175,15 +2288,15 @@ EXAMPLES:
               assertCompleteEvmRequestIntent(quoteData.request);
               assertQuoteMatchesRequest(quoteData.request, currentQuote, { chain, walletAddress: wcAddress, slippage: quoteData.slippage });
 
-              // Same-chain only: a legit swap's outer call is a router method,
-              // never a bare ERC-20 transfer/approve. Reject that drain shape.
-              // Cross-chain routes skip THIS selector check, but a bare transfer
-              // still targets the token contract, so validateSwapTarget's
-              // `to === inputMint` gate above already refuses it on both paths —
-              // cross-chain bare transfers are not actually waved through here.
-              if (!quoteData.toChain) {
-                assertSwapCalldataNotBareTransfer(currentQuote.transaction.data);
-              }
+              // Reject a bare ERC-20 transfer/approve/transferFrom as the outer
+              // call: a real swap or bridge routes through an aggregator/router,
+              // never a direct token method. Runs on cross-chain too — the
+              // validateSwapTarget gate above only refuses `to === inputMint`, so
+              // a bare transfer to a SIBLING token the wallet holds would
+              // otherwise slip through the bridge path (which doesn't parse the
+              // calldata recipient) and drain it. Legitimate bridges route through
+              // a router selector, so this never fires on a real cross-chain quote.
+              assertSwapCalldataNotBareTransfer(currentQuote.transaction.data);
 
               // Validate transaction.value (same checks as local wallet)
               const txValue = BigInt(currentQuote.transaction.value || '0');
@@ -2282,6 +2395,20 @@ EXAMPLES:
                 }
               }
 
+              // Verify the swap's simulated on-chain outcome matches intent. Its
+              // own gate: runs even when --no-simulate/gasless skip the cheap
+              // eth_call revert check above; degrades with a warning when no
+              // simulation endpoint is set.
+              if (!noVerifyOutcome) {
+                const outcome = await verifySwapOutcome({ chain, from: wcAddress, quote: currentQuote, quoteData, apiKey, log });
+                if (!outcome.proceed) {
+                  log(`  ❌ ${quoteName} failed swap-outcome verification: ${outcome.reason}`);
+                  if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                  lastQuoteError = `${quoteName} outcome verification failed: ${outcome.reason}`;
+                  continue;
+                }
+              }
+
               // Resolve gas
               const txData = currentQuote.transaction;
               const apiGas = parseInt(currentQuote.gas || "0");
@@ -2379,15 +2506,15 @@ EXAMPLES:
               assertCompleteEvmRequestIntent(quoteData.request);
               assertQuoteMatchesRequest(quoteData.request, currentQuote, { chain, walletAddress, slippage: quoteData.slippage });
 
-              // Same-chain only: a legit swap's outer call is a router method,
-              // never a bare ERC-20 transfer/approve. Reject that drain shape.
-              // Cross-chain routes skip THIS selector check, but a bare transfer
-              // still targets the token contract, so validateSwapTarget's
-              // `to === inputMint` gate above already refuses it on both paths —
-              // cross-chain bare transfers are not actually waved through here.
-              if (!quoteData.toChain) {
-                assertSwapCalldataNotBareTransfer(currentQuote.transaction.data);
-              }
+              // Reject a bare ERC-20 transfer/approve/transferFrom as the outer
+              // call: a real swap or bridge routes through an aggregator/router,
+              // never a direct token method. Runs on cross-chain too — the
+              // validateSwapTarget gate above only refuses `to === inputMint`, so
+              // a bare transfer to a SIBLING token the wallet holds would
+              // otherwise slip through the bridge path (which doesn't parse the
+              // calldata recipient) and drain it. Legitimate bridges route through
+              // a router selector, so this never fires on a real cross-chain quote.
+              assertSwapCalldataNotBareTransfer(currentQuote.transaction.data);
 
               // Handle approval if needed — skip for native ETH
               // Check existing allowance first to avoid unnecessary approve txs
@@ -2501,6 +2628,20 @@ EXAMPLES:
                 }
               }
 
+              // Verify the swap's simulated on-chain outcome matches intent. Its
+              // own gate: runs even when --no-simulate/gasless skip the cheap
+              // eth_call revert check above; degrades with a warning when no
+              // simulation endpoint is set.
+              if (!noVerifyOutcome) {
+                const outcome = await verifySwapOutcome({ chain, from: walletAddress, quote: currentQuote, quoteData, apiKey, log });
+                if (!outcome.proceed) {
+                  log(`  ❌ ${quoteName} failed swap-outcome verification: ${outcome.reason}`);
+                  if (qi + 1 < endIndex) log(`  Trying next quote...`);
+                  lastQuoteError = `${quoteName} outcome verification failed: ${outcome.reason}`;
+                  continue;
+                }
+              }
+
               // Use the Trading API's gas estimation (quote.gas) directly.
               // The API already applies a 1.5x buffer over eth_estimateGas.
               // Skip client-side re-estimation — it adds latency and the API value is reliable.