nansen-cli 1.41.1 → 1.43.0

package/src/trading.js

@@ -14,7 +14,7 @@ import { buildMessageV0, fetchRecentBlockhash } from './x402-svm.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, assertSolanaInstructionsSafe, assertSolanaSwapOutcome, approvalAmountForSwap, needsAllowanceRevoke, OVERSIZED_ALLOWANCE_MULTIPLIER } from './trade-validation.js';
+import { validateQuoteInput, validateBalance, resolvePercentAmount, validateGasBalance, encodeApproveCalldata, assertValidApprovalSpender, assertQuoteMatchesRequest, assertSwapCalldataNotBareTransfer, assertSwapOutcome, assertSolanaInstructionsSafe, assertSolanaSwapOutcome, approvalAmountForSwap, needsAllowanceRevoke, OVERSIZED_ALLOWANCE_MULTIPLIER, EVM_BRIDGE_NATIVE_FEE_SLACK, isBridgeRequest } from './trade-validation.js';
 import { readCompactU16 } from './solana-tx.js';
 export { readCompactU16 };
 import { CHAIN_RPCS } from './rpc-urls.js';
@@ -1008,7 +1008,18 @@ export async function verifySwapOutcome({ chain, from, quote, quoteData, apiKey
       { to: tx.to, data: tx.data, value: toRpcHexValue(tx.value) },
       { from, apiKey },
     );
-    const outcome = assertSwapOutcome(quoteData.request, quote, sim, { slippage: quoteData.slippage, expectedSpenders });
+    // A cross-chain bridge may pay a fee in native ETH via msg.value on a
+    // token-input route; that surfaces as a native sibling outflow which the
+    // no-sibling-drain check (assertion 3) would otherwise reject. Tolerate it up
+    // to the smaller of the tx's declared native value and the fixed cap — never
+    // the full value, which a hostile quote could inflate to the whole balance.
+    // assertSwapOutcome applies this only for bridges and only to native.
+    let siblingDustThreshold = 0n;
+    try {
+      const declaredValue = BigInt(tx.value ?? 0);
+      siblingDustThreshold = declaredValue < EVM_BRIDGE_NATIVE_FEE_SLACK ? declaredValue : EVM_BRIDGE_NATIVE_FEE_SLACK;
+    } catch { /* non-integer value → leave 0n, assertion 3 stays strict */ }
+    const outcome = assertSwapOutcome(quoteData.request, quote, sim, { slippage: quoteData.slippage, expectedSpenders, siblingDustThreshold });
     if (outcome.outputAssertionSkipped) {
       log('  ℹ Bridge: input-outflow and sibling checks ran; output arrives on the destination chain and is not simulated here.');
     }
@@ -1086,6 +1097,49 @@ export async function estimateEvmGas(chain, { from, to, data, value }) {
   }
 }
 
+/**
+ * Parse a gas field from quote/tx data (decimal or 0x-prefixed hex).
+ */
+function parseGasField(v) {
+  if (v === undefined || v === null || v === '') return 0;
+  if (typeof v === 'number') return v;
+  if (typeof v === 'string' && v.startsWith('0x')) return parseInt(v, 16);
+  return parseInt(v, 10);
+}
+
+/**
+ * Resolve gas limit for an EVM swap from quote fields. When both quote.gas and
+ * tx.gas/gasLimit are zero/missing, fall back to eth_estimateGas (×1.5) then 210000.
+ */
+export async function resolveEvmSwapGasLimit(currentQuote, { chain, from }) {
+  const txData = currentQuote.transaction;
+  const apiGas = parseGasField(currentQuote.gas);
+  const txGas = parseGasField(txData.gas || txData.gasLimit);
+  let finalGas = apiGas > 0 ? apiGas : txGas;
+  if (finalGas === 0) {
+    const estimated = await estimateEvmGas(chain, {
+      from,
+      to: txData.to,
+      data: txData.data || '0x',
+      value: txData.value ? '0x' + BigInt(txData.value).toString(16) : '0x0',
+    });
+    if (estimated) finalGas = Math.ceil(estimated * 1.5);
+    if (finalGas === 0) finalGas = 210000;
+  }
+  return finalGas;
+}
+
+/** Log when gas was resolved from API vs estimate/fallback (all EVM signing paths). */
+function logEvmSwapGasResolution(log, currentQuote, txData, finalGas) {
+  const apiGas = parseGasField(currentQuote.gas);
+  const txGas = parseGasField(txData.gas || txData.gasLimit);
+  if (apiGas > 0 && finalGas !== txGas) {
+    log(`  ℹ Using API gas ${finalGas} (tx.gas was ${txGas})`);
+  } else if (finalGas > 0 && apiGas === 0 && txGas === 0) {
+    log(`  ℹ Using estimated gas ${finalGas} (quote had no gas)`);
+  }
+}
+
 /**
  * Read the current on-chain ERC-20 allowance, throwing on any RPC failure
  * instead of masking it. checkErc20Allowance below wraps this with a
@@ -2537,7 +2591,16 @@ EXAMPLES:
                   continue;
                 }
               } else {
-                if (txValue > 0n) {
+                // A token-input swap sends no native value — except a cross-chain
+                // bridge may carry a bounded native fee via msg.value. Allow that up
+                // to the same ceiling assertSwapOutcome tolerates as a native sibling
+                // (verifySwapOutcome runs below and re-bounds the actual simulated
+                // outflow to min(tx.value, cap)); reject any other non-zero value, and
+                // any bridge fee above the ceiling.
+                const bridgeFeeAllowed = quoteData?.request
+                  && isBridgeRequest(quoteData.request)
+                  && txValue <= EVM_BRIDGE_NATIVE_FEE_SLACK;
+                if (txValue > 0n && !bridgeFeeAllowed) {
                   log(`  ❌ ERC-20 swap has non-zero tx.value (${txValue}) for ${quoteName} — aborting`);
                   if (qi + 1 < endIndex) log(`  Trying next quote...`);
                   lastQuoteError = `${quoteName} unexpected tx.value`;
@@ -2713,30 +2776,9 @@ EXAMPLES:
                 }
               }
 
-              // Gas resolution — fall back to eth_estimateGas if quote has no gas
               const txData = currentQuote.transaction;
-              const apiGas = parseInt(currentQuote.gas || '0');
-              const txGas = parseInt(txData.gas || txData.gasLimit || '0');
-              let finalGas = apiGas > 0 ? apiGas : txGas;
-              if (finalGas === 0) {
-                try {
-                  const rpcUrl = CHAIN_RPCS[chain];
-                  const estRes = await fetch(rpcUrl, {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({
-                      jsonrpc: '2.0', id: 1, method: 'eth_estimateGas',
-                      params: [{
-                        from: walletAddress, to: txData.to, data: txData.data || '0x',
-                        value: txData.value ? '0x' + BigInt(txData.value).toString(16) : '0x0',
-                      }],
-                    }),
-                  });
-                  const estBody = await estRes.json();
-                  if (estBody.result) finalGas = Math.ceil(parseInt(estBody.result, 16) * 1.5);
-                } catch { /* ignore */ }
-                if (finalGas === 0) finalGas = 210000;
-              }
+              const finalGas = await resolveEvmSwapGasLimit(currentQuote, { chain, from: walletAddress });
+              logEvmSwapGasResolution(log, currentQuote, txData, finalGas);
 
               log('  Fetching nonce...');
               const nonce = await getEvmNonce(chain, walletAddress);
@@ -2904,7 +2946,16 @@ EXAMPLES:
                   continue;
                 }
               } else {
-                if (txValue > 0n) {
+                // A token-input swap sends no native value — except a cross-chain
+                // bridge may carry a bounded native fee via msg.value. Allow that up
+                // to the same ceiling assertSwapOutcome tolerates as a native sibling
+                // (verifySwapOutcome runs below and re-bounds the actual simulated
+                // outflow to min(tx.value, cap)); reject any other non-zero value, and
+                // any bridge fee above the ceiling.
+                const bridgeFeeAllowed = quoteData?.request
+                  && isBridgeRequest(quoteData.request)
+                  && txValue <= EVM_BRIDGE_NATIVE_FEE_SLACK;
+                if (txValue > 0n && !bridgeFeeAllowed) {
                   log(`  ❌ ERC-20 swap has non-zero tx.value (${txValue}) for ${quoteName} — aborting`);
                   if (qi + 1 < endIndex) log(`  Trying next quote...`);
                   lastQuoteError = `${quoteName} unexpected tx.value`;
@@ -3098,11 +3149,9 @@ EXAMPLES:
                 }
               }
 
-              // Resolve gas
               const txData = currentQuote.transaction;
-              const apiGas = parseInt(currentQuote.gas || "0");
-              const txGas = parseInt(txData.gas || txData.gasLimit || "0");
-              const finalGas = apiGas > 0 ? apiGas : txGas;
+              const finalGas = await resolveEvmSwapGasLimit(currentQuote, { chain, from: wcAddress });
+              logEvmSwapGasResolution(log, currentQuote, txData, finalGas);
 
               // Send transaction via WalletConnect
               log('  Sending transaction via WalletConnect...');
@@ -3232,7 +3281,16 @@ EXAMPLES:
                   continue;
                 }
               } else {
-                if (txValue > 0n) {
+                // A token-input swap sends no native value — except a cross-chain
+                // bridge may carry a bounded native fee via msg.value. Allow that up
+                // to the same ceiling assertSwapOutcome tolerates as a native sibling
+                // (verifySwapOutcome runs below and re-bounds the actual simulated
+                // outflow to min(tx.value, cap)); reject any other non-zero value, and
+                // any bridge fee above the ceiling.
+                const bridgeFeeAllowed = quoteData?.request
+                  && isBridgeRequest(quoteData.request)
+                  && txValue <= EVM_BRIDGE_NATIVE_FEE_SLACK;
+                if (txValue > 0n && !bridgeFeeAllowed) {
                   log(`  ❌ ERC-20 swap has non-zero tx.value (${txValue}) for ${quoteName} — aborting`);
                   if (qi + 1 < endIndex) log(`  Trying next quote...`);
                   lastQuoteError = `${quoteName} unexpected tx.value`;
@@ -3405,16 +3463,9 @@ EXAMPLES:
                 }
               }
 
-              // 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.
               const txData = currentQuote.transaction;
-              const apiGas = parseInt(currentQuote.gas || "0");
-              const txGas = parseInt(txData.gas || txData.gasLimit || "0");
-              const finalGas = apiGas > 0 ? apiGas : txGas;
-              if (finalGas !== txGas) {
-                log(`  ℹ Using API gas ${finalGas} (tx.gas was ${txGas})`);
-              }
+              const finalGas = await resolveEvmSwapGasLimit(currentQuote, { chain, from: walletAddress });
+              logEvmSwapGasResolution(log, currentQuote, txData, finalGas);
               if (txData.gasLimit) txData.gasLimit = String(finalGas);
               else txData.gas = String(finalGas);
 

package/src/wallet.js

@@ -281,27 +281,32 @@ function hashPassword(password) {
 
 // ============= Prompt Helper =============
 
-async function promptPassword(question, deps = {}) {
+// Exported for testing (mirrors the exported `prompt` in cli.js). The streams
+// are injectable so the masking behavior can be exercised without a real TTY.
+export async function promptPassword(question, deps = {}, { input: inStream = process.stdin, output: outStream = process.stderr } = {}) {
   const promptFn = deps.promptFn;
   if (promptFn) {
     return promptFn(question, true);
   }
   // Fallback to readline (only available in --human mode)
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
-    if (process.stdout.isTTY) {
-      process.stdout.write(question);
+    // Gate on stdin, not stdout: raw-mode masking disables the terminal's own
+    // echo, so a redirected stdout (e.g. `wallet export > backup.json`) can no
+    // longer fall through to readline and echo the password in cleartext. Prompt
+    // and mask characters go to stderr so they stay on the terminal and never
+    // pollute — or leak into — a redirected stdout.
+    if (inStream.isTTY) {
+      outStream.write(question);
       let input = '';
-      process.stdin.setRawMode(true);
-      process.stdin.resume();
-      process.stdin.setEncoding('utf8');
+      inStream.setRawMode(true);
+      inStream.resume();
+      inStream.setEncoding('utf8');
       const onData = (char) => {
         if (char === '\n' || char === '\r') {
-          process.stdin.setRawMode(false);
-          process.stdin.pause();
-          process.stdin.removeListener('data', onData);
-          process.stdout.write('\n');
-          rl.close();
+          inStream.setRawMode(false);
+          inStream.pause();
+          inStream.removeListener('data', onData);
+          outStream.write('\n');
           resolve(input);
         } else if (char === '\u0003') {
           process.exit();
@@ -309,11 +314,12 @@ async function promptPassword(question, deps = {}) {
           input = input.slice(0, -1);
         } else {
           input += char;
-          process.stdout.write('*');
+          outStream.write('*');
         }
       };
-      process.stdin.on('data', onData);
+      inStream.on('data', onData);
     } else {
+      const rl = readline.createInterface({ input: inStream, output: outStream });
       rl.question(question, (answer) => { rl.close(); resolve(answer); });
     }
   });
@@ -1039,6 +1045,8 @@ ENVIRONMENT:
   NANSEN_EVM_RPC            Custom Ethereum RPC endpoint (also generic EVM fallback)
   NANSEN_BASE_RPC           Custom Base RPC endpoint
   NANSEN_SOLANA_RPC         Custom Solana RPC endpoint
+  NANSEN_X402_MAX_AMOUNT    Max USD per x402 auto-payment (default 1.00; "unlimited" to disable)
+  NANSEN_X402_ALLOWED_PAYTO Comma-separated recipient allowlist for x402 auto-payment (optional)
 
 EXAMPLES:
   NANSEN_WALLET_PASSWORD=mypass nansen wallet create --name trading

package/src/walletconnect-x402.js

@@ -9,6 +9,7 @@ import crypto from 'crypto';
 import { NansenError, ErrorCode } from './api.js';
 import { wcExec } from './walletconnect-exec.js';
 import { EVM_CHAIN_IDS } from './chain-ids.js';
+import { evaluatePaymentRequirement, resolvePaymentAmount, resolvePayTo } from './x402-policy.js';
 
 /**
  * Check if a WalletConnect wallet session is active.
@@ -52,9 +53,9 @@ function parseChainId(network) {
  * Build EIP-712 typed data for TransferWithAuthorization (EIP-3009).
  */
 export function buildEIP712TypedData({ fromAddress, requirement }) {
-  const { asset, payTo, extra, maxTimeoutSeconds } = requirement;
-  // x402 uses "amount", fall back to "maxAmountRequired" for compatibility
-  const amount = requirement.amount || requirement.maxAmountRequired;
+  const payTo = resolvePayTo(requirement);
+  const { asset, extra, maxTimeoutSeconds } = requirement;
+  const amount = resolvePaymentAmount(requirement);
 
   // Determine chain ID: extra.chainId > parsed from network > fallback map > base
   const chainId = extra.chainId || parseChainId(requirement.network) || EVM_CHAIN_IDS[requirement.chain] || EVM_CHAIN_IDS.base;
@@ -121,7 +122,7 @@ export function buildPaymentSignatureHeader({ signature, authorization, resource
  */
 function formatPaymentAmount(requirement) {
   const { extra } = requirement;
-  const rawAmount = requirement.amount || requirement.maxAmountRequired;
+  const rawAmount = resolvePaymentAmount(requirement);
   const symbol = extra.symbol || extra.name || 'tokens';
   const decimals = extra.decimals || 6;
   const amount = Number(rawAmount) / Math.pow(10, decimals);
@@ -171,15 +172,21 @@ export async function handleX402Payment(paymentRequirements) {
     );
   }
 
-  // 3. Build EIP-712 typed data
+  // 3. Evaluate payment policy before touching any signing material
+  const decision = evaluatePaymentRequirement(requirement);
+  if (!decision.ok) {
+    throw new Error(decision.reason);
+  }
+
+  // 4. Build EIP-712 typed data
   const typedData = buildEIP712TypedData({ fromAddress, requirement });
   const typedDataJson = JSON.stringify(typedData);
 
-  // 4. Log payment info to stderr (stdout is for JSON output)
+  // 5. Log payment info to stderr (stdout is for JSON output)
   const amountStr = formatPaymentAmount(requirement);
   process.stderr.write(`x402: Requesting payment approval (${amountStr})...\n`);
 
-  // 5. Sign via walletconnect CLI (120s timeout for user approval)
+  // 6. Sign via walletconnect CLI (120s timeout for user approval)
   let signResult;
   try {
     const output = await wcExec('walletconnect', ['sign-typed-data', typedDataJson], 120000);
@@ -195,11 +202,11 @@ export async function handleX402Payment(paymentRequirements) {
     );
   }
 
-  // 6. Build Payment-Signature header (authorization values must be strings per x402 spec)
+  // 7. Build Payment-Signature header (authorization values must be strings per x402 spec)
   const authorization = {
     from: fromAddress,
-    to: requirement.payTo,
-    value: (requirement.amount || requirement.maxAmountRequired).toString(),
+    to: resolvePayTo(requirement),
+    value: resolvePaymentAmount(requirement).toString(),
     validAfter: typedData.message.validAfter.toString(),
     validBefore: typedData.message.validBefore.toString(),
     nonce: typedData.message.nonce,

package/src/x402-evm.js

@@ -6,6 +6,7 @@
 
 import crypto from 'crypto';
 import { keccak256, signSecp256k1 } from './crypto.js';
+import { resolvePaymentAmount, resolvePayTo } from './x402-policy.js';
 
 // ============= EIP-712 Type Hashing =============
 
@@ -229,6 +230,7 @@ export function createEvmPaymentPayload(requirements, privateKeyHex, walletAddre
   const now = Math.floor(Date.now() / 1000);
   const validAfter = '0';
   const validBefore = String(now + 3600);
+  const amount = resolvePaymentAmount(requirements);
 
   // EIP-712 domain
   const domain = {
@@ -241,8 +243,8 @@ export function createEvmPaymentPayload(requirements, privateKeyHex, walletAddre
   // EIP-3009 message
   const message = {
     from: walletAddress,
-    to: requirements.pay_to || requirements.payTo,
-    value: BigInt(requirements.amount),
+    to: resolvePayTo(requirements),
+    value: BigInt(amount),
     validAfter: BigInt(validAfter),
     validBefore: BigInt(validBefore),
     nonce: nonce,
@@ -260,7 +262,7 @@ export function createEvmPaymentPayload(requirements, privateKeyHex, walletAddre
       authorization: {
         from: walletAddress,
         to: message.to,
-        value: String(requirements.amount),
+        value: String(amount),
         validAfter: validAfter,
         validBefore: validBefore,
         nonce: nonce,
@@ -301,15 +303,16 @@ export function createPermit2ExactPayload(requirements, privateKeyHex, walletAdd
     throw new Error('spenderAddress missing from requirements.extra (required for permit2-exact)');
   }
 
-  const payTo = requirements.pay_to || requirements.payTo;
+  const payTo = resolvePayTo(requirements);
   const now = Math.floor(Date.now() / 1000);
   // 256-bit random nonce — Permit2 uses an unordered nonce bitmap.
   const nonce = BigInt('0x' + crypto.randomBytes(32).toString('hex')).toString();
   const deadline = String(now + 3600);
   const validAfter = String(now - 60); // allow clock skew
+  const amount = resolvePaymentAmount(requirements);
 
   const message = {
-    permitted: { token: requirements.asset, amount: BigInt(requirements.amount) },
+    permitted: { token: requirements.asset, amount: BigInt(amount) },
     spender,
     nonce: BigInt(nonce),
     deadline: BigInt(deadline),
@@ -324,7 +327,7 @@ export function createPermit2ExactPayload(requirements, privateKeyHex, walletAdd
     x402Version: 2,
     payload: {
       permit2Authorization: {
-        permitted: { token: requirements.asset, amount: String(requirements.amount) },
+        permitted: { token: requirements.asset, amount: String(amount) },
         from: walletAddress,
         spender,
         nonce,

package/src/x402-policy.js

@@ -0,0 +1,201 @@
+/**
+ * x402 payment policy guard.
+ * Decides whether an auto-payment is safe to sign before any signature is produced.
+ * Three layers: known-asset allowlist, optional payTo allowlist, per-payment USD cap.
+ */
+
+import { EVM_X402_TOKENS, SVM_X402_TOKENS } from './x402-tokens.js';
+import { getWalletConfig } from './wallet.js';
+
+/**
+ * True for the exact Solana CAIP-2 network prefix ("solana:..."), matching
+ * isSvmNetwork() in x402-svm.js. Duplicated here (rather than imported) to
+ * avoid a circular dependency: x402-svm.js imports resolvePaymentAmount from
+ * this module.
+ */
+function isSvmNetworkString(network) {
+  return typeof network === 'string' && network.startsWith('solana:');
+}
+
+/**
+ * Look up the known token entry for a (network, asset) pair.
+ * Returns { token, symbol, decimals } or null if the pair is not a known
+ * Nansen x402 payment asset.
+ *
+ * EVM addresses are compared case-insensitively (hex is case-insensitive
+ * modulo EIP-55 checksum casing). Solana mint addresses are base58 and
+ * MUST be compared case-sensitively — flipping the case of a base58 string
+ * decodes to different bytes entirely, not the same address in a different
+ * checksum casing.
+ */
+export function resolveKnownToken(network, asset) {
+  if (typeof network !== 'string' || typeof asset !== 'string') return null;
+  if (network.startsWith('eip155:')) {
+    const table = EVM_X402_TOKENS[network];
+    if (!table) return null;
+    return table.find(t => t.token.toLowerCase() === asset.toLowerCase()) || null;
+  }
+  if (isSvmNetworkString(network)) {
+    const table = SVM_X402_TOKENS['solana'];
+    if (!table) return null;
+    return table.find(t => t.token === asset) || null;
+  }
+  return null;
+}
+
+// Default per-payment ceiling in USD. x402 API calls cost cents; $1.00 is a
+// conservative safety ceiling — raise NANSEN_X402_MAX_AMOUNT if legitimate
+// calls exceed it (they should not for normal API usage).
+export const DEFAULT_X402_MAX_AMOUNT_USD = 1.0;
+
+/**
+ * Resolve the per-payment USD cap.
+ * Precedence: NANSEN_X402_MAX_AMOUNT env var > wallet config x402MaxAmount > default.
+ * Returns a positive number, or Infinity when explicitly set to "unlimited".
+ */
+export function resolveMaxAmountUsd() {
+  const env = process.env.NANSEN_X402_MAX_AMOUNT;
+  // An empty/whitespace-only value (e.g. an exported-but-unset shell var) must
+  // be treated as unset, not as Number('') === 0 — a $0.00 cap would refuse
+  // every real payment.
+  if (env !== undefined && env.trim() !== '') {
+    if (env.trim().toLowerCase() === 'unlimited') return Infinity;
+    const n = Number(env);
+    if (Number.isFinite(n) && n >= 0) return n;
+    // fall through on garbage value
+  }
+  try {
+    const cfg = getWalletConfig();
+    if (cfg && cfg.x402MaxAmount !== undefined) {
+      const n = Number(cfg.x402MaxAmount);
+      if (Number.isFinite(n) && n >= 0) return n;
+    }
+  } catch { /* no config yet */ }
+  return DEFAULT_X402_MAX_AMOUNT_USD;
+}
+
+/**
+ * Optional payTo allowlist.
+ * If NANSEN_X402_ALLOWED_PAYTO is set (comma-separated addresses), only those
+ * recipients may be paid. Unset = no recipient restriction.
+ *
+ * Comparison is case-insensitive for EVM (hex) but case-sensitive for Solana
+ * (base58) — see resolveKnownToken for why. `network` is required to know
+ * which rule applies; omit it only for EVM-style (case-insensitive) checks.
+ */
+export function isPayToAllowed(payTo, network) {
+  const raw = process.env.NANSEN_X402_ALLOWED_PAYTO;
+  if (!raw) return true;
+  const caseSensitive = isSvmNetworkString(network);
+  const normalize = (s) => (caseSensitive ? s.trim() : s.trim().toLowerCase());
+  const allow = raw.split(',').map(normalize).filter(Boolean);
+  if (allow.length === 0) return true;
+  return typeof payTo === 'string' && allow.includes(normalize(payTo));
+}
+
+/**
+ * Resolve the payment amount field, preferring `amount` over the legacy
+ * `maxAmountRequired` alias (older x402 implementations only send the latter).
+ * A present-but-empty `amount` (e.g. "") is treated as missing so it falls
+ * through to `maxAmountRequired` here too — the one place this decision is
+ * made. Signers must call this instead of re-deriving the fallback themselves;
+ * a mismatched `??` vs `||` between here and a signer is exactly the
+ * amount-substitution bypass this guard exists to prevent.
+ */
+export function resolvePaymentAmount(requirement) {
+  const amount = requirement.amount;
+  if (amount !== undefined && amount !== null && amount !== '') return amount;
+  return requirement.maxAmountRequired;
+}
+
+/**
+ * Resolve the payment recipient field, preferring `payTo` (camelCase) over
+ * the legacy `pay_to` (snake_case) alias. A present-but-empty `payTo` (e.g.
+ * "") is treated as missing, exactly like resolvePaymentAmount — the same
+ * single-source-of-truth rule signers must use instead of re-deriving the
+ * fallback themselves.
+ */
+export function resolvePayTo(requirement) {
+  const payTo = requirement.payTo;
+  if (payTo !== undefined && payTo !== null && payTo !== '') return payTo;
+  return requirement.pay_to;
+}
+
+/**
+ * Decide whether an x402 payment requirement is safe to auto-sign.
+ * Returns { ok: true, usd, symbol } when allowed, or { ok: false, reason }
+ * with a human-readable, actionable reason when refused.
+ *
+ * Enforces in order: known (network, asset) allowlist, optional payTo
+ * allowlist, per-payment USD cap. Never signs; pure decision.
+ */
+export function evaluatePaymentRequirement(requirement) {
+  const network = requirement.network;
+  const asset = requirement.asset;
+  const payTo = resolvePayTo(requirement);
+  const amountRaw = resolvePaymentAmount(requirement);
+
+  const known = resolveKnownToken(network, asset);
+  if (!known) {
+    return {
+      ok: false,
+      reason:
+        `Refusing to auto-pay: asset ${asset} on ${network} is not a recognized ` +
+        `Nansen payment token. No signature was produced.`,
+    };
+  }
+
+  if (payTo === undefined || payTo === null || payTo === '') {
+    return {
+      ok: false,
+      reason: 'Refusing to auto-pay: payTo field is missing from the payment requirement.',
+    };
+  }
+
+  if (!isPayToAllowed(payTo, network)) {
+    return {
+      ok: false,
+      reason: `Refusing to auto-pay: recipient ${payTo} is not in NANSEN_X402_ALLOWED_PAYTO.`,
+    };
+  }
+
+  if (amountRaw === undefined || amountRaw === null) {
+    return { ok: false, reason: 'Refusing to auto-pay: amount field is missing from the payment requirement.' };
+  }
+
+  let usd;
+  try {
+    // BigInt base units → USD. Keep integer/fraction split to avoid float loss
+    // on large values; final Number() is safe for display-scale amounts.
+    const base = BigInt(amountRaw);
+    // A transfer authorization must be for a positive amount; a negative value
+    // is never legitimate and should never be signed.
+    if (base < 0n) {
+      return { ok: false, reason: `Refusing to auto-pay: negative amount ${amountRaw}.` };
+    }
+    const scale = 10n ** BigInt(known.decimals);
+    // Number arithmetic is precise enough for stablecoin amounts at 6 or 18
+    // decimals against a dollar-scale cap. Would need BigInt-native comparison
+    // if supported decimals or cap magnitudes change significantly.
+    usd = Number(base / scale) + Number(base % scale) / Number(scale);
+  } catch {
+    return { ok: false, reason: `Refusing to auto-pay: unparseable amount ${amountRaw}.` };
+  }
+
+  // Cap is inclusive: an amount exactly at the cap is allowed (usd > cap, not >=).
+  // Note a cap of 0 still permits a zero-value payment (0 > 0 is false); use
+  // NANSEN_X402_ALLOWED_PAYTO or an unfunded wallet to block signing entirely.
+  const cap = resolveMaxAmountUsd();
+  if (usd > cap) {
+    const capStr = Number.isFinite(cap) ? `$${cap.toFixed(2)}` : 'unlimited';
+    return {
+      ok: false,
+      reason:
+        `Refusing to auto-pay $${usd.toFixed(2)} ${known.symbol}: exceeds the ` +
+        `${capStr} per-payment cap. To authorize, raise it with ` +
+        `NANSEN_X402_MAX_AMOUNT=<usd> (or NANSEN_X402_MAX_AMOUNT=unlimited to disable).`,
+    };
+  }
+
+  return { ok: true, usd, symbol: known.symbol };
+}

package/src/x402-svm.js

@@ -6,6 +6,7 @@
 import crypto from 'crypto';
 import { base58Encode, base58DecodePubkey } from './wallet.js';
 import { encodeCompactU16, deriveATA as _deriveATA } from './transfer.js';
+import { resolvePaymentAmount, resolvePayTo } from './x402-policy.js';
 
 // ============= Constants =============
 
@@ -180,8 +181,8 @@ export function buildUnsignedSvmTransaction(
   }
 
   const mint = requirements.asset;
-  const amount = BigInt(requirements.amount);
-  const payTo = requirements.pay_to || requirements.payTo;
+  const amount = BigInt(resolvePaymentAmount(requirements));
+  const payTo = resolvePayTo(requirements);
 
   // Derive ATAs
   const sourceATA = deriveATA(walletAddress, mint, tokenProgram);

package/src/x402-tokens.js

@@ -0,0 +1,29 @@
+/**
+ * Known x402 payment tokens per network.
+ * Leaf module — imported by both x402.js and x402-policy.js to avoid circular deps.
+ */
+
+// Known payment tokens per EVM network (eip155:<chainId>).
+// decimals is per token — BSC stablecoins are 18-decimal BEP-20 deployments,
+// unlike the 6-decimal tokens on Base and X Layer.
+export const EVM_X402_TOKENS = {
+  'eip155:8453': [
+    { token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', symbol: 'USDC', decimals: 6 }, // Base USDC
+  ],
+  'eip155:196': [
+    { token: '0x779Ded0c9e1022225f8E0630b35a9b54bE713736', symbol: 'USDT0', decimals: 6 }, // X Layer USDT0
+  ],
+  'eip155:56': [
+    { token: '0xcE24439F2D9C6a2289F741120FE202248B666666', symbol: 'U', decimals: 18 }, // United Stables
+    { token: '0x8d0d000ee44948fc98c9b98a4fa4921476f08b0d', symbol: 'USD1', decimals: 18 }, // World Liberty Financial USD
+    { token: '0x55d398326f99059fF775485246999027B3197955', symbol: 'USDT', decimals: 18 }, // Tether USD
+    { token: '0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d', symbol: 'USDC', decimals: 18 }, // Binance-Peg USD Coin
+  ],
+};
+
+// Known payment tokens on Solana.
+export const SVM_X402_TOKENS = {
+  solana: [
+    { token: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', symbol: 'USDC', decimals: 6 },
+  ],
+};