agentwallet-mcp 1.13.4 → 1.13.6

package/build/index.js

@@ -13,14 +13,15 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { assertPublicUrl, safeFetch, finalUrlOf } from './ssrf-guard.js';
-import { deriveX402Payment, isWithinCap, lookupTrustedDecimals, assertDeclaredDecimals, nativeDecimals, SOLANA_CHAIN_IDS, assetLabel, autopayAssetAllowed, autopayEnvCap, effectiveAutopayCap, maxAuthWindowSeconds, parseDecimalPins, approvalRefusal, authorizationResource, } from './x402-payment.js';
+import { deriveX402Payment, isWithinCap, lookupTrustedDecimals, assertDeclaredDecimals, nativeDecimals, SOLANA_CHAIN_IDS, assetLabel, autopayAssetAllowed, autopayEnvCap, effectiveAutopayCap, maxAuthWindowSeconds, parseDecimalPins, approvalRefusal, authorizationResource, resolveNetworkChainId, normalizeRawAmount, parseAutopayAssets, assetSupportsExact, } from './x402-payment.js';
+import { createHash } from 'node:crypto';
 import { isLocalMode, getLocalAddress, localWalletRecord, localSend, localNativeBalance, localTokenBalance, localSignMessage, resolveRpcUrl, } from './local-wallet.js';
 import { localSignAuthorization, localEthCall, localGetCode, localSignPermit2Upto } from './local-wallet.js';
 import { WRAPPED_NATIVE } from './wrapped-native.js';
-import { buildUptoAuthorization, uptoPayload, permit2AllowanceCalldata, permit2ApproveCalldata, decodeUint, PERMIT2_ADDRESS, } from './x402-permit2.js';
+import { buildUptoAuthorization, uptoPayload, permit2AllowanceCalldata, permit2ApproveCalldata, decodeUint, permit2Address, } from './x402-permit2.js';
 import { assessTokenRisk } from './token-risk.js';
-import { isLegacyAgentWalletAccept, requiredAmount, buildAuthorization, buildPaymentPayload, buildPaymentPayloadRaw, paymentHeaderFor, parsePaymentRequired, parseSettlement, pickOption, knownTokenDomain, parseEip7702Delegation, erc1271ProbeCalldata, classifyErc1271Probe, } from './x402-eip3009.js';
-import { isSolanaLocalMode, getSolanaAddress, solanaWalletRecord, localSolBalance, localSplBalance, localSolTransfer, localSplTransfer, resolveSolanaRpc, } from './local-solana.js';
+import { isLegacyAgentWalletAccept, requiredAmount, buildAuthorization, buildPaymentPayload, buildPaymentPayloadRaw, paymentHeaderFor, parsePaymentRequired, parseSettlement, pickOption, knownTokenDomain, parseEip7702Delegation, erc1271ProbeCalldata, classifyErc1271Probe, settlementVerdict, legacyReceiptAllowed, } from './x402-eip3009.js';
+import { isSolanaLocalMode, getSolanaAddress, solanaWalletRecord, localSolBalance, localSplBalance, localSolTransfer, localSplTransfer, resolveSolanaRpc, mintDecimalsStrict, } from './local-solana.js';
 /** True when either chain family is running non-custodially. */
 function anyLocalMode() {
     return isLocalMode() || isSolanaLocalMode();
@@ -76,7 +77,7 @@ async function routeLocally(path, method, body) {
     const [rawPath, rawQs = ''] = path.split('?');
     const qs = new URLSearchParams(rawQs);
     // POST /wallets/{id}/send
-    if (method === 'POST' && /^\/wallets\/[^/]*\/send$/.test(rawPath)) {
+    if (method === 'POST' && /^\/wallets\/[^/]+\/send$/.test(rawPath)) {
         const chainId = localChainId(body, qs);
         const solanaOp = SOLANA_CHAIN_IDS.has(chainId) || Boolean(body?.token_mint);
         if (solanaOp) {
@@ -209,7 +210,13 @@ async function api(path, method = 'GET', body, extraHeaders) {
        single choke point every funds operation already passes through means no
        tool can quietly stay custodial because someone forgot to update it. */
     if (anyLocalMode()) {
-        const handled = await routeLocally(path, method, body);
+        let handled;
+        try {
+            handled = await routeLocally(path, method, body);
+        }
+        catch (e) {
+            throw new Error(redactRpcSecrets(e)); // viem puts the RPC URL, key and all, in its messages
+        }
         if (handled !== NOT_HANDLED)
             return handled;
     }
@@ -221,15 +228,39 @@ async function api(path, method = 'GET', body, extraHeaders) {
     if (API_USER && API_PASS) {
         headers['Authorization'] = 'Basic ' + Buffer.from(`${API_USER}:${API_PASS}`).toString('base64');
     }
-    const options = { method, headers };
+    // The API host has no reason to send a wallet operation elsewhere: a
+    // redirect is refused instead of followed, so a request body is never
+    // replayed to another origin and another origin's answer is never returned
+    // as the API's (2026-10-04 audit).
+    const options = { method, headers, redirect: 'manual', signal: AbortSignal.timeout(API_TIMEOUT_MS) };
     if (body && method !== 'GET') {
         options.body = JSON.stringify(body);
     }
     const res = await fetch(url, options);
-    const data = await res.json();
-    // Handle 402 Payment Required — auto-pay if a wallet or a local key is configured
-    if (res.status === 402 && (X402_WALLET_ID || anyLocalMode()) && !extraHeaders?.['X-PAYMENT'] && !extraHeaders?.['X-AGW-SKIP-X402']) {
-        return handleX402Payment(data, path, method, body);
+    if (res.status >= 300 && res.status < 400) {
+        throw new Error(`The AgentWallet API host answered ${path} with a redirect (HTTP ${res.status}); refusing to follow it.`);
+    }
+    const text = await res.text();
+    if (text.length > API_MAX_RESPONSE_CHARS)
+        throw new Error(`The AgentWallet API host returned an oversized response (${text.length} characters); refusing to parse it.`);
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`The AgentWallet API host returned a non-JSON response (HTTP ${res.status}).`);
+    }
+    // A 402 from the API host is paid automatically only for a HOSTED wallet the
+    // operator named with AGENTWALLET_WALLET_ID. In local mode the host is not a
+    // custodian and must never be able to make the local key sign: a 402 is
+    // returned as an error and the agent can call pay_x402 explicitly, which
+    // reports what it does (2026-10-04 audit).
+    if (res.status === 402 && !extraHeaders?.['X-PAYMENT'] && !extraHeaders?.['X-AGW-SKIP-X402']) {
+        if (anyLocalMode()) {
+            throw new Error(`The AgentWallet API host asked for payment on ${path}; nothing is paid automatically in local mode. If you trust it, call pay_x402 with that URL so the payment is explicit and reported.`);
+        }
+        if (X402_WALLET_ID)
+            return handleX402Payment(data, path, method, body);
     }
     if (!res.ok) {
         const error = data.error || `HTTP ${res.status}`;
@@ -395,8 +426,10 @@ function isValidAddress(address) {
 }
 // ─── Guard helpers ──────────────────────────────────────────────
 /** Request headers the caller may not set on pay_x402: Host would rename the TLS peer, the rest belong to the client. */
-const FORBIDDEN_REQUEST_HEADERS = new Set(['host', 'content-length', 'transfer-encoding', 'connection', 'upgrade', 'expect', 'te', 'trailer', 'keep-alive']);
+const FORBIDDEN_REQUEST_HEADERS = new Set(['host', 'content-length', 'transfer-encoding', 'connection', 'upgrade', 'expect', 'te', 'trailer', 'keep-alive',
+    'x-payment', 'payment-signature', 'x-payment-response', 'payment-response']); // the payment headers are the tool's own to set
 /** Authorizations signed in this process, keyed by endpoint and requirement, kept until they expire. */
+const signingInFlight = new Map();
 const signedPayments = new Map();
 function looksLikeTxHash(v) {
     return typeof v === 'string' && (/^0x[0-9a-fA-F]{64}$/.test(v) || /^[1-9A-HJ-NP-Za-km-z]{86,88}$/.test(v));
@@ -417,6 +450,18 @@ function redactUrl(u) {
         return u;
     }
 }
+const API_MAX_RESPONSE_CHARS = 8 * 1024 * 1024;
+const API_TIMEOUT_MS = 60_000; // a hosted hop that hangs must not hold a signing gate open
+/* Error text from the local signing path with every URL reduced to its origin
+   and viem's "URL:" / "Request body:" lines dropped: an RPC endpoint carries
+   its API key in the path or query, and a tool result is the agent's context
+   and the client's log (2026-10-04 audit). */
+function redactRpcSecrets(err) {
+    const e = err;
+    let msg = e?.shortMessage ? [e.shortMessage, e.details].filter(Boolean).join(' ') : String(e?.message ?? err);
+    msg = msg.split(/\r?\n/).filter(l => !/^\s*(URL|Request body|Request Arguments|Raw Call Arguments)\s*:/i.test(l)).join('\n').trim();
+    return msg.replace(/[a-z][a-z0-9+.-]*:\/\/[^\s"'<>)]+/gi, (u) => redactUrl(u)); // brackets stay in: IPv6 hosts
+}
 /**
  * Decimals to scale a human amount by. Always the token's own value (registry,
  * then decimals() on chain); a caller-supplied value must agree or the call
@@ -425,12 +470,12 @@ function redactUrl(u) {
 async function verifiedDecimals(chainId, token, given) {
     let trusted = null;
     if (isSolanaChain(chainId)) {
-        trusted = lookupTrustedDecimals(chainId, token);
-        if (trusted === null) {
-            if (given === undefined)
-                throw new Error(`Decimals for mint ${token} are not in the registry; pass decimals explicitly.`);
-            return given; // the token program verifies it on-chain (TransferChecked)
-        }
+        // The mint itself says how many decimals it has; a caller's value only
+        // ever confirms it (2026-10-04 audit: the substituted byte could not catch
+        // an amount already scaled by a wrong guess).
+        trusted = await mintDecimalsStrict(token, chainId);
+        if (trusted === null)
+            throw new Error(`Could not read the decimals of mint ${token} from the chain; refusing to guess the scale of the amount.`);
     }
     else {
         trusted = await resolveTrustedDecimals(chainId, token);
@@ -444,15 +489,23 @@ async function verifiedDecimals(chainId, token, given) {
 function validateGuardEnv() {
     parseDecimalPins(process.env.AGENTWALLET_TOKEN_DECIMALS); // throws on a malformed pin
     for (const name of ['AGENTWALLET_MAX_TX_NATIVE', 'AGENTWALLET_MAX_TX_TOKEN', 'AGENTWALLET_MAX_TX_SOL', 'AGENTWALLET_MAX_AUTOPAY']) {
-        const v = (process.env[name] || '').trim();
+        const raw = process.env[name];
+        const v = (raw || '').trim();
+        // Set but blank is a typo, not "no cap": refuse to start rather than run uncapped.
+        if (raw !== undefined && v === '')
+            throw new Error(`${name} is set but blank. Set it to a number or unset it.`);
         if (v && !/^\d+(\.\d+)?$/.test(v))
             throw new Error(`${name} must be a decimal number, got "${v}".`);
     }
-    for (const e of (process.env.AGENTWALLET_AUTOPAY_ASSETS || '').split(',').map(s => s.trim()).filter(Boolean)) {
-        if (e !== 'native' && !/^0x[0-9a-fA-F]{40}$/.test(e) && !/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(e)) {
-            throw new Error(`AGENTWALLET_AUTOPAY_ASSETS entry "${e}" is not "native", an EVM address or an SPL mint.`);
+    for (const e of parseAutopayAssets(process.env.AGENTWALLET_AUTOPAY_ASSETS)) {
+        if (e.asset !== 'native' && !/^0x[0-9a-f]{40}$/.test(e.asset) && !/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(e.asset)) {
+            throw new Error(`AGENTWALLET_AUTOPAY_ASSETS entry "${e.asset}" is not "native", an EVM address or an SPL mint (optionally prefixed "chainId:").`);
         }
     }
+    const t = (process.env.AGENTWALLET_X402_MAX_TIMEOUT || '').trim();
+    if (t && (!/^\d+$/.test(t) || Number(t) < 60 || Number(t) > 31_536_000)) {
+        throw new Error(`AGENTWALLET_X402_MAX_TIMEOUT must be a whole number of seconds between 60 and 31536000, got "${t}".`);
+    }
 }
 // ─── EVM Helpers ──────────────────────────────────────────────────
 /**
@@ -480,7 +533,7 @@ function formatUnits(raw, decimals) {
     const frac = padded.slice(padded.length - decimals);
     // Trim trailing zeros but keep at least one decimal
     const trimmed = frac.replace(/0+$/, '') || '0';
-    return `${whole}.${trimmed}`;
+    return decimals === 0 ? whole : `${whole}.${trimmed}`; // a 0-decimal amount has no fraction, so it round-trips through parseUnits
 }
 /**
  * Pad an address to 32 bytes (64 hex chars) for ABI encoding.
@@ -503,48 +556,13 @@ function encodeUint256(value) {
 }
 // ─── Server ──────────────────────────────────────────────────────
 // ─── x402 Network Mapping ──────────────────────────────────────
-const X402_NETWORKS = {
-    'ethereum': 1,
-    'base': 8453,
-    'base-sepolia': 84532,
-    'polygon': 137,
-    'arbitrum': 42161,
-    'optimism': 10,
-    'bsc': 56,
-    'avalanche': 43114,
-    'zora': 7777777,
-    'pulsechain': 369,
-    'solana': 900,
-    'solana-devnet': 901,
-};
-// Solana genesis hash prefixes for CAIP-2
-const SOLANA_GENESIS = {
-    900: '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', // mainnet-beta
-    901: 'EtWTRABZaYq6iMfeYKouRu166VU2xqa1', // devnet
-};
 /**
- * Resolve an x402 network identifier to a chain ID.
- * Supports plain names ("base"), CAIP-2 format ("eip155:8453"), and raw chain IDs ("8453").
+ * Resolve an x402 network identifier to a chain ID: plain names ("base"),
+ * CAIP-2 ("eip155:8453", "solana:<genesis prefix>") and raw ids ("8453").
+ * The table and the parsing live in x402-payment.ts so they can be tested.
  */
 function resolveChainId(network) {
-    const lower = network.toLowerCase();
-    if (X402_NETWORKS[lower])
-        return X402_NETWORKS[lower];
-    const caipMatch = network.match(/^eip155:(\d+)$/);
-    if (caipMatch)
-        return parseInt(caipMatch[1], 10);
-    // Solana CAIP-2: solana:<genesis_prefix>
-    const solanaMatch = network.match(/^solana:(.+)$/);
-    if (solanaMatch) {
-        for (const [chainId, genesis] of Object.entries(SOLANA_GENESIS)) {
-            if (solanaMatch[1] === genesis)
-                return parseInt(chainId, 10);
-        }
-    }
-    const num = parseInt(network, 10);
-    if (!isNaN(num) && num > 0)
-        return num;
-    return null;
+    return resolveNetworkChainId(network);
 }
 // ─── Server ──────────────────────────────────────────────────────
 /**
@@ -561,7 +579,7 @@ function resolveChainId(network) {
 const AddressSchema = z.string().regex(/^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$/, 'Must be a 0x-prefixed 40-hex EVM address or a base58 Solana address');
 const server = new McpServer({
     name: 'agentwallet',
-    version: '1.13.4',
+    version: '1.13.6',
 }, {
     instructions: `AgentWallet gives AI agents their own blockchain wallets. ${anyLocalMode()
         ? 'This server runs in LOCAL (self-custody) mode: the operator supplied the key, signing happens in this process, and the only spend guards are the AGENTWALLET_MAX_TX_* environment caps. There is no server-side pause, daily limit or approval email; pause_wallet, unpause_wallet and delete_wallet are refused.'
@@ -930,7 +948,7 @@ server.tool('approve_token', 'Approve a spender contract to transfer ERC-20 toke
     // Asset risk rides along with the approval (issue #13). It never blocks; it is the
     // caller's call. Skipped for Permit2, which only moves what a signature allows.
     let risk = null;
-    if (spender.toLowerCase() !== PERMIT2_ADDRESS.toLowerCase() && process.env.AGENTWALLET_TOKEN_RISK !== '0') {
+    if (spender.toLowerCase() !== permit2Address(chain_id).toLowerCase() && process.env.AGENTWALLET_TOKEN_RISK !== '0') {
         try {
             risk = await assessTokenRisk(chain_id, token, (to, data) => ethCallHex(chain_id, to, data));
         }
@@ -1159,11 +1177,17 @@ async function ethCallHex(chainId, to, data) {
  * rather than guess.
  */
 async function resolveTokenDomain(chainId, asset, extra) {
-    if (extra?.name && extra?.version)
-        return { name: String(extra.name), version: String(extra.version) };
     const known = knownTokenDomain(chainId, asset);
-    if (known)
+    const declared = (typeof extra?.name === 'string' && typeof extra?.version === 'string') ? { name: extra.name, version: extra.version } : null;
+    if (known) {
+        // A registry token's domain is known; a 402 declaring a different one would only yield a signature the token rejects.
+        if (declared && (declared.name !== known.name || declared.version !== known.version)) {
+            throw new Error(`x402: the endpoint declared EIP-712 domain "${serverText(declared.name)}"/"${serverText(declared.version)}" for ${asset} on chain ${chainId}, but that token's domain is "${known.name}"/"${known.version}"; refusing to sign under a domain the token would reject.`);
+        }
         return known;
+    }
+    if (declared)
+        return declared;
     let name = '', version = '';
     try {
         name = decodeAbiString(await ethCallHex(chainId, asset, '0x06fdde03')); // name()
@@ -1176,6 +1200,13 @@ async function resolveTokenDomain(chainId, asset, extra) {
     }
     return { name, version };
 }
+/** Text an endpoint wrote, bounded so it cannot flood the agent's context. */
+function serverText(s) {
+    if (s === undefined || s === null)
+        return null;
+    const t = String(s);
+    return t.length > 300 ? t.slice(0, 300) + '…' : t;
+}
 /** Sign the authorization with whichever custody mode is active (local key, or the hosted signer). */
 async function signAuthorization(walletId, chainId, asset, domain, auth, approvalId) {
     const r = (await api(`/wallets/${walletId}/x402/authorize`, 'POST', {
@@ -1192,7 +1223,7 @@ async function signAuthorization(walletId, chainId, asset, domain, auth, approva
 /** Sign a Permit2 upto authorization with whichever custody mode is active. */
 async function signPermit2(walletId, chainId, auth, approvalId) {
     const r = (await api(`/wallets/${walletId}/x402/permit2`, 'POST', {
-        chain_id: chainId, asset: auth.permitted.token, amount: auth.permitted.amount, spender: auth.spender, permit2: PERMIT2_ADDRESS,
+        chain_id: chainId, asset: auth.permitted.token, amount: auth.permitted.amount, spender: auth.spender, permit2: permit2Address(chainId),
         nonce: auth.nonce, deadline: auth.deadline, to: auth.witness.to, facilitator: auth.witness.facilitator, valid_after: auth.witness.validAfter,
         ...(approvalId ? { approval_id: approvalId } : {}),
     }, { 'X-AGW-SKIP-X402': 'true' }));
@@ -1206,8 +1237,8 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
     'parses the payment requirements (v1 body or v2 PAYMENT-REQUIRED header), signs an EIP-3009 ' +
     'TransferWithAuthorization for the "exact" scheme (no gas, nothing broadcast by the payer), and retries ' +
     'the request with the payment header. AgentWallet paywalls are paid by on-chain transfer instead. ' +
-    'The "upto" scheme is refused, never approximated. Returns the final response and the settlement ' +
-    'receipt. Supports the x402 open payment standard (https://x402.org). Set max_payment to cap spend.', {
+    'The "upto" scheme is settled with a Permit2 authorization bounded by the cap. Returns the final response and the settlement ' +
+    'receipt. Supports the x402 open payment standard (https://x402.org). max_payment can only lower the operator\'s cap for one call.', {
     url: z.string().url().describe('The URL to access (will handle 402 payment if required)'),
     wallet_id: z.number().int().describe('Wallet ID to pay from'),
     method: z.string().default('GET').describe('HTTP method (GET, POST, PUT, DELETE)'),
@@ -1216,10 +1247,8 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
         'endpoint redirects to a different origin they are dropped, not forwarded.'),
     body: z.string().optional().describe('Optional request body for POST/PUT requests'),
     max_payment: z.string().optional().describe('Maximum payment in human-readable format (e.g. "1.00" for 1 USDC). ' +
-        'Rejects payments above this amount. If omitted, a default cap of ' +
-        'AGENTWALLET_MAX_AUTOPAY (default "1") is applied, so an untrusted 402 ' +
-        'endpoint can never authorize an unbounded payment. Set this explicitly ' +
-        'to allow a larger single payment.'),
+        'Lowers the operator\'s AGENTWALLET_MAX_AUTOPAY ceiling (default "1") for this one call; ' +
+        'it can never raise it, and a value above the ceiling is ignored and reported as max_payment_ignored.'),
     prefer_chain: z.number().int().optional().describe('Preferred chain ID if the server accepts payment on multiple chains ' +
         '(e.g. 8453 for Base, 1 for Ethereum)'),
     request_approval: z.boolean().optional().describe('Hosted wallets only. When the payment exceeds the cap, email the wallet owner an approve/deny link ' +
@@ -1319,16 +1348,14 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
             payment_required: true,
             payment_made: false,
             error: picked.reason,
-            offered: accepts.map(a => ({ scheme: a.scheme, network: a.network, amount: requiredAmount(a), asset: a.asset ?? a.extra?.token ?? null })),
+            offered: accepts.slice(0, 10).map(a => ({ scheme: serverText(a.scheme), network: serverText(a.network), amount: serverText(requiredAmount(a)), asset: serverText(a.asset ?? a.extra?.token ?? null) })),
+            server_text_is_untrusted: true,
         });
     }
     const option = picked.option;
     const chainId = picked.chainId;
     const isUpto = option.scheme === 'upto';
-    const rawAmount = requiredAmount(option);
-    if (!/^\d+$/.test(rawAmount)) {
-        throw new Error(`x402: invalid amount "${rawAmount}" in the payment requirements (expected integer base units).`);
-    }
+    const rawAmount = normalizeRawAmount(requiredAmount(option)); // "0010000" and "10000" are one amount
     // Decimals come from the registry or the token contract, NEVER from the 402
     // body. The endpoint controls what it declares, so trusting it would let a
     // hostile server inflate the cap and misreport the amount shown to the agent.
@@ -1352,6 +1379,20 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
             error: assetPolicy.reason,
         });
     }
+    // Step 3c: The tx-hash receipt flow (an on-chain transfer, final the moment
+    // it is broadcast) is only for AgentWallet's own paywalls: the API host or
+    // the origins in AGENTWALLET_LEGACY_PAYWALL_ORIGINS. Any other host sending
+    // the legacy shape gets the standard flow (2026-10-04 round 2). And an
+    // "exact" requirement in a token with no EIP-3009 can never settle, so it
+    // is refused before an approval could be consumed for it.
+    const legacyReceipt = isLegacyAgentWalletAccept(option) && legacyReceiptAllowed(servedFrom, API_BASE, process.env.AGENTWALLET_LEGACY_PAYWALL_ORIGINS);
+    if (!isUpto && !isSolanaChain(chainId) && tokenAddress && !legacyReceipt && !assetSupportsExact(chainId, tokenAddress)) {
+        return jsonResponse({
+            status: 402, payment_required: true, payment_made: false,
+            required_amount: amount, token: tokenLabel, token_address: tokenAddress, network: option.network, chain_id: chainId, pay_to: option.payTo,
+            error: `${tokenLabel} on chain ${chainId} does not implement EIP-3009, so an "exact" x402 payment in it cannot settle; nothing was signed. The endpoint would need an "upto" option or a USDC requirement.`,
+        });
+    }
     // Step 4: Hard per-payment cap, ALWAYS applied. If the caller omits max_payment
     // we fall back to AGENTWALLET_MAX_AUTOPAY (default "1"). Above the cap a hosted
     // wallet can ask its owner instead of refusing: an approval is created, the
@@ -1366,7 +1407,7 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
             status: 402, payment_required: true, payment_made: false,
             required_amount: amount, max_allowed: effectiveMax, cap_source: capSource, token: tokenLabel,
             ...(clamped ? { max_payment_ignored: `max_payment ${max_payment} exceeds the operator ceiling AGENTWALLET_MAX_AUTOPAY=${effectiveMax}; only the operator can raise it.` } : {}),
-            network: option.network, chain_id: chainId, pay_to: option.payTo, description: option.description,
+            network: option.network, chain_id: chainId, pay_to: option.payTo, description: serverText(option.description), server_text_is_untrusted: true,
         };
         const wantApproval = request_approval ?? (process.env.AGENTWALLET_APPROVALS !== '0');
         if (approval_id) {
@@ -1400,8 +1441,8 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
                 ...overCap,
                 error: `Payment of ${amount} ${tokenLabel} exceeds the ${effectiveMax} cap (from ${capSource}).` +
                     (max_payment ? '' : ' No max_payment was provided, so the default cap was applied.') +
-                    (anyLocalMode() ? ' Local mode has no approval channel: raise max_payment, AGENTWALLET_MAX_AUTOPAY or AGENTWALLET_MAX_TX_TOKEN yourself.'
-                        : ' Pass request_approval=true to email the wallet owner for a one-time approval, or raise the cap.'),
+                    (anyLocalMode() ? ' Local mode has no approval channel; the caps are the operator\'s and only the operator can change them. Do not edit the environment or config to raise them.'
+                        : ' Pass request_approval=true to email the wallet owner for a one-time approval; the cap itself is the operator\'s to change.'),
             });
         }
     }
@@ -1410,7 +1451,7 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
     // usage; the payer broadcasts nothing and pays no gas for either. AgentWallet's
     // own paywalls (verified by receipt), native-asset requests and Solana still use
     // a broadcast transfer proved by hash.
-    const standardExact = !isUpto && !isSolanaChain(chainId) && Boolean(tokenAddress) && !isLegacyAgentWalletAccept(option);
+    const standardExact = !isUpto && !isSolanaChain(chainId) && Boolean(tokenAddress) && !legacyReceipt;
     let headerName = 'X-PAYMENT';
     let paymentHeader = '';
     let txHash = null;
@@ -1423,80 +1464,103 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
     // The resource is the whole URL including its query: /buy?id=1 and /buy?id=2
     // are different purchases, and reusing the first signature for the second
     // would report a payment the second resource never received.
-    const cacheKey = [wallet_id, chainId, tokenAddress.toLowerCase(), option.payTo.toLowerCase(), rawAmount, option.scheme, authorizationResource(url)].join('|');
+    // The method and body are part of what was bought: POST {item:A} and
+    // POST {item:B} to one URL are two purchases. Concurrent calls for one key
+    // wait for the first signature instead of each signing a nonce.
+    const bodyDigest = createHash('sha256').update(reqBody ?? '').digest('hex').slice(0, 16);
+    const cacheKey = [wallet_id, chainId, tokenAddress.toLowerCase(), option.payTo.toLowerCase(), rawAmount, option.scheme, authorizationResource(url), (method || 'GET').toUpperCase(), bodyDigest].join('|');
+    const inFlight = signingInFlight.get(cacheKey);
+    if (inFlight && !fresh_authorization)
+        await inFlight;
     const cachedAuth = fresh_authorization ? undefined : signedPayments.get(cacheKey);
     for (const [k, v] of signedPayments)
         if (v.until <= Date.now())
             signedPayments.delete(k);
-    if (cachedAuth && cachedAuth.until > Date.now()) {
-        // Same endpoint, same requirement, still inside the window: re-send the
-        // earlier signature. Its nonce is single-use, so a server that already
-        // settled it cannot settle it again, and one that never did now can.
-        ({ headerName, paymentHeader, txHash, authorization, uptoAuth, payer } = cachedAuth);
-        authorizationReused = true;
-    }
-    else if (isUpto) {
-        payer = await payerAddress(wallet_id);
-        payerDelegationInfo = await payerDelegation(chainId, payer);
-        const allowance = decodeUint(await ethCallHex(chainId, tokenAddress, permit2AllowanceCalldata(payer)));
-        if (allowance < BigInt(rawAmount)) {
-            if (process.env.AGENTWALLET_PERMIT2_AUTO_APPROVE === '1' && assetPolicy.via === 'stablecoin') {
-                const r = (await api(`/wallets/${wallet_id}/send`, 'POST', { to: tokenAddress, value: '0', data: permit2ApproveCalldata(), chain_id: chainId }, skip));
-                permit2ApprovalTx = String(r?.tx_hash || '');
-                await new Promise(res => setTimeout(res, 4000));
-            }
-            else {
-                return jsonResponse({
-                    status: 402, payment_required: true, payment_made: false, permit2_approval_needed: true,
-                    token: tokenLabel, token_address: tokenAddress, chain_id: chainId, payer, permit2: PERMIT2_ADDRESS,
-                    error: `This endpoint uses the x402 "upto" scheme, which settles through Permit2. Wallet ${payer} has not approved ` +
-                        `${tokenLabel} to Permit2 on chain ${chainId}. Call approve_permit2 once for this token (a normal transaction that needs gas), ` +
-                        `or set AGENTWALLET_PERMIT2_AUTO_APPROVE=1, then call pay_x402 again.`,
-                });
-            }
-        }
-        uptoAuth = buildUptoAuthorization(payer, option);
-        const signature = await signPermit2(wallet_id, chainId, uptoAuth, approvalUsed);
-        const payload = buildPaymentPayloadRaw(x402Version, option, uptoPayload(uptoAuth, signature), paymentInfo.resource, paymentInfo.extensions);
-        const h = paymentHeaderFor(x402Version, payload);
-        headerName = h.name;
-        paymentHeader = h.value;
-    }
-    else if (standardExact) {
-        payer = await payerAddress(wallet_id);
-        payerDelegationInfo = await payerDelegation(chainId, payer);
-        const domain = await resolveTokenDomain(chainId, tokenAddress, option.extra);
-        authorization = buildAuthorization(payer, option);
-        const signature = await signAuthorization(wallet_id, chainId, tokenAddress, domain, authorization, approvalUsed);
-        const payload = buildPaymentPayload(x402Version, option, authorization, signature, paymentInfo.resource, paymentInfo.extensions);
-        const h = paymentHeaderFor(x402Version, payload);
-        headerName = h.name;
-        paymentHeader = h.value;
+    let releaseSigning = () => { };
+    if (!(cachedAuth && cachedAuth.until > Date.now())) {
+        const mine = new Promise(r => { releaseSigning = r; });
+        // Released in the finally below, whatever path this call takes. A timer
+        // used to stand in for that and opened the gate under a slow signer, so
+        // a second call signed a second nonce (2026-10-04 round 2); every
+        // network hop inside the gate carries its own timeout instead.
+        signingInFlight.set(cacheKey, mine);
     }
-    else {
-        let txResult;
-        if (isSolanaChain(chainId)) {
-            txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', tokenAddress
-                ? { to: option.payTo, value: rawAmount, token_mint: tokenAddress, token_decimals: trustedDecimals, chain_id: chainId }
-                : { to: option.payTo, value: rawAmount, chain_id: chainId }));
+    try {
+        if (cachedAuth && cachedAuth.until > Date.now()) {
+            // Same endpoint, same requirement, still inside the window: re-send the
+            // earlier signature. Its nonce is single-use, so a server that already
+            // settled it cannot settle it again, and one that never did now can.
+            ({ headerName, paymentHeader, txHash, authorization, uptoAuth, payer } = cachedAuth);
+            authorizationReused = true;
         }
-        else if (tokenAddress) {
-            const calldata = '0xa9059cbb' + padAddress(option.payTo) + encodeUint256(rawAmount);
-            txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', { to: tokenAddress, value: '0', data: calldata, chain_id: chainId }));
+        else if (isUpto) {
+            payer = await payerAddress(wallet_id);
+            payerDelegationInfo = await payerDelegation(chainId, payer);
+            const allowance = decodeUint(await ethCallHex(chainId, tokenAddress, permit2AllowanceCalldata(payer, chainId)));
+            if (allowance < BigInt(rawAmount)) {
+                if (process.env.AGENTWALLET_PERMIT2_AUTO_APPROVE === '1' && assetPolicy.via === 'stablecoin') {
+                    // Approve exactly this payment's maximum, never unlimited (2026-10-04 audit).
+                    const r = (await api(`/wallets/${wallet_id}/send`, 'POST', { to: tokenAddress, value: '0', data: permit2ApproveCalldata(rawAmount, chainId), chain_id: chainId }, skip));
+                    permit2ApprovalTx = String(r?.tx_hash || '');
+                    await new Promise(res => setTimeout(res, 4000));
+                }
+                else {
+                    return jsonResponse({
+                        status: 402, payment_required: true, payment_made: false, permit2_approval_needed: true,
+                        token: tokenLabel, token_address: tokenAddress, chain_id: chainId, payer, permit2: permit2Address(chainId),
+                        error: `This endpoint uses the x402 "upto" scheme, which settles through Permit2. Wallet ${payer} has not approved ` +
+                            `${tokenLabel} to Permit2 on chain ${chainId}. Call approve_permit2 once for this token (a normal transaction that needs gas), ` +
+                            `or set AGENTWALLET_PERMIT2_AUTO_APPROVE=1, then call pay_x402 again.`,
+                    });
+                }
+            }
+            uptoAuth = buildUptoAuthorization(payer, option);
+            const signature = await signPermit2(wallet_id, chainId, uptoAuth, approvalUsed);
+            const payload = buildPaymentPayloadRaw(x402Version, option, uptoPayload(uptoAuth, signature), paymentInfo.resource, paymentInfo.extensions);
+            const h = paymentHeaderFor(x402Version, payload);
+            headerName = h.name;
+            paymentHeader = h.value;
+        }
+        else if (standardExact) {
+            payer = await payerAddress(wallet_id);
+            payerDelegationInfo = await payerDelegation(chainId, payer);
+            const domain = await resolveTokenDomain(chainId, tokenAddress, option.extra);
+            authorization = buildAuthorization(payer, option);
+            const signature = await signAuthorization(wallet_id, chainId, tokenAddress, domain, authorization, approvalUsed);
+            const payload = buildPaymentPayload(x402Version, option, authorization, signature, paymentInfo.resource, paymentInfo.extensions);
+            const h = paymentHeaderFor(x402Version, payload);
+            headerName = h.name;
+            paymentHeader = h.value;
         }
         else {
-            txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', { to: option.payTo, value: rawAmount, data: '', chain_id: chainId }));
+            let txResult;
+            if (isSolanaChain(chainId)) {
+                txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', tokenAddress
+                    ? { to: option.payTo, value: rawAmount, token_mint: tokenAddress, token_decimals: trustedDecimals, chain_id: chainId }
+                    : { to: option.payTo, value: rawAmount, chain_id: chainId }));
+            }
+            else if (tokenAddress) {
+                const calldata = '0xa9059cbb' + padAddress(option.payTo) + encodeUint256(rawAmount);
+                txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', { to: tokenAddress, value: '0', data: calldata, chain_id: chainId }));
+            }
+            else {
+                txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', { to: option.payTo, value: rawAmount, data: '', chain_id: chainId }));
+            }
+            txHash = String(txResult.tx_hash || txResult.signature || '');
+            if (!txHash)
+                throw new Error('x402: the payment transaction returned no hash.');
+            paymentHeader = Buffer.from(JSON.stringify({ x402Version, scheme: option.scheme, network: option.network, payload: { txHash } })).toString('base64');
+        }
+        if (!authorizationReused) {
+            const until = authorization ? Number(authorization.validBefore) * 1000
+                : uptoAuth ? Number(uptoAuth.deadline) * 1000
+                    : Date.now() + maxAuthWindowSeconds() * 1000; // a broadcast transfer: the hash stays valid, re-sending it never pays twice
+            signedPayments.set(cacheKey, { headerName, paymentHeader, txHash, authorization, uptoAuth, payer, until });
         }
-        txHash = String(txResult.tx_hash || txResult.signature || '');
-        if (!txHash)
-            throw new Error('x402: the payment transaction returned no hash.');
-        paymentHeader = Buffer.from(JSON.stringify({ x402Version, scheme: option.scheme, network: option.network, payload: { txHash } })).toString('base64');
     }
-    if (!authorizationReused) {
-        const until = authorization ? Number(authorization.validBefore) * 1000
-            : uptoAuth ? Number(uptoAuth.deadline) * 1000
-                : Date.now() + maxAuthWindowSeconds() * 1000; // a broadcast transfer: the hash stays valid, re-sending it never pays twice
-        signedPayments.set(cacheKey, { headerName, paymentHeader, txHash, authorization, uptoAuth, payer, until });
+    finally {
+        releaseSigning();
+        signingInFlight.delete(cacheKey);
     }
     // Step 6: Retry with the payment header and read the settlement receipt.
     const retryHeaders = { ...reqHeaders, [headerName]: paymentHeader };
@@ -1508,7 +1572,19 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
     if (reqBody && method !== 'GET') {
         retryOptions.body = reqBody;
     }
-    const retryRes = await safeFetch(url, retryOptions);
+    let retryRes;
+    try {
+        retryRes = await safeFetch(url, retryOptions);
+    }
+    catch (e) {
+        // The authorization has already been handed over; say so instead of a bare transport error.
+        return jsonResponse({
+            status: 0, payment_required: true, payment_made: null, payment_outcome: 'unknown',
+            error: `The paid request could not be completed: ${e.message}. The authorization was already sent; it stays cached, and calling pay_x402 again with the same URL inside its window re-sends the same one rather than signing a new one.`,
+            authorization: authorization ? { nonce: authorization.nonce, valid_before: authorization.validBefore } : (uptoAuth ? { scheme: 'upto', nonce: uptoAuth.nonce, deadline: uptoAuth.deadline } : null),
+            tx_hash: txHash ?? null, amount, token: tokenLabel, pay_to: option.payTo, chain_id: chainId,
+        });
+    }
     const retryText = await retryRes.text();
     let retryParsed;
     try {
@@ -1523,22 +1599,24 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
     let retryError = null;
     const retryServedFrom = finalUrlOf(retryRes, url);
     const retryCrossOrigin = new URL(retryServedFrom).origin !== new URL(url).origin;
+    const verdict = settlementVerdict(retryRes.status, settlement, retryCrossOrigin);
     if (retryCrossOrigin) {
         retryError = `The paid request was redirected to another origin (${new URL(retryServedFrom).origin}); the payment header is never forwarded across origins, so this response did not see the payment.`;
     }
     if (retryRes.status === 402) {
         const again = parsePaymentRequired(n => retryRes.headers.get(n), retryParsed);
-        retryError = String(again?.error || retryParsed?.error || 'Payment was not accepted (no reason given).');
+        retryError = serverText(String(again?.error || retryParsed?.error || 'Payment was not accepted (no reason given).'));
         if (payerDelegationInfo && /signature/i.test(retryError))
             retryError += ` Likely cause: ${payerDelegationInfo.warning}`;
     }
     return jsonResponse({
         status: retryRes.status,
         payment_required: true,
-        // Paid means the endpoint accepted the payment: a settlement receipt, or a success status after the payment header.
-        // A 4xx other than 402 (bad body, auth) means the request failed for another reason; the authorization was
-        // sent but the facilitator normally does not settle a failed request, so it is not reported as paid.
-        payment_made: !retryCrossOrigin && (Boolean(settlement?.success) || (retryRes.status >= 200 && retryRes.status < 300)),
+        // Paid means a success status after the payment header and no server-reported settlement failure. A 402 or
+        // any other non-2xx is not paid whatever the settlement header claims (a server could send success:true on a
+        // 402 and mislead the agent, 2026-10-04 round 2); the facilitator does not settle a failed request.
+        payment_made: verdict.payment_made,
+        payment_outcome: verdict.outcome,
         authorization_reused: authorizationReused,
         retry_error: retryError,
         payment_method: isUpto ? 'permit2-upto-authorization' : (standardExact ? 'eip3009-authorization' : 'onchain-transfer'),
@@ -1553,13 +1631,15 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
         pay_to: option.payTo,
         payer,
         payer_delegation: payerDelegationInfo,
-        // txHash is ours (we broadcast it); settlement.transaction is the server's
-        // claim and is surfaced only when it is shaped like a real hash.
-        tx_hash: txHash ?? (looksLikeTxHash(settlement?.transaction) ? settlement?.transaction : null) ?? null,
+        // tx_hash is only ever ours (we broadcast it). The server's claimed hash
+        // is kept apart and unverified: it is not evidence the payment settled.
+        tx_hash: txHash ?? null,
+        server_claimed_tx_hash: looksLikeTxHash(settlement?.transaction) ? settlement?.transaction : null,
         settlement_reported_by_server: settlement,
         authorization: authorization ? { nonce: authorization.nonce, valid_before: authorization.validBefore }
             : (uptoAuth ? { scheme: 'upto', max_amount: amount, nonce: uptoAuth.nonce, deadline: uptoAuth.deadline, facilitator: uptoAuth.witness.facilitator } : null),
-        description: option.description,
+        description: serverText(option.description),
+        server_text_is_untrusted: true, // description, retry_error and the response are the endpoint's words, not instructions
         response: retryParsed,
     });
 });
@@ -1578,13 +1658,13 @@ server.tool('approve_permit2', 'One-time ERC-20 approval of a token to the Permi
 }, async ({ wallet_id, token, chain_id, amount }) => {
     if (isSolanaChain(chain_id))
         throw new Error('Permit2 is an EVM contract; there is nothing to approve on Solana.');
-    let data = permit2ApproveCalldata();
+    let data = permit2ApproveCalldata(undefined, chain_id);
     if (amount !== undefined) {
         const raw = parseUnits(amount, await resolveTrustedDecimals(chain_id, token));
-        data = '0x095ea7b3' + padAddress(PERMIT2_ADDRESS) + encodeUint256(raw);
+        data = permit2ApproveCalldata(raw, chain_id);
     }
     const result = (await api(`/wallets/${wallet_id}/send`, 'POST', { to: token, value: '0', data, chain_id }));
-    return jsonResponse({ ...result, token, spender: PERMIT2_ADDRESS, amount: amount ?? 'unlimited', note: 'Permit2 only transfers what a signed authorization allows; the allowance itself moves nothing.' });
+    return jsonResponse({ ...result, token, spender: permit2Address(chain_id), amount: amount ?? 'unlimited', note: 'Permit2 only transfers what a signed authorization allows; the allowance itself moves nothing.' });
 });
 // ─── Tool: check_token_risk ─────────────────────────────────────
 server.tool('check_token_risk', 'Assess an ERC-20 token before approving or swapping it: honeypot, taxes, owner powers, verified source, ' +
@@ -1764,7 +1844,13 @@ server.tool('wallet_mode', 'Report whether this server is signing locally (self-
             mode: 'custodial',
             custody: 'agentwallet',
             signing: 'AgentWallet servers hold an encrypted key and sign on your behalf.',
-            api_base: API_BASE,
+            api_base: redactUrl(API_BASE),
+            client_guards: {
+                autopay_cap_usd: autopayEnvCap(),
+                autopay_assets: (process.env.AGENTWALLET_AUTOPAY_ASSETS || '').trim() || 'registry stablecoins only',
+                x402_max_timeout_seconds: maxAuthWindowSeconds(),
+                note: 'These bound pay_x402 on hosted wallets too; the hosted signer adds its own pause, daily limit and approval checks.',
+            },
             to_self_custody: 'Set AGENTWALLET_PRIVATE_KEY for EVM and/or AGENTWALLET_SOLANA_KEY for Solana, then restart. ' +
                 'Use export_wallet_key first if you want to carry an existing hosted wallet across.',
         });
@@ -1864,7 +1950,7 @@ async function main() {
         }
     }
     else {
-        console.error('AgentWallet MCP: custodial mode via ' + API_BASE + '. Run wallet_mode for details.');
+        console.error('AgentWallet MCP: custodial mode via ' + redactUrl(API_BASE) + '. Run wallet_mode for details.');
     }
 }
 main().catch((error) => {