agentwallet-mcp 1.13.0 → 1.13.1

package/README.md

@@ -43,7 +43,7 @@ Use `AGENTWALLET_KEYFILE=/path/to/key` instead if you would rather keep the key
 
 `AGENTWALLET_MAX_TX_NATIVE` is a per-transaction ceiling in native units (ETH, MATIC and so on). In hosted mode the server enforces limits; in local mode there is no server, so these guards are the only ones there are. Set them.
 
-`AGENTWALLET_MAX_TX_TOKEN` is the equivalent ceiling for ERC-20 movement, in human units of the token. **Set this one too if you hold stablecoins.** The native cap cannot see a token transfer: an ERC-20 send carries `value = 0` with the amount in the calldata, so `AGENTWALLET_MAX_TX_NATIVE` alone leaves a USDC balance uncapped. `AGENTWALLET_MAX_TX_TOKEN` covers `transfer`, `transferFrom`, `approve`, `increaseAllowance`, Permit2 `approve`, and `deposit()` / `withdraw(uint256)` on the chain's own wrapped-native contract (so `wrap_eth` and `unwrap_eth` keep working under the cap), the approvals because an unbounded allowance is a drain waiting to happen. Any other calldata sent to a token contract or to Permit2 is refused while the cap is set, because the guard cannot price it; set `AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS=1` to allow such calls deliberately. Calls to other contracts (routers, bridges) pass, since they can only pull what an approval already allowed; a contract counts as "other" only when it demonstrably declines `decimals()`, so an absurd or malformed answer, or an RPC that cannot be reached, refuses rather than allows. Decimals are resolved locally from the trusted registry, then the token's own `decimals()`; a token that resolves neither way is evaluated at 0 decimals, the only value that cannot fail open.
+`AGENTWALLET_MAX_TX_TOKEN` is the equivalent ceiling for ERC-20 movement, in human units of the token. **Set this one too if you hold stablecoins.** The native cap cannot see a token transfer: an ERC-20 send carries `value = 0` with the amount in the calldata, so `AGENTWALLET_MAX_TX_NATIVE` alone leaves a USDC balance uncapped. `AGENTWALLET_MAX_TX_TOKEN` covers `transfer`, `transferFrom`, `approve`, `increaseAllowance`, Permit2 `approve`, and `deposit()` / `withdraw(uint256)` on the chain's own wrapped-native contract (so `wrap_eth` and `unwrap_eth` keep working under the cap), the approvals because an unbounded allowance is a drain waiting to happen. Any other calldata sent to a token contract or to Permit2 is refused while the cap is set, because the guard cannot price it; set `AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS=1` to allow such calls deliberately. `increaseAllowance` is judged on the resulting total: the current allowance is read first and the call refuses if it cannot be, so two compliant increments cannot stack a standing allowance above the cap. Calls to other contracts (routers, bridges) pass, since they can only pull what an approval already allowed; a contract counts as "other" only when it demonstrably declines `decimals()`, so an absurd or malformed answer, or an RPC that cannot be reached, refuses rather than allows. Decimals are resolved locally from the trusted registry, then the token's own `decimals()`; a token that resolves neither way is evaluated at 0 decimals, the only value that cannot fail open. For a token outside the registry the RPC is the only source of decimals, and an RPC you do not control could scale the amount and the cap together; pin such tokens with `AGENTWALLET_TOKEN_DECIMALS` (for example `8453:0x<token>=6`) and the pin is used everywhere the RPC's answer would have been.
 
 ### Solana local signing
 
@@ -120,7 +120,7 @@ Add to your config:
 
 > `AGENTWALLET_WALLET_ID` is optional. Set it to enable x402 auto-pay: when you exceed the free tier without a credit card, the MCP server automatically pays for operations with USDC from this wallet.
 >
-> **Auto-pay safety cap.** `AGENTWALLET_MAX_AUTOPAY` (optional, default `1`) is the most one x402 payment may authorize, in stablecoin units: `1` means one dollar. It prices registry stablecoins only (USDC, USDT, USDbC, DAI on the supported chains, USDC and USDT on Solana). A requirement in the chain's native asset or in any other token is refused, because "1" measured in ETH is a few thousand dollars; list such assets in `AGENTWALLET_AUTOPAY_ASSETS` (comma-separated addresses or mints, or the word `native`) to allow them, and the cap then applies in that asset's own units. Any requirement above the cap is rejected instead of paid, so a malformed or tampered payment requirement cannot drain the wallet. The cap is the operator's ceiling: a `max_payment` argument can lower it for one call but never raise it. Raise the variable itself if you genuinely need larger automatic payments (for example `"5"` for up to 5 USDC per call).
+> **Auto-pay safety cap.** `AGENTWALLET_MAX_AUTOPAY` (optional, default `1`) is the most one x402 payment may authorize, in stablecoin units: `1` means one dollar. It prices registry stablecoins only (USDC, USDT, USDbC, DAI on the supported chains, USDC and USDT on Solana). A requirement in the chain's native asset or in any other token is refused, because "1" measured in ETH is a few thousand dollars; list such assets in `AGENTWALLET_AUTOPAY_ASSETS` (comma-separated addresses or mints, or the word `native`) to allow them, and the cap then applies in that asset's own units. Any requirement above the cap is rejected instead of paid, so a malformed or tampered payment requirement cannot drain the wallet. This automatic path settles `exact` requirements only; an `upto` offer from the API is refused before any wallet call, because paying a usage maximum upfront is not what the offer means (use `pay_x402`, which signs a Permit2 authorization for it). The cap is the operator's ceiling: a `max_payment` argument can lower it for one call but never raise it. Raise the variable itself if you genuinely need larger automatic payments (for example `"5"` for up to 5 USDC per call).
 
 ### Claude Code
 
@@ -332,6 +332,7 @@ Which guards apply depends on who holds the key.
 - `AGENTWALLET_MAX_TX_NATIVE`: ceiling per transaction in native units (ETH, MATIC, and so on)
 - `AGENTWALLET_MAX_TX_TOKEN`: ceiling per ERC-20 transfer or approval, in human units of the token
 - `AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS`: set to `1` to let calldata the token cap cannot price reach a token contract or Permit2 (refused by default while the cap is set)
+- `AGENTWALLET_TOKEN_DECIMALS`: pin decimals for tokens outside the registry (`8453:0x<token>=6,<mint>=9`); a pin is used for amounts and caps instead of asking the RPC
 - `AGENTWALLET_MAX_TX_SOL`: ceiling per native SOL transfer (also charged for the rent of a recipient token account an SPL send has to create). It does not cover SPL token amounts: `AGENTWALLET_MAX_TX_TOKEN` does, on Solana as on EVM
 - `AGENTWALLET_MAX_AUTOPAY`: ceiling per x402 auto-payment in stablecoin units (default `1`); `AGENTWALLET_AUTOPAY_ASSETS` opts native or non-stable assets in; `AGENTWALLET_X402_MAX_TIMEOUT` bounds how long a signed authorization stays valid (default 3600 seconds)
 - `AGENTWALLET_SOLANA_RPC_<chainId>` (or `AGENTWALLET_SOLANA_RPC` for all clusters): the RPC's genesis hash is checked against the chain id before anything is sent, and an EVM RPC's `eth_chainId` likewise, so one URL cannot silently serve a different network than the one requested

package/build/index.js

@@ -13,7 +13,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { assertPublicUrl, safeFetch, FINAL_URL_HEADER } from './ssrf-guard.js';
-import { deriveX402Payment, isWithinCap, lookupTrustedDecimals, assertDeclaredDecimals, nativeDecimals, SOLANA_CHAIN_IDS, assetLabel, autopayAssetAllowed, autopayEnvCap, effectiveAutopayCap, maxAuthWindowSeconds, } from './x402-payment.js';
+import { deriveX402Payment, isWithinCap, lookupTrustedDecimals, assertDeclaredDecimals, nativeDecimals, SOLANA_CHAIN_IDS, assetLabel, autopayAssetAllowed, autopayEnvCap, effectiveAutopayCap, maxAuthWindowSeconds, parseDecimalPins, } from './x402-payment.js';
 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';
@@ -292,7 +292,17 @@ async function handleX402Payment(x402Data, originalPath, originalMethod, origina
     if (!accepts || accepts.length === 0) {
         throw new Error('402 Payment Required but no payment options available.');
     }
-    const accept = accepts[0]; // Use first option
+    // Only an "exact" requirement can be settled by a transfer. An upto offer
+    // names the MAXIMUM of a usage authorization; paying that maximum upfront
+    // hands the endpoint the whole ceiling instead of what was used (2026-09-28
+    // report). Such offers are refused here, before any wallet call; pay_x402
+    // settles them with a Permit2 authorization. A missing scheme is our own
+    // legacy paywall shape and means exact.
+    const accept = accepts.find((a) => !a.scheme || a.scheme === 'exact');
+    if (!accept) {
+        throw new Error(`x402 auto-pay: no "exact" payment option was offered (schemes: ${accepts.map((a) => a.scheme || '?').join(', ')}); ` +
+            `an upto maximum is not paid upfront. Use pay_x402 for this endpoint.`);
+    }
     const payTo = String(accept.payTo || '');
     // Determine chain_id from network string (CAIP-2, plain name, or raw ID)
     const network = accept.network || '';
@@ -432,6 +442,7 @@ async function verifiedDecimals(chainId, token, given) {
 }
 /** Cap variables are read at send time; a typo must fail at startup, not after funding. */
 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();
         if (v && !/^\d+(\.\d+)?$/.test(v))
@@ -550,7 +561,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.0',
+    version: '1.13.1',
 }, {
     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.'
@@ -1763,6 +1774,7 @@ server.tool('wallet_mode', 'Report whether this server is signing locally (self-
         x402_max_timeout_seconds: maxAuthWindowSeconds(),
         per_tx_cap_token: process.env.AGENTWALLET_MAX_TX_TOKEN || 'not set (ERC-20 and SPL transfers are uncapped)',
         allow_unknown_token_calls: process.env.AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS === '1',
+        token_decimals_pins: parseDecimalPins(process.env.AGENTWALLET_TOKEN_DECIMALS).size,
     };
     if (isLocalMode()) {
         let rpc = 'default public endpoint';

package/build/local-wallet.js

@@ -368,6 +368,32 @@ async function assertWithinTokenCap(chainId, to, data, valueWei = 0n) {
             `AGENTWALLET_MAX_TX_TOKEN (${cap}, evaluated at ${decimals} decimals). ` +
             `Raise the cap deliberately if this is intended.`);
     }
+    // increaseAllowance ADDS to what a spender may already pull. Checking the
+    // increment alone let two individually compliant calls leave a standing
+    // allowance above the cap (2026-09-28 report), so the resulting total is
+    // what gets checked, and an allowance that cannot be read refuses rather
+    // than assumes zero. approve() is absolute and needs no read.
+    if (selector === '39509351') {
+        const spenderWord = wordAt(0);
+        if (spenderWord.length !== 64)
+            throw new Error(`Blocked by local guard: calldata for ${layout.what} is truncated (spender word has ${spenderWord.length / 2} bytes, expected 32).`);
+        const spender = ('0x' + spenderWord.slice(24));
+        let current;
+        try {
+            const { pub } = clients(chainId);
+            current = await pub.readContract({ address: token, abi: ERC20_ABI, functionName: 'allowance', args: [getLocalAddress(), spender] });
+        }
+        catch (err) {
+            throw new Error(`Blocked by local guard: could not read the current allowance of ${spender} on ${token} ` +
+                `(${String(err.message).split('\n')[0]}), so the resulting total cannot be checked against AGENTWALLET_MAX_TX_TOKEN.`);
+        }
+        const total = current + amount;
+        if (total > capRaw) {
+            throw new Error(`Blocked by local guard: ${layout.what} of ${amount} base units would leave a standing allowance of ${total} base units ` +
+                `for ${spender}, above AGENTWALLET_MAX_TX_TOKEN (${cap}, evaluated at ${decimals} decimals). ` +
+                `Use approve with an absolute amount, or raise the cap deliberately.`);
+        }
+    }
 }
 export async function localSend(chainId, to, valueWei, data) {
     assertWithinNativeCap(valueWei);

package/build/x402-payment.d.ts

@@ -98,6 +98,17 @@ export declare const TRUSTED_SPL_DECIMALS: Record<string, number>;
  * Look up decimals we already know to be correct. Returns null when the asset
  * is unknown, which means the caller must resolve it on-chain or refuse.
  */
+/**
+ * Operator-pinned decimals: AGENTWALLET_TOKEN_DECIMALS="8453:0x<token>=6,<mint>=9".
+ *
+ * Consulted before the registry and before any RPC answer. The registry pins
+ * the major stablecoins; for any other token the only remaining source of
+ * decimals is the operator's RPC, and a compromised RPC scales the amount and
+ * the cap by the same false factor, so the cap never notices (2026-09-28
+ * report). A pin makes the token's decimals a fact the RPC cannot change.
+ */
+export declare function parseDecimalPins(raw: string | undefined): Map<string, number>;
+export declare function pinnedDecimals(chainId: number, token: string): number | null;
 export declare function lookupTrustedDecimals(chainId: number, token: string): number | null;
 /**
  * Guard the server's declared decimals against the trusted value.

package/build/x402-payment.js

@@ -171,9 +171,56 @@ export const TRUSTED_SPL_DECIMALS = {
  * Look up decimals we already know to be correct. Returns null when the asset
  * is unknown, which means the caller must resolve it on-chain or refuse.
  */
+/**
+ * Operator-pinned decimals: AGENTWALLET_TOKEN_DECIMALS="8453:0x<token>=6,<mint>=9".
+ *
+ * Consulted before the registry and before any RPC answer. The registry pins
+ * the major stablecoins; for any other token the only remaining source of
+ * decimals is the operator's RPC, and a compromised RPC scales the amount and
+ * the cap by the same false factor, so the cap never notices (2026-09-28
+ * report). A pin makes the token's decimals a fact the RPC cannot change.
+ */
+export function parseDecimalPins(raw) {
+    const pins = new Map();
+    for (const entry of (raw || '').split(',').map((s) => s.trim()).filter(Boolean)) {
+        const m = /^(?:(\d+):)?([0-9a-zA-Z]+)=(\d{1,2})$/.exec(entry);
+        if (!m)
+            throw new Error(`AGENTWALLET_TOKEN_DECIMALS entry "${entry}" is not chainId:0xtoken=decimals or mint=decimals.`);
+        const [, chain, token, dec] = m;
+        const d = Number(dec);
+        if (d > 36)
+            throw new Error(`AGENTWALLET_TOKEN_DECIMALS entry "${entry}": decimals must be 0..36.`);
+        if (/^0x[0-9a-fA-F]{40}$/.test(token)) {
+            if (!chain)
+                throw new Error(`AGENTWALLET_TOKEN_DECIMALS entry "${entry}": an EVM token needs a chain id prefix (8453:0x...=6).`);
+            pins.set(`${Number(chain)}:${token.toLowerCase()}`, d);
+        }
+        else if (/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(token)) {
+            pins.set(`spl:${token}`, d);
+        }
+        else {
+            throw new Error(`AGENTWALLET_TOKEN_DECIMALS entry "${entry}": "${token}" is not an EVM address or an SPL mint.`);
+        }
+    }
+    return pins;
+}
+let pinCache = null;
+export function pinnedDecimals(chainId, token) {
+    const raw = process.env.AGENTWALLET_TOKEN_DECIMALS || '';
+    if (!pinCache || pinCache.raw !== raw)
+        pinCache = { raw, pins: parseDecimalPins(raw) };
+    const evm = pinCache.pins.get(`${chainId}:${token.toLowerCase()}`);
+    if (typeof evm === 'number')
+        return evm;
+    const spl = pinCache.pins.get(`spl:${token}`);
+    return typeof spl === 'number' ? spl : null;
+}
 export function lookupTrustedDecimals(chainId, token) {
     if (!token)
         return null;
+    const pinned = pinnedDecimals(chainId, token);
+    if (pinned !== null)
+        return pinned;
     const spl = TRUSTED_SPL_DECIMALS[token];
     if (typeof spl === 'number')
         return spl;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentwallet-mcp",
   "mcpName": "io.github.hifriendbot/agentwallet",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "description": "MCP server for AgentWallet: self-custody local signing on EVM and Solana, or hosted wallets. Sign, broadcast, pay x402 invoices, and accept x402 payments.",
   "type": "module",
   "main": "build/index.js",
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "tsc",
     "start": "node build/index.js",
-    "test": "node test/x402-payment.test.mjs && node test/eip3009.test.mjs && node test/permit2-risk.test.mjs && node test/token-cap.test.mjs && node test/spl-cap.test.mjs && node test/unknown-decimals-cap.test.mjs && node test/decimals-range-cap.test.mjs && node test/local-mode.test.mjs && node test/ssrf-guard.test.mjs && node test/x402-policy.test.mjs && node test/local-guard-shape.test.mjs && node test/x402-policy.test.mjs && node test/local-guard-shape.test.mjs",
+    "test": "node test/x402-payment.test.mjs && node test/eip3009.test.mjs && node test/permit2-risk.test.mjs && node test/token-cap.test.mjs && node test/spl-cap.test.mjs && node test/unknown-decimals-cap.test.mjs && node test/decimals-range-cap.test.mjs && node test/local-mode.test.mjs && node test/ssrf-guard.test.mjs && node test/x402-policy.test.mjs && node test/local-guard-shape.test.mjs && node test/allowance-total-cap.test.mjs && node test/autopay-scheme.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [