agentwallet-mcp 1.13.0 → 1.13.2

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
 
@@ -245,7 +245,7 @@ pay_x402(
 
 **Schemes.** `exact` (EIP-3009, gasless for the payer) is preferred and works on every EVM chain AgentWallet knows. `upto` (a Permit2 maximum the seller settles at actual usage) is signed as a `PermitWitnessTransferFrom` bound to the endpoint's facilitator; it needs a one-time `approve_permit2` per token (or `AGENTWALLET_PERMIT2_AUTO_APPROVE=1`). An `upto` option without `extra.facilitatorAddress` is refused, never approximated with an upfront transfer. Native-asset and Solana requests, and AgentWallet's own paywalls, are paid by an on-chain transfer proved by transaction hash, which is what those servers verify.
 
-**Approvals above the cap.** On a hosted wallet, a payment above the cap does not have to fail. With `request_approval` (default on; `AGENTWALLET_APPROVALS=0` turns it off) the wallet owner gets an email with approve and deny links, `pay_x402` returns an `approval_id`, and the agent retries with it once `check_approval` says approved. An approval is bound to one wallet, chain, asset, recipient and maximum, expires in 24 hours, and is consumed by one signature. Local mode has no approval channel: the caps in your environment are the policy.
+**Approvals above the cap.** On a hosted wallet, a payment above the cap does not have to fail. With `request_approval` (default on; `AGENTWALLET_APPROVALS=0` turns it off) the wallet owner gets an email with approve and deny links, `pay_x402` returns an `approval_id`, and the agent retries with it once `check_approval` says approved. An approval is bound to one wallet, chain, asset, recipient and maximum, expires in 24 hours, and is consumed by one signature. Local mode has no approval channel: the caps in your environment are the policy, and an `approval_id` passed there is refused.
 
 **Asset risk.** `check_token_risk` (and every `approve_token` result) reports honeypot, tax, owner-power, verified-source, holder-concentration and liquidity flags from GoPlus Security, with an on-chain fallback. A warning for the caller to weigh, never a block.
 
@@ -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, approvalRefusal, } 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.2',
 }, {
     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.'
@@ -1359,13 +1370,14 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
         };
         const wantApproval = request_approval ?? (process.env.AGENTWALLET_APPROVALS !== '0');
         if (approval_id) {
-            const a = (await api(`/approvals/${encodeURIComponent(approval_id)}`, 'GET', undefined, skip));
-            if (a?.status !== 'approved' || Number(a.used) === 1) {
-                return jsonResponse({ ...overCap, approval_id, approval_status: a?.status ?? null, error: `Approval ${approval_id} is ${a?.status ?? 'unknown'}, not approved.${a?.error ? ' ' + a.error : ''}` });
-            }
-            const sameAsset = String(a.asset ?? '').toLowerCase() === tokenAddress.toLowerCase();
-            if (!sameAsset || String(a.pay_to || '').toLowerCase() !== option.payTo.toLowerCase() || Number(a.chain_id) !== chainId || BigInt(String(a.value || '0')) < BigInt(rawAmount)) {
-                return jsonResponse({ ...overCap, approval_id, error: 'Approval does not cover this payment (asset, recipient, chain or amount differ).' });
+            // Local mode refuses before any lookup: only the hosted signer can consume
+            // an approval, so here the same id would lift the cap on every call.
+            const want = { walletId: wallet_id, chainId, asset: tokenAddress, payTo: option.payTo, rawAmount };
+            const local = anyLocalMode();
+            const a = local ? null : (await api(`/approvals/${encodeURIComponent(approval_id)}`, 'GET', undefined, skip));
+            const refusal = approvalRefusal(approval_id, a, want, local);
+            if (refusal) {
+                return jsonResponse({ ...overCap, approval_id, ...refusal });
             }
             approvalUsed = String(approval_id);
         }
@@ -1763,6 +1775,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-solana.js

@@ -355,10 +355,19 @@ export async function localSplTransfer(mintStr, to, rawAmount, decimals, chainId
     };
 }
 const TOKEN_ACCOUNT_SIZE = 165;
+const MINT_SIZE = 82;
+/** Token-2022 pads a mint to the token-account size and tags the next byte: 1 = mint, 2 = token account. */
+const TOKEN_2022_TYPE_MINT = 1;
 /**
  * A recipient must be something that can own a token account: a wallet or a
- * program-derived wallet (Squads and friends), never a program and never a
- * token account. SPL sent to ATA(ATA) or to a program id is gone for good.
+ * program-derived wallet (Squads and friends), never a program and never an
+ * account the token programs own. SPL sent to ATA(ATA), ATA(mint) or a program
+ * id is gone for good, or belongs to whoever kept the mint's keypair.
+ *
+ * Ownership alone decides. A length gate (>= 165 bytes) used to sit here and
+ * let an 82-byte mint through as a "wallet" (2026-10-02 report): everything
+ * the token programs own is a mint, a token account or a multisig, and none
+ * of those is a wallet.
  */
 async function assertRecipientIsWallet(conn, recipient) {
     const info = await conn.getAccountInfo(recipient);
@@ -366,8 +375,16 @@ async function assertRecipientIsWallet(conn, recipient) {
         return; // never seen on chain: an ordinary fresh wallet
     if (info.executable)
         throw new Error(`Refusing to send to ${recipient.toBase58()}: it is a program, not a wallet.`);
-    if ((info.owner.equals(TOKEN_PROGRAM) || info.owner.equals(TOKEN_2022_PROGRAM)) && info.data.length >= TOKEN_ACCOUNT_SIZE) {
-        throw new Error(`Refusing to send to ${recipient.toBase58()}: it is a token account, not a wallet. Pass the owner's wallet address instead.`);
+    if (info.owner.equals(TOKEN_PROGRAM) || info.owner.equals(TOKEN_2022_PROGRAM)) {
+        const isMint = info.data.length === MINT_SIZE
+            || (info.data.length > TOKEN_ACCOUNT_SIZE && info.data[TOKEN_ACCOUNT_SIZE] === TOKEN_2022_TYPE_MINT);
+        if (isMint) {
+            throw new Error(`Refusing to send to ${recipient.toBase58()}: it is a token mint, not a wallet. Pass the recipient's wallet address; the mint belongs in token_mint.`);
+        }
+        if (info.data.length >= TOKEN_ACCOUNT_SIZE) {
+            throw new Error(`Refusing to send to ${recipient.toBase58()}: it is a token account, not a wallet. Pass the owner's wallet address instead.`);
+        }
+        throw new Error(`Refusing to send to ${recipient.toBase58()}: it is an account owned by the SPL token program, not a wallet.`);
     }
 }
 export function solanaWalletRecord() {

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.
@@ -152,3 +163,35 @@ export declare const SOLANA_CHAIN_IDS: ReadonlySet<number>;
  */
 export declare function nativeDecimals(chainId: number): number;
 export declare function isWithinCap(rawAmountRequired: string, trustedDecimals: number, capHuman: string): boolean;
+/** The row GET /approvals/{id} answers with. Numbers arrive as strings from the server. */
+export interface ApprovalRow {
+    status?: string;
+    used?: number | string;
+    wallet_id?: number | string;
+    chain_id?: number | string;
+    asset?: string;
+    pay_to?: string;
+    value?: string;
+    error?: string;
+}
+export interface ApprovalWant {
+    walletId: number;
+    chainId: number;
+    asset: string;
+    payTo: string;
+    rawAmount: string;
+}
+/**
+ * Why an approval cannot stand in for the cap on this payment, or null when it can.
+ *
+ * An approval is single-use because the hosted signer marks it used in the same
+ * request that signs. A local signer never talks to that server, so in local
+ * mode nothing could ever consume one and the same id would lift the cap again
+ * on every call (2026-10-02 report). Local mode therefore refuses approvals
+ * outright, before any lookup. For a hosted wallet every bound field is checked
+ * here, the wallet included, and the server checks them again when it signs.
+ */
+export declare function approvalRefusal(approvalId: string, row: ApprovalRow | null | undefined, want: ApprovalWant, localMode: boolean): {
+    error: string;
+    approval_status?: string | null;
+} | null;

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;
@@ -277,3 +324,37 @@ export function isWithinCap(rawAmountRequired, trustedDecimals, capHuman) {
     const capRaw = toBaseUnits(capHuman, trustedDecimals);
     return BigInt(rawAmountRequired) <= BigInt(capRaw);
 }
+/**
+ * Why an approval cannot stand in for the cap on this payment, or null when it can.
+ *
+ * An approval is single-use because the hosted signer marks it used in the same
+ * request that signs. A local signer never talks to that server, so in local
+ * mode nothing could ever consume one and the same id would lift the cap again
+ * on every call (2026-10-02 report). Local mode therefore refuses approvals
+ * outright, before any lookup. For a hosted wallet every bound field is checked
+ * here, the wallet included, and the server checks them again when it signs.
+ */
+export function approvalRefusal(approvalId, row, want, localMode) {
+    if (localMode) {
+        return {
+            error: `Approval ${approvalId} cannot be used in local mode: approvals are consumed by the hosted signer, and this server signs with your own key, so nothing could mark it used. Local mode has no approval channel: raise AGENTWALLET_MAX_AUTOPAY or AGENTWALLET_MAX_TX_TOKEN yourself.`,
+        };
+    }
+    const status = row?.status ?? null;
+    // "used" must read as exactly 0. A missing or unparseable field refuses rather than passes.
+    if (status !== 'approved' || Number(row?.used) !== 0) {
+        const state = status === 'approved' ? 'already used' : `${status ?? 'unknown'}, not approved`;
+        return { approval_status: status, error: `Approval ${approvalId} is ${state}.${row?.error ? ' ' + row.error : ''}` };
+    }
+    const value = String(row?.value ?? '');
+    const covers = Number(row?.wallet_id) === want.walletId
+        && Number(row?.chain_id) === want.chainId
+        && String(row?.asset ?? '').toLowerCase() === want.asset.toLowerCase()
+        && String(row?.pay_to ?? '').toLowerCase() === want.payTo.toLowerCase()
+        && /^\d+$/.test(value) && /^\d+$/.test(want.rawAmount)
+        && BigInt(value) >= BigInt(want.rawAmount);
+    if (!covers) {
+        return { error: 'Approval does not cover this payment (wallet, asset, recipient, chain or amount differ).' };
+    }
+    return null;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentwallet-mcp",
   "mcpName": "io.github.hifriendbot/agentwallet",
-  "version": "1.13.0",
+  "version": "1.13.2",
   "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 && node test/spl-recipient-guard.test.mjs && node test/approval-binding.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [