agentwallet-mcp 1.7.5 → 1.9.0

package/README.md

@@ -1,29 +1,70 @@
 # AgentWallet MCP Server
 
-Permissionless wallet infrastructure for AI agents. Create wallets, sign transactions, and broadcast on-chain — on any EVM chain and Solana. Up to 50% less expensive than Coinbase. Built-in guards. No KYC. The only AI agent wallet that accepts crypto for its own API fees.
+Permissionless wallet infrastructure for AI agents. Create wallets, sign transactions, and broadcast on-chain, on any EVM chain and Solana. Built-in guards. No KYC. The only AI agent wallet that accepts crypto for its own API fees.
+
+**Your keys can stay on your machine.** Set one environment variable and every signature happens in your own process. No server sees the key, no company can freeze the wallet, and you can verify that claim by reading `src/local-wallet.ts` or by running the server with the API pointed at a closed port.
 
 **No KYC. No KYT. No approval process. No transaction monitoring. No one can block your wallet. Pay with USDC on-chain — no credit card required.**
 
+## Two modes
+
+| | Local (self-custody) | Hosted (custodial) |
+|---|---|---|
+| Who holds the key | You, in your own process | Encrypted on AgentWallet servers |
+| Set up | One env var, no account needed | API key |
+| Chains | EVM | EVM + Solana |
+| Can anyone freeze it | No | Yes, that is what pause is for |
+| Spend guards | `AGENTWALLET_MAX_TX_NATIVE`, `AGENTWALLET_MAX_AUTOPAY` | Server-side limits, pause, rate limits |
+| Paywalls, usage, billing | Needs an API key too | Included |
+
+Run `wallet_mode` at any time and the server will tell you which one you are in, and which address it controls.
+
+### Local signing in one variable
+
+```json
+{
+  "mcpServers": {
+    "agentwallet": {
+      "command": "npx",
+      "args": ["-y", "agentwallet-mcp"],
+      "env": {
+        "AGENTWALLET_PRIVATE_KEY": "0xyour_key",
+        "AGENTWALLET_RPC_8453": "https://your-own-rpc",
+        "AGENTWALLET_MAX_TX_NATIVE": "0.05"
+      }
+    }
+  }
+}
+```
+
+Use `AGENTWALLET_KEYFILE=/path/to/key` instead if you would rather keep the key out of your shell config. The key is read once, never written to disk, never logged, and never included in an error message.
+
+`AGENTWALLET_RPC_<chainId>` (or `AGENTWALLET_RPC_URL` for all chains) points at an endpoint you trust. Without it a public RPC is used, and a public RPC can see which addresses you ask about.
+
+`AGENTWALLET_MAX_TX_NATIVE` is a per-transaction ceiling in native units. In hosted mode the server enforces limits; in local mode there is no server, so this guard is the only one there is. Set it.
+
+**Local mode is EVM only right now.** Solana calls are refused with a clear error rather than quietly falling back to the custodial API, because silently moving your funds onto someone else's signer is exactly the behavior this mode exists to prevent.
+
 <p align="center">
   <img src="assets/demo.svg" alt="AgentWallet demo — AI agent pays x402 invoice automatically" width="800">
 </p>
 
 ## Features
 
-- **29 MCP tools** — create wallets, send transactions, approve tokens, wrap ETH, transfer SPL tokens, pay and accept x402 payments, and more
+- **31 MCP tools** — create wallets, send transactions, approve tokens, wrap ETH, transfer SPL tokens, pay and accept x402 payments, verify custody mode, and more
 - **EVM + Solana** — Ethereum, Base, Polygon, BSC, Arbitrum, Optimism, Avalanche, Zora, PulseChain, Solana, and any other EVM-compatible chain
 - **SOL + SPL tokens** — native SOL transfers and SPL token transfers (USDC, USDT, etc.) with automatic account creation
 - **Built-in guards** — daily spending limits, gas price protection, emergency pause, rate limiting, replay protection, and on-chain verification — all active by default
 - **x402 payments** — pay for x402-enabled APIs automatically, or accept x402 payments on your own endpoints (EVM and Solana)
-- **Secure** — Private keys encrypted at rest, decrypted only during signing, zeroed from memory immediately after
+- **Self-custody option** — run local mode and the key never leaves your machine. In hosted mode, keys are encrypted at rest, decrypted only during signing, and zeroed from memory immediately after. Either way you can export and walk away.
 - **Permissionless** — No KYC. No KYT. No identity verification. No approval process. No compliance gatekeeping. Sign up, get an API key, and start transacting immediately.
 - **30-second setup** — three lines of config. No SDK to install. No dependencies to manage.
 
 ## Pricing
 
-- **$0.00345 per operation** (31% less expensive than Coinbase CDP)
+- **$0.00345 per operation** (31% under Coinbase CDP list pricing, checked 2026-07-29)
 - **6,000 free operations/month**
-- **$0.0005 per x402 verification** (50% less expensive than Coinbase)
+- **$0.0005 per x402 verification** (50% under Coinbase, checked 2026-07-29)
 - **1,000 free x402 verifications/month**
 - **Pay with USDC on-chain** via x402 — no credit card required
 - No monthly fee, no tiers — just pay as you go
@@ -115,6 +156,8 @@ Add to your settings:
 | `delete_paywall` | Delete a paywall |
 | `get_paywall_payments` | View payment history for a paywall |
 | `get_x402_revenue` | Aggregate revenue stats across all paywalls |
+| `wallet_mode` | Report whether signing is local (self-custody) or hosted, and which address is in use |
+| `export_wallet_key` | How to export a hosted wallet key and move to self-custody |
 | `buy_verification_credits` | Buy x402 verification credits with USDC on-chain |
 | `get_usage` | Check your monthly usage and billing |
 | `get_chains` | List all supported chains |
@@ -160,7 +203,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(
@@ -170,7 +213,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
 
@@ -194,7 +239,7 @@ When an agent hits the paywall URL:
 3. Retries with proof of payment
 4. Receives the protected content
 
-On-chain verification ensures every payment is real. Replay protection prevents double-spending. Revenue tracking shows you who paid, how much, and when. 1,000 free verifications/month, then $0.0005 each — 50% less expensive than Coinbase.
+On-chain verification ensures every payment is real. Replay protection prevents double-spending. Revenue tracking shows you who paid, how much, and when. 1,000 free verifications/month, then $0.0005 each, 50% under Coinbase as of 2026-07-29.
 
 ## How We Compare
 

package/build/index.js

@@ -12,17 +12,111 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { deriveX402Payment } from './x402-payment.js';
+import { deriveX402Payment, isWithinCap } from './x402-payment.js';
+import { isLocalMode, getLocalAddress, localWalletRecord, localSend, localNativeBalance, localTokenBalance, localSignMessage, resolveRpcUrl, } from './local-wallet.js';
 // ─── Configuration ──────────────────────────────────────────────
 const API_BASE = process.env.AGENTWALLET_API_URL || 'https://hifriendbot.com/wp-json/agentwallet/v1';
 const API_USER = process.env.AGENTWALLET_USER || '';
 const API_PASS = process.env.AGENTWALLET_PASS || ''; // WordPress application password
 const X402_WALLET_ID = process.env.AGENTWALLET_WALLET_ID || ''; // Wallet ID for x402 auto-pay
+const DASHBOARD_URL = process.env.AGENTWALLET_DASHBOARD_URL || 'https://hifriendbot.com/wallet/';
+/* ── Local-mode routing ──────────────────────────────────────────
+   Translates the REST paths the tools already speak into in-process signing
+   calls. Anything not listed here falls through to the hosted API, so
+   non-custodial concerns (paywalls, billing, usage) still work if the operator
+   has also configured credentials. */
+const NOT_HANDLED = Symbol('not-handled');
+function localChainId(body, qs) {
+    const fromBody = body?.chain_id;
+    if (typeof fromBody === 'number')
+        return fromBody;
+    const fromQs = qs?.get('chain_id');
+    if (fromQs)
+        return parseInt(fromQs, 10);
+    const fromEnv = (process.env.AGENTWALLET_CHAIN_ID || '').trim();
+    if (fromEnv)
+        return parseInt(fromEnv, 10);
+    return 8453; // Base, matching the custodial default
+}
+function refuseSolanaLocally() {
+    throw new Error('Local signing mode currently supports EVM chains only. Solana keys are not signed in-process yet, ' +
+        'so this call was refused rather than silently routed through the hosted custodial API. ' +
+        'Unset AGENTWALLET_PRIVATE_KEY to use the custodial path for Solana.');
+}
+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 (body?.token_mint)
+            refuseSolanaLocally();
+        const chainId = localChainId(body, qs);
+        if (SOLANA_CHAIN_IDS.has(chainId))
+            refuseSolanaLocally();
+        const to = String(body?.to || '');
+        const value = BigInt(String(body?.value ?? '0'));
+        const data = String(body?.data || '');
+        if (!/^0x[a-fA-F0-9]{40}$/.test(to)) {
+            throw new Error(`Local mode expects an EVM address, got "${to}".`);
+        }
+        const hasData = data && data !== '0x';
+        return localSend(chainId, to, value, hasData ? data : undefined);
+    }
+    // GET /wallets/{id}/balance
+    if (method === 'GET' && /^\/wallets\/[^/]*\/balance$/.test(rawPath)) {
+        const chainId = localChainId(body, qs);
+        if (SOLANA_CHAIN_IDS.has(chainId))
+            refuseSolanaLocally();
+        return localNativeBalance(chainId);
+    }
+    // GET /wallets/{id}/token-balance
+    if (method === 'GET' && /^\/wallets\/[^/]*\/token-balance$/.test(rawPath)) {
+        const chainId = localChainId(body, qs);
+        if (SOLANA_CHAIN_IDS.has(chainId))
+            refuseSolanaLocally();
+        const token = qs.get('token') || qs.get('token_address') || '';
+        if (!/^0x[a-fA-F0-9]{40}$/.test(token)) {
+            throw new Error(`Local mode needs an EVM token address, got "${token}".`);
+        }
+        return localTokenBalance(chainId, token);
+    }
+    // POST /wallets/{id}/sign  (message signing only; tx signing goes through send)
+    if (method === 'POST' && /^\/wallets\/[^/]*\/sign$/.test(rawPath)) {
+        const message = body?.message;
+        if (typeof message === 'string' && message)
+            return localSignMessage(message);
+        throw new Error('Local mode signs messages in-process. For transactions use send_transaction, ' +
+            'which signs and broadcasts locally in one step.');
+    }
+    // Wallet listing and lookup describe the one local key.
+    if (method === 'GET' && rawPath === '/wallets')
+        return { wallets: [localWalletRecord()] };
+    if (method === 'GET' && /^\/wallets\/[^/]+$/.test(rawPath))
+        return localWalletRecord();
+    if (method === 'POST' && rawPath === '/wallets') {
+        throw new Error('Local signing mode uses the single key you supplied, so there is nothing to create. ' +
+            'Generate another key yourself and run a second instance with a different ' +
+            'AGENTWALLET_PRIVATE_KEY, or unset it to create hosted wallets.');
+    }
+    if (/^\/wallets\/[^/]*\/(pause|unpause)$/.test(rawPath) || (method === 'DELETE' && /^\/wallets\/[^/]+$/.test(rawPath))) {
+        throw new Error('Pause, unpause and delete are custodial controls: they work by refusing to sign on the server. ' +
+            'In local mode the key is yours, so nothing can freeze it. Stop the process or move the funds.');
+    }
+    return NOT_HANDLED;
+}
 /**
  * Make an API call. If the response is 402 and auto-pay is configured,
  * automatically pay via x402 and retry the request.
  */
 async function api(path, method = 'GET', body, extraHeaders) {
+    /* Local mode intercepts here rather than inside each tool. Routing at the
+       single choke point every funds operation already passes through means no
+       tool can quietly stay custodial because someone forgot to update it. */
+    if (isLocalMode()) {
+        const handled = await routeLocally(path, method, body);
+        if (handled !== NOT_HANDLED)
+            return handled;
+    }
     const url = `${API_BASE}${path}`;
     const headers = {
         'Content-Type': 'application/json',
@@ -37,8 +131,8 @@ async function api(path, method = 'GET', body, extraHeaders) {
     }
     const res = await fetch(url, options);
     const data = await res.json();
-    // Handle 402 Payment Required — auto-pay if wallet configured
-    if (res.status === 402 && X402_WALLET_ID && !extraHeaders?.['X-PAYMENT']) {
+    // Handle 402 Payment Required — auto-pay if a wallet or a local key is configured
+    if (res.status === 402 && (X402_WALLET_ID || isLocalMode()) && !extraHeaders?.['X-PAYMENT']) {
         return handleX402Payment(data, path, method, body);
     }
     if (!res.ok) {
@@ -221,7 +315,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.
 
@@ -744,7 +838,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 }) => {
@@ -826,35 +923,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,
             }));
@@ -868,11 +975,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,
@@ -921,7 +1028,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,
@@ -1083,10 +1190,80 @@ server.tool('get_x402_revenue', 'Get aggregate x402 revenue statistics across al
     const data = await api('/x402/revenue');
     return jsonResponse(data);
 });
+// ─── Tool: wallet_mode ──────────────────────────────────────────
+server.tool('wallet_mode', 'Report whether this server is signing locally (self-custody, the private key never leaves this machine) ' +
+    'or through the hosted AgentWallet API (custodial). Use this to verify custody before moving funds.', {}, async () => {
+    if (!isLocalMode()) {
+        return jsonResponse({
+            mode: 'custodial',
+            custody: 'agentwallet',
+            signing: 'AgentWallet servers hold an encrypted key and sign on your behalf.',
+            api_base: API_BASE,
+            to_self_custody: 'Set AGENTWALLET_PRIVATE_KEY (or AGENTWALLET_KEYFILE) and restart. ' +
+                'Use export_wallet_key first if you want to carry an existing hosted wallet across.',
+        });
+    }
+    let rpc = 'default public endpoint';
+    try {
+        rpc = resolveRpcUrl(parseInt(process.env.AGENTWALLET_CHAIN_ID || '8453', 10));
+    }
+    catch { /* chain has no default; not worth failing the report over */ }
+    return jsonResponse({
+        mode: 'local',
+        custody: 'self',
+        address: getLocalAddress(),
+        signing: 'Signed in this process. The private key is never sent to AgentWallet or anyone else.',
+        rpc_endpoint: rpc,
+        chains: 'EVM only in local mode. Solana calls are refused rather than routed to the custodial API.',
+        per_tx_cap_native: process.env.AGENTWALLET_MAX_TX_NATIVE || 'not set',
+        max_autopay: process.env.AGENTWALLET_MAX_AUTOPAY || '1',
+    });
+});
+// ─── Tool: export_wallet_key ────────────────────────────────────
+server.tool('export_wallet_key', 'Explain how to export the private key of a hosted (custodial) AgentWallet so it can be moved ' +
+    'to self-custody or any other wallet. Export itself is deliberately human-gated and is not ' +
+    'performed by this tool.', {
+    wallet_id: z.number().int().optional().describe('Hosted wallet ID to export'),
+}, async ({ wallet_id }) => {
+    if (isLocalMode()) {
+        return jsonResponse({
+            exportable: true,
+            mode: 'local',
+            note: 'You are already in self-custody. The key is the one you supplied via AGENTWALLET_PRIVATE_KEY ' +
+                'or AGENTWALLET_KEYFILE, and this server has no copy of it beyond this process.',
+        });
+    }
+    return jsonResponse({
+        exportable: true,
+        mode: 'custodial',
+        how: `Sign in at ${DASHBOARD_URL} and use Export key on the wallet. ` +
+            'The key is shown once and the export is logged.',
+        wallet_id: wallet_id ?? 'all wallets are exportable',
+        why_not_here: 'Export is gated behind a browser login rather than the API key on purpose. An API key can ' +
+            'spend within your limits; if it could also export keys, a leaked key would mean instant total loss. ' +
+            'Your funds stay portable either way: nothing here is locked in.',
+        after_export: 'Set AGENTWALLET_PRIVATE_KEY to the exported key and restart to run non-custodially, ' +
+            'or import it into any wallet you like.',
+    });
+});
 // ─── Start ──────────────────────────────────────────────────────
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    /* stderr, so it never corrupts the stdio JSON-RPC stream. Announcing custody
+       at startup means an operator sees which mode they are in without asking. */
+    if (isLocalMode()) {
+        try {
+            console.error(`AgentWallet MCP: LOCAL signing mode. Address ${getLocalAddress()}. Key never leaves this machine.`);
+        }
+        catch (e) {
+            console.error(`AgentWallet MCP: local signing configured but the key could not be loaded: ${e.message}`);
+            process.exit(1);
+        }
+    }
+    else {
+        console.error('AgentWallet MCP: custodial mode via ' + API_BASE + '. Run wallet_mode for details.');
+    }
 }
 main().catch((error) => {
     console.error('AgentWallet MCP server failed to start:', error);

package/build/local-wallet.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Local (non-custodial) signing mode.
+ *
+ * When AGENTWALLET_PRIVATE_KEY or AGENTWALLET_KEYFILE is set, every signing
+ * operation happens in this process with a key that never leaves the machine.
+ * The AgentWallet API is not called, not consulted, and not trusted for any
+ * funds-moving step. Transactions are broadcast straight to an RPC endpoint.
+ *
+ * This is the mode that makes the custody claim verifiable: an operator can
+ * read this file, run the server offline against their own RPC, and confirm the
+ * key is never transmitted. Nothing here writes the key to disk, logs it, or
+ * puts it in an error message.
+ *
+ * EVM only for now. Solana local signing is not implemented; those calls stay
+ * on the custodial path and say so explicitly rather than silently downgrading.
+ */
+import { type Address, type Hex } from 'viem';
+/** True when the server is running non-custodially. */
+export declare function isLocalMode(): boolean;
+export declare function getLocalAccount(): {
+    address: Address;
+    nonceManager?: import("viem").NonceManager | undefined;
+    sign: (parameters: {
+        hash: import("viem").Hash;
+    }) => Promise<Hex>;
+    signAuthorization: (parameters: import("viem").AuthorizationRequest) => Promise<import("viem/accounts").SignAuthorizationReturnType>;
+    signMessage: ({ message }: {
+        message: import("viem").SignableMessage;
+    }) => Promise<Hex>;
+    signTransaction: <serializer extends import("viem").SerializeTransactionFn<import("viem").TransactionSerializable> = import("viem").SerializeTransactionFn<import("viem").TransactionSerializable>, transaction extends Parameters<serializer>[0] = Parameters<serializer>[0]>(transaction: transaction, options?: {
+        serializer?: serializer | undefined;
+    } | undefined) => Promise<Hex>;
+    signTypedData: <const typedData extends import("viem").TypedData | Record<string, unknown>, primaryType extends keyof typedData | "EIP712Domain" = keyof typedData>(parameters: import("viem").TypedDataDefinition<typedData, primaryType>) => Promise<Hex>;
+    publicKey: Hex;
+    source: "privateKey";
+    type: "local";
+};
+/** The address the local key controls. Safe to log. */
+export declare function getLocalAddress(): Address;
+export declare function resolveRpcUrl(chainId: number): string;
+export declare function localNativeBalance(chainId: number): Promise<{
+    address: `0x${string}`;
+    chain_id: number;
+    balance_wei: string;
+    balance: string;
+    mode: string;
+}>;
+export declare function localTokenBalance(chainId: number, token: Address): Promise<{
+    address: `0x${string}`;
+    chain_id: number;
+    token: `0x${string}`;
+    symbol: string;
+    decimals: number;
+    balance_raw: string;
+    balance: string;
+    mode: string;
+}>;
+export interface LocalSendResult {
+    tx_hash: string;
+    from: string;
+    to: string;
+    value: string;
+    chain_id: number;
+    mode: 'local';
+    signed_locally: true;
+}
+/**
+ * Sign and broadcast a transaction. viem fills nonce, gas and EIP-1559 fees
+ * from the RPC unless they are supplied.
+ */
+export declare function localSend(chainId: number, to: Address, valueWei: bigint, data?: Hex): Promise<LocalSendResult>;
+/** ERC-20 transfer, encoded locally. */
+export declare function localTransferToken(chainId: number, token: Address, to: Address, rawAmount: string): Promise<LocalSendResult>;
+/** ERC-20 approve, encoded locally. */
+export declare function localApproveToken(chainId: number, token: Address, spender: Address, rawAmount: string): Promise<LocalSendResult>;
+/** Sign a message without broadcasting anything. */
+export declare function localSignMessage(message: string): Promise<{
+    address: string;
+    message: string;
+    signature: string;
+    mode: 'local';
+}>;
+/**
+ * One-line summary for tools that report wallet identity. Deliberately mirrors
+ * the shape of a custodial wallet record so callers do not need to branch.
+ */
+export declare function localWalletRecord(): {
+    id: string;
+    address: `0x${string}`;
+    wallet_type: string;
+    mode: string;
+    custody: string;
+    note: string;
+};

package/build/local-wallet.js

@@ -0,0 +1,225 @@
+/**
+ * Local (non-custodial) signing mode.
+ *
+ * When AGENTWALLET_PRIVATE_KEY or AGENTWALLET_KEYFILE is set, every signing
+ * operation happens in this process with a key that never leaves the machine.
+ * The AgentWallet API is not called, not consulted, and not trusted for any
+ * funds-moving step. Transactions are broadcast straight to an RPC endpoint.
+ *
+ * This is the mode that makes the custody claim verifiable: an operator can
+ * read this file, run the server offline against their own RPC, and confirm the
+ * key is never transmitted. Nothing here writes the key to disk, logs it, or
+ * puts it in an error message.
+ *
+ * EVM only for now. Solana local signing is not implemented; those calls stay
+ * on the custodial path and say so explicitly rather than silently downgrading.
+ */
+import { readFileSync } from 'node:fs';
+import { createPublicClient, createWalletClient, http, encodeFunctionData, parseAbi, formatUnits, } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+/* ── Key loading ─────────────────────────────────────────────────── */
+/**
+ * Read the key once at startup. Kept module-private: nothing exports the key
+ * itself, only an account object that can sign.
+ */
+let cachedAccount = null;
+let keyLoadError = null;
+function loadKeyMaterial() {
+    const inline = (process.env.AGENTWALLET_PRIVATE_KEY || '').trim();
+    if (inline)
+        return inline;
+    const file = (process.env.AGENTWALLET_KEYFILE || '').trim();
+    if (file) {
+        try {
+            return readFileSync(file, 'utf8').trim();
+        }
+        catch (e) {
+            keyLoadError = `Could not read AGENTWALLET_KEYFILE at ${file}: ${e.message}`;
+            return null;
+        }
+    }
+    return null;
+}
+function normalizeKey(raw) {
+    const hex = raw.startsWith('0x') ? raw.slice(2) : raw;
+    if (!/^[0-9a-fA-F]{64}$/.test(hex)) {
+        throw new Error('Invalid private key. Expected 64 hex characters, with or without a 0x prefix. ' +
+            'The value itself is never logged.');
+    }
+    return `0x${hex}`;
+}
+/** True when the server is running non-custodially. */
+export function isLocalMode() {
+    return Boolean((process.env.AGENTWALLET_PRIVATE_KEY || '').trim() ||
+        (process.env.AGENTWALLET_KEYFILE || '').trim());
+}
+export function getLocalAccount() {
+    if (cachedAccount)
+        return cachedAccount;
+    if (keyLoadError)
+        throw new Error(keyLoadError);
+    const raw = loadKeyMaterial();
+    if (!raw)
+        throw new Error('Local signing mode is not configured.');
+    if (keyLoadError)
+        throw new Error(keyLoadError);
+    cachedAccount = privateKeyToAccount(normalizeKey(raw));
+    return cachedAccount;
+}
+/** The address the local key controls. Safe to log. */
+export function getLocalAddress() {
+    return getLocalAccount().address;
+}
+/* ── Chains and RPC ──────────────────────────────────────────────── */
+/**
+ * Public RPC endpoints used only when the operator has not supplied their own.
+ * Anyone serious about privacy should set AGENTWALLET_RPC_<chainId>, because
+ * a public RPC sees every address you query.
+ */
+const DEFAULT_RPC = {
+    1: 'https://eth.llamarpc.com',
+    10: 'https://mainnet.optimism.io',
+    56: 'https://bsc-dataseed.binance.org',
+    137: 'https://polygon-rpc.com',
+    8453: 'https://mainnet.base.org',
+    42161: 'https://arb1.arbitrum.io/rpc',
+    43114: 'https://api.avax.network/ext/bc/C/rpc',
+    7777777: 'https://rpc.zora.energy',
+    369: 'https://rpc.pulsechain.com',
+};
+export function resolveRpcUrl(chainId) {
+    const perChain = (process.env[`AGENTWALLET_RPC_${chainId}`] || '').trim();
+    if (perChain)
+        return perChain;
+    const generic = (process.env.AGENTWALLET_RPC_URL || '').trim();
+    if (generic)
+        return generic;
+    const fallback = DEFAULT_RPC[chainId];
+    if (fallback)
+        return fallback;
+    throw new Error(`No RPC endpoint for chain ${chainId} in local mode. ` +
+        `Set AGENTWALLET_RPC_${chainId} to an endpoint you trust.`);
+}
+function clients(chainId) {
+    const url = resolveRpcUrl(chainId);
+    const transport = http(url);
+    // The chain object is deliberately minimal: viem only needs the id for
+    // signing, and not pinning a chain definition keeps any EVM network usable.
+    const chain = { id: chainId, name: `chain-${chainId}`, nativeCurrency: { name: 'Native', symbol: 'NATIVE', decimals: 18 }, rpcUrls: { default: { http: [url] } } };
+    return {
+        pub: createPublicClient({ chain, transport }),
+        wallet: createWalletClient({ account: getLocalAccount(), chain, transport }),
+    };
+}
+/* ── Spend guards ────────────────────────────────────────────────── */
+/**
+ * Per-transaction ceiling for local mode, in native units (ETH, MATIC...).
+ * Custodial mode enforces limits server-side; local mode has no server, so the
+ * guard has to live here or it does not exist at all.
+ */
+function assertWithinNativeCap(valueWei) {
+    const cap = (process.env.AGENTWALLET_MAX_TX_NATIVE || '').trim();
+    if (!cap)
+        return;
+    if (!/^\d+(\.\d+)?$/.test(cap)) {
+        throw new Error(`AGENTWALLET_MAX_TX_NATIVE must be a decimal number, got "${cap}".`);
+    }
+    const [whole, frac = ''] = cap.split('.');
+    const capWei = BigInt(whole + frac.padEnd(18, '0').slice(0, 18));
+    if (valueWei > capWei) {
+        throw new Error(`Blocked by local guard: transaction value exceeds AGENTWALLET_MAX_TX_NATIVE (${cap}). ` +
+            `Raise the cap deliberately if this is intended.`);
+    }
+}
+/* ── Read operations ─────────────────────────────────────────────── */
+export async function localNativeBalance(chainId) {
+    const { pub } = clients(chainId);
+    const address = getLocalAddress();
+    const wei = await pub.getBalance({ address });
+    return { address, chain_id: chainId, balance_wei: wei.toString(), balance: formatUnits(wei, 18), mode: 'local' };
+}
+const ERC20_ABI = parseAbi([
+    'function balanceOf(address) view returns (uint256)',
+    'function decimals() view returns (uint8)',
+    'function symbol() view returns (string)',
+    'function transfer(address,uint256) returns (bool)',
+    'function approve(address,uint256) returns (bool)',
+    'function allowance(address,address) view returns (uint256)',
+]);
+export async function localTokenBalance(chainId, token) {
+    const { pub } = clients(chainId);
+    const address = getLocalAddress();
+    const [raw, decimals, symbol] = await Promise.all([
+        pub.readContract({ address: token, abi: ERC20_ABI, functionName: 'balanceOf', args: [address] }),
+        pub.readContract({ address: token, abi: ERC20_ABI, functionName: 'decimals' }).catch(() => 18),
+        pub.readContract({ address: token, abi: ERC20_ABI, functionName: 'symbol' }).catch(() => ''),
+    ]);
+    return {
+        address, chain_id: chainId, token, symbol,
+        decimals: Number(decimals),
+        balance_raw: raw.toString(),
+        balance: formatUnits(raw, Number(decimals)),
+        mode: 'local',
+    };
+}
+/**
+ * Sign and broadcast a transaction. viem fills nonce, gas and EIP-1559 fees
+ * from the RPC unless they are supplied.
+ */
+export async function localSend(chainId, to, valueWei, data) {
+    assertWithinNativeCap(valueWei);
+    const { wallet } = clients(chainId);
+    const hash = await wallet.sendTransaction({
+        to,
+        value: valueWei,
+        ...(data ? { data } : {}),
+    });
+    return {
+        tx_hash: hash,
+        from: getLocalAddress(),
+        to,
+        value: valueWei.toString(),
+        chain_id: chainId,
+        mode: 'local',
+        signed_locally: true,
+    };
+}
+/** ERC-20 transfer, encoded locally. */
+export async function localTransferToken(chainId, token, to, rawAmount) {
+    const data = encodeFunctionData({
+        abi: ERC20_ABI,
+        functionName: 'transfer',
+        args: [to, BigInt(rawAmount)],
+    });
+    const res = await localSend(chainId, token, 0n, data);
+    return { ...res, to, value: rawAmount };
+}
+/** ERC-20 approve, encoded locally. */
+export async function localApproveToken(chainId, token, spender, rawAmount) {
+    const data = encodeFunctionData({
+        abi: ERC20_ABI,
+        functionName: 'approve',
+        args: [spender, BigInt(rawAmount)],
+    });
+    const res = await localSend(chainId, token, 0n, data);
+    return { ...res, to: spender, value: rawAmount };
+}
+/** Sign a message without broadcasting anything. */
+export async function localSignMessage(message) {
+    const signature = await getLocalAccount().signMessage({ message });
+    return { address: getLocalAddress(), message, signature, mode: 'local' };
+}
+/**
+ * One-line summary for tools that report wallet identity. Deliberately mirrors
+ * the shape of a custodial wallet record so callers do not need to branch.
+ */
+export function localWalletRecord() {
+    return {
+        id: 'local',
+        address: getLocalAddress(),
+        wallet_type: 'evm',
+        mode: 'local',
+        custody: 'self',
+        note: 'Signed in-process. The private key is never sent to AgentWallet servers.',
+    };
+}

package/build/x402-payment.d.ts

@@ -32,3 +32,17 @@ export declare function deriveX402Payment(accept: X402AcceptLike, maxAutopayHuma
     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

@@ -44,3 +44,23 @@ export function deriveX402Payment(accept, maxAutopayHuman) {
     }
     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.5",
-  "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.9.0",
+  "description": "MCP server for AgentWallet: self-custody local signing or hosted wallets. Lets AI agents sign and broadcast on EVM + Solana, pay x402 invoices, and accept x402 payments.",
   "type": "module",
   "main": "build/index.js",
   "bin": {
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "tsc",
     "start": "node build/index.js",
-    "test": "node test/x402-payment.test.mjs",
+    "test": "node test/x402-payment.test.mjs && node test/local-mode.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -43,7 +43,10 @@
     "x402",
     "http-402",
     "agent-payments",
-    "agentwallet"
+    "agentwallet",
+    "self-custody",
+    "non-custodial",
+    "local-signing"
   ],
   "author": "HiFriendbot (https://hifriendbot.com)",
   "license": "MIT",
@@ -53,6 +56,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.11.4",
+    "viem": "^2.55.10",
     "zod": "^3.24.0"
   },
   "devDependencies": {