agentwallet-mcp 1.7.4 → 1.8.0

package/README.md

@@ -52,7 +52,9 @@ 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 will automatically pay for operations with USDC from this wallet.
+> `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 maximum amount, in human-readable units of the asset, that x402 auto-pay will authorize for a single payment. Any 402 requirement above this cap is rejected instead of paid, so a malformed or tampered payment requirement cannot drain the wallet. Raise it only if you genuinely need larger automatic payments (for example `"5"` to allow up to 5 USDC per call).
 
 ### Claude Code
 
@@ -158,7 +160,7 @@ AgentWallet natively supports the [x402 open payment standard](https://x402.org)
 4. Retries the request with proof of payment
 5. Returns the final response
 
-**Always set `max_payment` to control spending:**
+**Set `max_payment` to control spending:**
 
 ```
 pay_x402(
@@ -168,7 +170,9 @@ pay_x402(
 )
 ```
 
-Supports ERC-20 tokens, SPL tokens, and native tokens on EVM and Solana. Compatible with x402 V1 and V2 (CAIP-2 chain identifiers).
+`max_payment` is enforced as a hard per-payment cap. If you omit it, `pay_x402` falls back to `AGENTWALLET_MAX_AUTOPAY` (default `1`), the same cap the auto-pay path uses, so a malicious or compromised 402 endpoint can never authorize an unbounded payment. Set `max_payment` explicitly (or raise `AGENTWALLET_MAX_AUTOPAY`) to allow a larger single payment.
+
+Supports ERC-20 tokens, SPL tokens, and native tokens on EVM and Solana. Compatible with x402 V1 and V2 (CAIP-2 chain identifiers), and reads the token address from the standard x402 `asset` field (falling back to `extra.token`).
 
 ## x402 Acceptance
 

package/build/index.js

@@ -12,6 +12,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { deriveX402Payment, isWithinCap } from './x402-payment.js';
 // ─── Configuration ──────────────────────────────────────────────
 const API_BASE = process.env.AGENTWALLET_API_URL || 'https://hifriendbot.com/wp-json/agentwallet/v1';
 const API_USER = process.env.AGENTWALLET_USER || '';
@@ -55,15 +56,19 @@ async function handleX402Payment(x402Data, originalPath, originalMethod, origina
         throw new Error('402 Payment Required but no payment options available.');
     }
     const accept = accepts[0]; // Use first option
-    const tokenAddress = accept.extra?.token || '';
-    const amount = accept.maxAmountRequired;
     const payTo = accept.payTo;
-    const decimals = accept.requiredDecimals || 6;
     // Determine chain_id from network string (CAIP-2, plain name, or raw ID)
     const network = accept.network || '';
     const chainId = resolveChainId(network) ?? 8453;
-    // Convert human-readable amount to raw (e.g. "0.01" with 6 decimals = "10000")
-    const rawAmount = parseUnits(amount, decimals);
+    // x402 maxAmountRequired is ALREADY in base/atomic units (e.g. "10000" =
+    // 0.01 USDC at 6 decimals) and must be used directly. The previous code ran
+    // it through parseUnits(), which re-scaled it by 10**decimals and overpaid by
+    // that factor (1,000,000x for USDC). deriveX402Payment uses it directly (like
+    // the pay_x402 tool) and enforces a hard ceiling so a malformed or malicious
+    // 402 response cannot drain the wallet. AGENTWALLET_MAX_AUTOPAY is in
+    // human-readable units of the asset; default 1.
+    const maxAutopay = process.env.AGENTWALLET_MAX_AUTOPAY || '1';
+    const { tokenAddress, rawAmount, decimals } = deriveX402Payment(accept, maxAutopay);
     // Send payment using our wallet (with X-AGW-SKIP-X402 to prevent recursion)
     let txHash;
     try {
@@ -216,7 +221,7 @@ function resolveChainId(network) {
 // ─── Server ──────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'agentwallet',
-    version: '1.7.2',
+    version: '1.8.0',
 }, {
     instructions: `AgentWallet gives AI agents their own blockchain wallets. Private keys are encrypted server-side and never exposed — agents sign and broadcast transactions without ever touching raw keys.
 
@@ -739,7 +744,10 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
     headers: z.string().optional().describe('Optional JSON string of additional request headers'),
     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. Strongly recommended to prevent overspending.'),
+        '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.'),
     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)'),
 }, async ({ url, wallet_id, method, headers: headersJson, body: reqBody, max_payment, prefer_chain }) => {
@@ -821,35 +829,45 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
     }
     // Calculate human-readable amount
     const amount = formatUnits(option.maxAmountRequired, option.requiredDecimals);
-    // Step 4: Check spending limit
-    if (max_payment) {
-        const maxRaw = parseUnits(max_payment, option.requiredDecimals);
-        if (BigInt(option.maxAmountRequired) > BigInt(maxRaw)) {
-            return jsonResponse({
-                status: 402,
-                payment_required: true,
-                payment_made: false,
-                error: `Payment of ${amount} ${option.extra?.name || 'tokens'} exceeds your max_payment limit of ${max_payment}`,
-                required_amount: amount,
-                max_allowed: max_payment,
-                token: option.extra?.name || 'native',
-                network: option.network,
-                chain_id: chainId,
-                pay_to: option.payTo,
-                description: option.description,
-            });
-        }
+    // Step 4: Enforce a hard per-payment cap. ALWAYS applied — if the caller
+    // omits max_payment we fall back to AGENTWALLET_MAX_AUTOPAY (default "1"),
+    // mirroring the internal auto-pay path (deriveX402Payment). Without this, an
+    // untrusted or compromised x402 endpoint could return an arbitrarily large
+    // maxAmountRequired and drain the wallet. The cap is never silently skipped.
+    const capSource = max_payment ? 'max_payment' : 'AGENTWALLET_MAX_AUTOPAY';
+    const effectiveMax = max_payment || process.env.AGENTWALLET_MAX_AUTOPAY || '1';
+    if (!isWithinCap(option.maxAmountRequired, option.requiredDecimals, effectiveMax)) {
+        return jsonResponse({
+            status: 402,
+            payment_required: true,
+            payment_made: false,
+            error: `Payment of ${amount} ${option.extra?.name || 'tokens'} exceeds the ` +
+                `${effectiveMax} cap (from ${capSource}).` +
+                (max_payment ? '' : ' No max_payment was provided, so the default cap was applied. ' +
+                    'Pass max_payment (or raise AGENTWALLET_MAX_AUTOPAY) to allow a larger payment.'),
+            required_amount: amount,
+            max_allowed: effectiveMax,
+            cap_source: capSource,
+            token: option.extra?.name || 'native',
+            network: option.network,
+            chain_id: chainId,
+            pay_to: option.payTo,
+            description: option.description,
+        });
     }
+    // Standard x402 puts the token address in `asset`; AgentWallet's own server
+    // currently emits it under extra.token. Prefer the standard field, fall back.
+    const tokenAddress = option.asset || option.extra?.token || '';
     // Step 5: Execute payment
     let txResult;
     if (isSolanaChain(chainId)) {
         // Solana payment
-        if (option.extra?.token) {
+        if (tokenAddress) {
             // SPL token payment (e.g. USDC on Solana)
             txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', {
                 to: option.payTo,
                 value: option.maxAmountRequired,
-                token_mint: option.extra.token,
+                token_mint: tokenAddress,
                 token_decimals: option.requiredDecimals,
                 chain_id: chainId,
             }));
@@ -863,11 +881,11 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
             }));
         }
     }
-    else if (option.extra?.token) {
+    else if (tokenAddress) {
         // EVM ERC-20 token payment (e.g. USDC)
         const calldata = '0xa9059cbb' + padAddress(option.payTo) + encodeUint256(option.maxAmountRequired);
         txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', {
-            to: option.extra.token,
+            to: tokenAddress,
             value: '0',
             data: calldata,
             chain_id: chainId,
@@ -916,7 +934,7 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
         payment_made: true,
         amount,
         token: option.extra?.name || 'native',
-        token_address: option.extra?.token || null,
+        token_address: option.asset || option.extra?.token || null,
         network: option.network,
         chain_id: chainId,
         pay_to: option.payTo,

package/build/x402-payment.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pure helpers for x402 auto-pay amount/token derivation.
+ *
+ * Isolated from the server bootstrap in index.ts so the funds-sensitive amount
+ * math can be unit-tested without starting the MCP server.
+ */
+export interface X402AcceptLike {
+    maxAmountRequired: string;
+    requiredDecimals?: number;
+    asset?: string;
+    extra?: {
+        token?: string;
+    };
+}
+/**
+ * Derive the on-chain transfer parameters from an x402 payment requirement.
+ *
+ * CRITICAL: x402 `maxAmountRequired` is ALREADY denominated in base/atomic
+ * units (e.g. "10000" = 0.01 USDC at 6 decimals). It MUST be used directly.
+ * Running it through parseUnits() re-scales it by 10**decimals and overpays by
+ * that factor (1,000,000x for USDC). This mirrors the pay_x402 tool, which has
+ * always used maxAmountRequired directly.
+ *
+ * Also enforces a hard ceiling so a malformed or malicious 402 response can
+ * never authorize a transfer larger than `maxAutopayHuman` units of the asset.
+ *
+ * @param accept           the chosen x402 accept option
+ * @param maxAutopayHuman  max auto-pay, in human-readable units of the asset
+ */
+export declare function deriveX402Payment(accept: X402AcceptLike, maxAutopayHuman: string): {
+    tokenAddress: string;
+    rawAmount: string;
+    decimals: number;
+};
+/**
+ * Returns true if an x402 required amount (already in base/atomic units) is
+ * within a human-readable per-payment cap.
+ *
+ * Shared by both x402 payment paths so neither can authorize an unbounded
+ * transfer: the internal auto-pay path and the public pay_x402 MCP tool both
+ * gate on this. pay_x402 uses it (instead of deriveX402Payment's throw) so it
+ * can return a structured rejection to the calling agent.
+ *
+ * @param rawAmountRequired x402 maxAmountRequired, already in base units
+ * @param decimals          token decimals
+ * @param capHuman          cap in human-readable units of the asset (e.g. "1")
+ */
+export declare function isWithinCap(rawAmountRequired: string, decimals: number, capHuman: string): boolean;

package/build/x402-payment.js

@@ -0,0 +1,66 @@
+/**
+ * Pure helpers for x402 auto-pay amount/token derivation.
+ *
+ * Isolated from the server bootstrap in index.ts so the funds-sensitive amount
+ * math can be unit-tested without starting the MCP server.
+ */
+/** Convert a human-readable decimal amount (e.g. "0.01") to base/atomic units. */
+function toBaseUnits(amount, decimals) {
+    if (!/^\d+(\.\d+)?$/.test(amount)) {
+        throw new Error(`Invalid amount "${amount}".`);
+    }
+    const [whole, frac = ''] = amount.split('.');
+    const fracPadded = frac.slice(0, decimals).padEnd(decimals, '0');
+    return BigInt(whole + fracPadded).toString();
+}
+/**
+ * Derive the on-chain transfer parameters from an x402 payment requirement.
+ *
+ * CRITICAL: x402 `maxAmountRequired` is ALREADY denominated in base/atomic
+ * units (e.g. "10000" = 0.01 USDC at 6 decimals). It MUST be used directly.
+ * Running it through parseUnits() re-scales it by 10**decimals and overpays by
+ * that factor (1,000,000x for USDC). This mirrors the pay_x402 tool, which has
+ * always used maxAmountRequired directly.
+ *
+ * Also enforces a hard ceiling so a malformed or malicious 402 response can
+ * never authorize a transfer larger than `maxAutopayHuman` units of the asset.
+ *
+ * @param accept           the chosen x402 accept option
+ * @param maxAutopayHuman  max auto-pay, in human-readable units of the asset
+ */
+export function deriveX402Payment(accept, maxAutopayHuman) {
+    const decimals = accept.requiredDecimals || 6;
+    // Standard x402 uses `asset` for the token address; AgentWallet's own server
+    // currently emits it under extra.token. Prefer the standard field, fall back.
+    const tokenAddress = accept.asset || accept.extra?.token || '';
+    const rawAmount = accept.maxAmountRequired;
+    if (!/^\d+$/.test(rawAmount)) {
+        throw new Error(`x402 auto-pay: invalid maxAmountRequired "${rawAmount}" (expected an integer base-unit amount).`);
+    }
+    const capRaw = toBaseUnits(maxAutopayHuman, decimals);
+    if (BigInt(rawAmount) > BigInt(capRaw)) {
+        throw new Error(`x402 auto-pay blocked: required amount (${rawAmount} base units) exceeds the ` +
+            `AGENTWALLET_MAX_AUTOPAY cap of ${maxAutopayHuman}. Raise AGENTWALLET_MAX_AUTOPAY to allow it.`);
+    }
+    return { tokenAddress, rawAmount, decimals };
+}
+/**
+ * Returns true if an x402 required amount (already in base/atomic units) is
+ * within a human-readable per-payment cap.
+ *
+ * Shared by both x402 payment paths so neither can authorize an unbounded
+ * transfer: the internal auto-pay path and the public pay_x402 MCP tool both
+ * gate on this. pay_x402 uses it (instead of deriveX402Payment's throw) so it
+ * can return a structured rejection to the calling agent.
+ *
+ * @param rawAmountRequired x402 maxAmountRequired, already in base units
+ * @param decimals          token decimals
+ * @param capHuman          cap in human-readable units of the asset (e.g. "1")
+ */
+export function isWithinCap(rawAmountRequired, decimals, capHuman) {
+    if (!/^\d+$/.test(rawAmountRequired)) {
+        throw new Error(`Invalid maxAmountRequired "${rawAmountRequired}" (expected an integer base-unit amount).`);
+    }
+    const capRaw = toBaseUnits(capHuman, decimals);
+    return BigInt(rawAmountRequired) <= BigInt(capRaw);
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "agentwallet-mcp",
   "mcpName": "io.github.hifriendbot/agentwallet",
-  "version": "1.7.4",
-  "description": "MCP server for AgentWallet — lets AI agents create wallets, sign transactions, broadcast on EVM + Solana, pay x402 invoices, and accept x402 payments",
+  "version": "1.8.0",
+  "description": "MCP server for AgentWallet: lets AI agents create wallets, sign transactions, broadcast on EVM + Solana, pay x402 invoices, and accept x402 payments",
   "type": "module",
   "main": "build/index.js",
   "bin": {
@@ -16,6 +16,7 @@
   "scripts": {
     "build": "tsc",
     "start": "node build/index.js",
+    "test": "node test/x402-payment.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -46,7 +47,7 @@
   ],
   "author": "HiFriendbot (https://hifriendbot.com)",
   "license": "MIT",
-  "homepage": "https://hifriendbot.com/agentwallet",
+  "homepage": "https://hifriendbot.com/wallet/",
   "engines": {
     "node": ">=18.0.0"
   },