nansen-cli 1.42.0 → 1.43.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.43.0
+
+### Minor Changes
+
+- [#539](https://github.com/nansen-ai/nansen-cli/pull/539) [`2ba6c40`](https://github.com/nansen-ai/nansen-cli/commit/2ba6c40376b5c1cc4d7105592cd63d47b5130f02) Thanks [@kome12](https://github.com/kome12)! - x402 auto-payment now refuses to sign payments for unknown tokens/networks and enforces a configurable per-payment USD cap (NANSEN_X402_MAX_AMOUNT, default $1.00) before signing.
+
+### Patch Changes
+
+- [#535](https://github.com/nansen-ai/nansen-cli/pull/535) [`863ef23`](https://github.com/nansen-ai/nansen-cli/commit/863ef2372dd042eb37d198f16513eedf5df97dab) Thanks [@crazywriter1](https://github.com/crazywriter1)! - Fix EVM swap execution when quotes omit gas limits: WalletConnect and local wallet paths now fall back to eth_estimateGas (×1.5) and then 210000, matching the Privy path.
+
+- [#541](https://github.com/nansen-ai/nansen-cli/pull/541) [`7492bbe`](https://github.com/nansen-ai/nansen-cli/commit/7492bbe6a86cd848168b400ba7c8a53c403d264c) Thanks [@kome12](https://github.com/kome12)! - Refuse x402 auto-payments whose payment requirement is missing a payTo/pay_to recipient, matching the existing missing-amount check. Previously this fell through to the per-signing-path field validation inconsistently, and the WalletConnect path had no check at all.
+
 ## 1.42.0
 
 ### Minor Changes

package/package.json

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

package/src/privy.js

@@ -10,6 +10,7 @@ import fs from "fs";
 import path from "path";
 import { parsePaymentRequirements } from "./x402.js";
 import { isEvmNetwork } from "./x402-evm.js";
+import { evaluatePaymentRequirement, resolvePaymentAmount, resolvePayTo } from "./x402-policy.js";
 import {
   isSvmNetwork,
   getSolanaRpcUrl,
@@ -297,6 +298,11 @@ export async function* createPrivyPaymentSignatures(response, url) {
     const evmWallet = await getPrivyEvmWallet(client);
     if (evmWallet) {
       for (const requirement of evmRequirements) {
+        const decision = evaluatePaymentRequirement(requirement);
+        if (!decision.ok) {
+          console.error(`[x402] ${decision.reason}`);
+          continue;
+        }
         try {
           const typedData = buildEIP712TypedData({
             fromAddress: evmWallet.address,
@@ -311,8 +317,8 @@ export async function* createPrivyPaymentSignatures(response, url) {
 
           const authorization = {
             from: evmWallet.address,
-            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,
@@ -342,6 +348,11 @@ export async function* createPrivyPaymentSignatures(response, url) {
     const solWallet = await getPrivySolanaWallet(client);
     if (solWallet) {
       for (const requirement of svmRequirements) {
+        const svmDecision = evaluatePaymentRequirement(requirement);
+        if (!svmDecision.ok) {
+          console.error(`[x402] ${svmDecision.reason}`);
+          continue;
+        }
         try {
           const rpcUrl = getSolanaRpcUrl(requirement.network);
           const recentBlockhash = await fetchRecentBlockhash(rpcUrl);

package/src/schema.json

@@ -1800,7 +1800,7 @@
       }
     },
     "wallet": {
-      "description": "Wallet management",
+      "description": "Wallet management. x402 auto-payments are guarded by a client-side policy: per-payment USD cap via NANSEN_X402_MAX_AMOUNT (default 1.00; 'unlimited' to disable) and an optional recipient allowlist via NANSEN_X402_ALLOWED_PAYTO (comma-separated addresses).",
       "subcommands": {
         "create": {
           "description": "Create a new wallet"

package/src/trading.js

@@ -1097,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
@@ -2733,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);
@@ -3127,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...');
@@ -3443,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

@@ -1045,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 },
+  ],
+};

package/src/x402.js

@@ -13,6 +13,9 @@ import {
 } from './x402-svm.js';
 import { resolvePassword } from './keychain.js';
 import { CHAIN_RPCS } from './rpc-urls.js';
+import { evaluatePaymentRequirement, resolvePaymentAmount } from './x402-policy.js';
+import { EVM_X402_TOKENS } from './x402-tokens.js';
+export { EVM_X402_TOKENS } from './x402-tokens.js';
 
 /**
  * Parse PaymentRequirements from a 402 response.
@@ -94,19 +97,26 @@ async function hasPermit2Allowance(network, token, owner, amount) {
  * @returns {string|null} Base64 payment signature, or null on failure
  */
 async function buildPaymentForRequirement(requirement, exported, url) {
+  const decision = evaluatePaymentRequirement(requirement);
+  if (!decision.ok) {
+    console.error(`[x402] ${decision.reason}`);
+    return null;
+  }
+
   if (isEvmNetwork(requirement.network)) {
     if ((requirement.extra || {}).assetTransferMethod === 'permit2-exact') {
+      const resolvedAmount = resolvePaymentAmount(requirement);
       const approved = await hasPermit2Allowance(
         requirement.network,
         requirement.asset,
         exported.evm.address,
-        requirement.amount,
+        resolvedAmount,
       );
       if (!approved) {
         console.error(
           `[x402] Skipping ${requirement.network} permit2 option: Permit2 ` +
           `(${PERMIT2_ADDRESS}) allowance for token ${requirement.asset} is ` +
-          `missing or below the payment amount (${requirement.amount}). ` +
+          `missing or below the payment amount (${resolvedAmount}). ` +
           `Send approve(${PERMIT2_ADDRESS}, <amount>) from the wallet to enable it.`,
         );
         return null;
@@ -207,11 +217,6 @@ export async function createPaymentSignature(response, url, options = {}) {
   return null;
 }
 
-/**
- * x402 payment tokens per EVM network, matching the stablecoins the API
- * advertises in 402 `accepts` entries. `decimals` matters: USDT on BNB Smart
- * Chain uses 18 decimals, unlike the 6-decimal tokens on Base and X Layer.
- */
 // RPC endpoint per supported x402 EVM network.
 export const EVM_X402_RPCS = {
   'eip155:8453': CHAIN_RPCS.base,
@@ -223,24 +228,6 @@ function getEvmRpcUrl(network) {
   return EVM_X402_RPCS[network] || null;
 }
 
-// Known payment tokens per network, in the order servers typically advertise
-// them. A network can accept several stablecoins (BSC accepts four); `decimals`
-// is per token — every BSC stablecoin is an 18-decimal BEP-20 deployment,
-// 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
-  ],
-};
 
 /**
  * Check stablecoin balance for x402 payment wallet on the given network.