agentwallet-mcp 1.8.0 → 1.10.0

package/README.md

@@ -1,36 +1,99 @@
 # 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.
 
-**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.**
+**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 + Solana | EVM + Solana |
+| Can anyone freeze it | No | Yes, that is what pause is for |
+| Spend guards | `AGENTWALLET_MAX_TX_NATIVE`, `AGENTWALLET_MAX_TX_SOL`, `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.
+
+### Solana local signing
+
+```json
+"env": {
+  "AGENTWALLET_SOLANA_KEY": "[12,34...]",
+  "AGENTWALLET_SOLANA_RPC": "https://your-own-rpc",
+  "AGENTWALLET_MAX_TX_SOL": "1"
+}
+```
+
+Accepts whichever format you already have: a `solana-keygen` id.json array, a base58 secret key as exported by Phantom, or base64. Use `AGENTWALLET_SOLANA_KEYFILE` to point at a file instead. Native SOL and SPL token transfers are both signed locally, and a missing associated token account is created for the recipient automatically.
+
+Set either key, or both. They are independent: run EVM locally and Solana hosted, or the reverse.
+
+**An operation with no matching local key is refused, never silently routed to the hosted signer.** If you have an EVM key configured and ask for a Solana transfer with no Solana key, the server stops and tells you which variable is missing. Quietly moving funds onto a key you do not hold, while you believe you are in self-custody, is the worst thing this server could do.
+
+### About the dependency tree
+
+Local signing uses [viem](https://viem.sh) for EVM and `@solana/web3.js` for Solana, plus `bs58` for key parsing. SPL instructions are built by hand rather than with `@solana/spl-token`, because that package pulls in `bigint-buffer`, which carries a high severity buffer overflow advisory. A wallet has no business shipping that to save a dozen lines of instruction encoding.
+
+`npm audit` currently reports issues inside `@modelcontextprotocol/sdk`'s HTTP transport dependencies. This server speaks stdio, so that code never loads, and the SDK is not something this package can patch. Run the audit yourself. Publishing a tree you can inspect is the point.
 
 <p align="center">
-  <img src="assets/demo.svg" alt="AgentWallet demo — AI agent pays x402 invoice automatically" width="800">
+  <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
-- **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
-- **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.
+- **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)
+- **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**
 - **6,000 free operations/month**
-- **$0.0005 per x402 verification** (50% less expensive than Coinbase)
+- **$0.0005 per x402 verification**
 - **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
+- **Pay with USDC on-chain** via x402, no credit card required
+- No monthly fee, no tiers, just pay as you go
+
+Competitor comparisons are kept at [hifriendbot.com/wallet/#pricing](https://hifriendbot.com/wallet/#pricing) with the date they were last verified. They live there rather than here because a published npm README cannot be corrected when someone else changes their prices.
 
 ## Quick Start
 
-Get your free API key at [hifriendbot.com/wallet](https://hifriendbot.com/wallet) — no credit card required, no KYC, no approval wait.
+Get your free API key at [hifriendbot.com/wallet](https://hifriendbot.com/wallet), no credit card required, no KYC, no approval wait.
 
 ### Claude Desktop / OpenClaw
 
@@ -115,6 +178,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 |
@@ -196,14 +261,14 @@ 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. See the [pricing comparison](https://hifriendbot.com/wallet/#pricing) for how that stacks up.
 
 ## How We Compare
 
 | Feature | Coinbase CDP | AgentWallet |
 |---------|-------------|-------------|
 | Setup Time | Install SDK + configure | **3 lines of config** |
-| Approval Process | Identity verification required | **None — instant access** |
+| Approval Process | Identity verification required | **None, instant access** |
 | KYC Required | Yes | **No** |
 | KYT / Transaction Monitoring | Yes | **No** |
 | Can Block Your Wallet | Yes | **No** |
@@ -218,27 +283,27 @@ On-chain verification ensures every payment is real. Replay protection prevents
 | Token Tools | Yes | **ERC-20 + SPL (29 tools)** |
 | MCP Server | Yes | **Yes** |
 
-## Pay with Crypto — No Credit Card Required
+## Pay with Crypto, No Credit Card Required
 
-AgentWallet is the only AI agent wallet infrastructure that accepts crypto for its own API fees. Every competitor — Coinbase CDP, Circle, MoonPay, Crossmint, Turnkey — requires a credit card or monthly invoice. With AgentWallet, your agent can pay for operations with USDC on-chain via the x402 protocol. No credit card, no invoice, no billing portal. Just on-chain payments.
+AgentWallet is the only AI agent wallet infrastructure that accepts crypto for its own API fees. Every competitor, Coinbase CDP, Circle, MoonPay, Crossmint, Turnkey, requires a credit card or monthly invoice. With AgentWallet, your agent can pay for operations with USDC on-chain via the x402 protocol. No credit card, no invoice, no billing portal. Just on-chain payments.
 
 When your agent exceeds the free tier (6,000 ops/month) without a credit card configured, the API returns HTTP 402 with USDC payment instructions. Your agent pays on-chain, retries with proof of payment, and the operation executes. Fully automated via the MCP server.
 
-You can also pre-purchase x402 verification credits with USDC using the `buy_verification_credits` tool — keeping your paywalls running beyond the free 1,000 verifications/month without needing a credit card.
+You can also pre-purchase x402 verification credits with USDC using the `buy_verification_credits` tool, keeping your paywalls running beyond the free 1,000 verifications/month without needing a credit card.
 
 ## Built-in Guards
 
-All guards are active by default — no configuration required.
-
-- **Encrypted at rest** — private keys encrypted before storage and never leave the server
-- **Memory zeroing** — keys wiped from memory immediately after every signing operation
-- **Daily spending limits** — set a per-wallet daily cap in USD, enforced automatically on every transaction
-- **Gas price protection** — transactions blocked when gas prices spike above safe thresholds
-- **Emergency pause** — instantly freeze any wallet or all wallets with one click
-- **Rate limiting** — API requests capped per minute to prevent abuse and brute force attacks
-- **Replay protection** — every x402 payment verified on-chain with unique transaction tracking
-- **On-chain verification** — x402 payments verified directly on the blockchain with finalized commitment
-- Bug bounty program: $50–$500 for responsible disclosure ([details](https://hifriendbot.com/wallet))
+All guards are active by default, no configuration required.
+
+- **Encrypted at rest**: private keys encrypted before storage and never leave the server
+- **Memory zeroing**: keys wiped from memory immediately after every signing operation
+- **Daily spending limits**: set a per-wallet daily cap in USD, enforced automatically on every transaction
+- **Gas price protection**: transactions blocked when gas prices spike above safe thresholds
+- **Emergency pause**: instantly freeze any wallet or all wallets with one click
+- **Rate limiting**: API requests capped per minute to prevent abuse and brute force attacks
+- **Replay protection**: every x402 payment verified on-chain with unique transaction tracking
+- **On-chain verification**: x402 payments verified directly on the blockchain with finalized commitment
+- Bug bounty program: $50,$500 for responsible disclosure ([details](https://hifriendbot.com/wallet))
 
 ## Links
 

package/build/index.js

@@ -13,16 +13,155 @@ 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';
+import { isLocalMode, getLocalAddress, localWalletRecord, localSend, localNativeBalance, localTokenBalance, localSignMessage, resolveRpcUrl, } from './local-wallet.js';
+import { isSolanaLocalMode, getSolanaAddress, solanaWalletRecord, localSolBalance, localSplBalance, localSolTransfer, localSplTransfer, resolveSolanaRpc, } from './local-solana.js';
+/** True when either chain family is running non-custodially. */
+function anyLocalMode() {
+    return isLocalMode() || isSolanaLocalMode();
+}
 // ─── 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
+}
+/**
+ * Refuse rather than silently hand the operation to someone else's signer.
+ *
+ * Reached when the operator is running non-custodially for one chain family but
+ * has supplied no key for the other. Falling through to the hosted API here
+ * would move funds onto a key they do not hold, while they believe they are in
+ * self-custody. That is the single worst thing this server could do, so it
+ * stops and says exactly which variable is missing.
+ */
+function refuseMissingLocalKey(family) {
+    const wanted = family === 'solana'
+        ? 'AGENTWALLET_SOLANA_KEY (or AGENTWALLET_SOLANA_KEYFILE)'
+        : 'AGENTWALLET_PRIVATE_KEY (or AGENTWALLET_KEYFILE)';
+    throw new Error(`This is a ${family === 'solana' ? 'Solana' : 'EVM'} operation and no local ${family === 'solana' ? 'Solana' : 'EVM'} key is configured, ` +
+        `but this server is running in local signing mode. Refusing rather than routing it through the hosted ` +
+        `custodial signer while you believe you hold the keys. Set ${wanted} to sign it here, or unset the other ` +
+        `local key variables to use the hosted path for everything.`);
+}
+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)) {
+        const chainId = localChainId(body, qs);
+        const solanaOp = SOLANA_CHAIN_IDS.has(chainId) || Boolean(body?.token_mint);
+        if (solanaOp) {
+            if (!isSolanaLocalMode())
+                refuseMissingLocalKey('solana');
+            const to = String(body?.to || '');
+            const value = String(body?.value ?? '0');
+            if (body?.token_mint) {
+                return localSplTransfer(String(body.token_mint), to, value, Number(body.token_decimals ?? 6), chainId);
+            }
+            return localSolTransfer(to, value, chainId);
+        }
+        if (!isLocalMode())
+            refuseMissingLocalKey('evm');
+        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)) {
+            if (!isSolanaLocalMode())
+                refuseMissingLocalKey('solana');
+            return localSolBalance(chainId);
+        }
+        if (!isLocalMode())
+            refuseMissingLocalKey('evm');
+        return localNativeBalance(chainId);
+    }
+    // GET /wallets/{id}/token-balance
+    if (method === 'GET' && /^\/wallets\/[^/]*\/token-balance$/.test(rawPath)) {
+        const chainId = localChainId(body, qs);
+        const token0 = qs.get('token') || qs.get('token_address') || '';
+        if (SOLANA_CHAIN_IDS.has(chainId)) {
+            if (!isSolanaLocalMode())
+                refuseMissingLocalKey('solana');
+            return localSplBalance(token0, chainId);
+        }
+        if (!isLocalMode())
+            refuseMissingLocalKey('evm');
+        const token = token0;
+        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 whichever local keys are configured.
+    if (method === 'GET' && rawPath === '/wallets') {
+        const wallets = [];
+        if (isLocalMode())
+            wallets.push(localWalletRecord());
+        if (isSolanaLocalMode())
+            wallets.push(solanaWalletRecord());
+        return { wallets };
+    }
+    if (method === 'GET' && /^\/wallets\/[^/]+$/.test(rawPath)) {
+        return isLocalMode() ? localWalletRecord() : solanaWalletRecord();
+    }
+    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 (anyLocalMode()) {
+        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 +176,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 || anyLocalMode()) && !extraHeaders?.['X-PAYMENT']) {
         return handleX402Payment(data, path, method, body);
     }
     if (!res.ok) {
@@ -1096,10 +1235,107 @@ 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 (!anyLocalMode()) {
+        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 for EVM and/or AGENTWALLET_SOLANA_KEY for Solana, then restart. ' +
+                'Use export_wallet_key first if you want to carry an existing hosted wallet across.',
+        });
+    }
+    const report = {
+        mode: 'local',
+        custody: 'self',
+        signing: 'Signed in this process. Keys are never sent to AgentWallet or anyone else.',
+        max_autopay: process.env.AGENTWALLET_MAX_AUTOPAY || '1',
+    };
+    if (isLocalMode()) {
+        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 */ }
+        report.evm = {
+            address: getLocalAddress(),
+            rpc_endpoint: rpc,
+            per_tx_cap_native: process.env.AGENTWALLET_MAX_TX_NATIVE || 'not set',
+        };
+    }
+    else {
+        report.evm = 'no local EVM key. EVM operations are refused, not sent to the hosted signer.';
+    }
+    if (isSolanaLocalMode()) {
+        let rpc = 'default public endpoint';
+        try {
+            rpc = resolveSolanaRpc(900);
+        }
+        catch { /* fall through to the default label */ }
+        report.solana = {
+            address: getSolanaAddress(),
+            rpc_endpoint: rpc,
+            per_tx_cap_sol: process.env.AGENTWALLET_MAX_TX_SOL || 'not set',
+        };
+    }
+    else {
+        report.solana = 'no local Solana key. Solana operations are refused, not sent to the hosted signer.';
+    }
+    return jsonResponse(report);
+});
+// ─── 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 (anyLocalMode()) {
+        return jsonResponse({
+            exportable: true,
+            mode: 'local',
+            note: 'You are already in self-custody. The keys are the ones you supplied via AGENTWALLET_PRIVATE_KEY, ' +
+                'AGENTWALLET_SOLANA_KEY or their KEYFILE variants, and this server keeps no copy 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 (anyLocalMode()) {
+        try {
+            const parts = [];
+            if (isLocalMode())
+                parts.push(`EVM ${getLocalAddress()}`);
+            if (isSolanaLocalMode())
+                parts.push(`Solana ${getSolanaAddress()}`);
+            console.error(`AgentWallet MCP: LOCAL signing mode. ${parts.join(', ')}. Keys never leave this machine.`);
+        }
+        catch (e) {
+            console.error(`AgentWallet MCP: local signing configured but a 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-solana.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Local (non-custodial) Solana signing.
+ *
+ * Same contract as local-wallet.ts on the EVM side: the secret key is loaded
+ * once into this process, never written anywhere, never logged, and never put
+ * in an error message. Transactions are signed here and submitted straight to
+ * an RPC endpoint. The AgentWallet API is not involved.
+ *
+ * SPL transfers are built from raw instructions rather than @solana/spl-token
+ * on purpose. That package pulls in bigint-buffer, which carries a high
+ * severity buffer overflow advisory, and a wallet has no business shipping
+ * that when the two instructions it needs are a dozen lines each.
+ */
+import { Keypair } from '@solana/web3.js';
+export declare function isSolanaLocalMode(): boolean;
+export declare function getSolanaKeypair(): Keypair;
+export declare function getSolanaAddress(): string;
+export declare function resolveSolanaRpc(chainId?: number): string;
+export declare function localSolBalance(chainId?: number): Promise<{
+    address: string;
+    chain_id: number;
+    balance_lamports: string;
+    balance: string;
+    mode: string;
+}>;
+export declare function localSplBalance(mintStr: string, chainId?: number): Promise<{
+    address: string;
+    chain_id: number;
+    mint: string;
+    token_account: string;
+    balance_raw: string;
+    balance: string;
+    decimals: number;
+    mode: string;
+}>;
+export interface LocalSolResult {
+    signature: string;
+    from: string;
+    to: string;
+    value: string;
+    chain_id: number;
+    mode: 'local';
+    signed_locally: true;
+}
+export declare function localSolTransfer(to: string, lamports: string, chainId?: number): Promise<LocalSolResult>;
+/**
+ * Transfer SPL tokens. The recipient's associated account is created if it does
+ * not exist, using the idempotent instruction so a race cannot fail the send.
+ */
+export declare function localSplTransfer(mintStr: string, to: string, rawAmount: string, decimals: number, chainId?: number): Promise<LocalSolResult>;
+export declare function solanaWalletRecord(): {
+    id: string;
+    address: string;
+    wallet_type: string;
+    mode: string;
+    custody: string;
+    note: string;
+};

package/build/local-solana.js

@@ -0,0 +1,252 @@
+/**
+ * Local (non-custodial) Solana signing.
+ *
+ * Same contract as local-wallet.ts on the EVM side: the secret key is loaded
+ * once into this process, never written anywhere, never logged, and never put
+ * in an error message. Transactions are signed here and submitted straight to
+ * an RPC endpoint. The AgentWallet API is not involved.
+ *
+ * SPL transfers are built from raw instructions rather than @solana/spl-token
+ * on purpose. That package pulls in bigint-buffer, which carries a high
+ * severity buffer overflow advisory, and a wallet has no business shipping
+ * that when the two instructions it needs are a dozen lines each.
+ */
+import { readFileSync } from 'node:fs';
+import { Connection, Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction, sendAndConfirmTransaction, LAMPORTS_PER_SOL, } from '@solana/web3.js';
+import bs58 from 'bs58';
+/* ── Program IDs ─────────────────────────────────────────────────── */
+const TOKEN_PROGRAM = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
+const TOKEN_2022_PROGRAM = new PublicKey('TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb');
+const ASSOCIATED_TOKEN_PROGRAM = new PublicKey('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL');
+/* ── Key loading ─────────────────────────────────────────────────── */
+let cached = null;
+/**
+ * Accepts every format a Solana user is likely to already have:
+ *   - solana-keygen id.json, a JSON array of 64 bytes
+ *   - base58 secret key, what Phantom and friends export
+ *   - base64, 64 bytes, or the 96-byte sodium keypair AgentWallet exports
+ *     for hosted Solana wallets (its first 64 bytes are the secret key)
+ */
+function parseSolanaKey(raw) {
+    const text = raw.trim();
+    if (text.startsWith('[')) {
+        const arr = JSON.parse(text);
+        if (!Array.isArray(arr) || arr.length < 64) {
+            throw new Error('Solana key JSON must be an array of at least 64 bytes.');
+        }
+        return Keypair.fromSecretKey(Uint8Array.from(arr.slice(0, 64)));
+    }
+    // base64 tends to contain characters base58 never does.
+    if (/[+/=]/.test(text)) {
+        const buf = Buffer.from(text, 'base64');
+        if (buf.length !== 64 && buf.length !== 96) {
+            throw new Error(`Base64 Solana key must decode to 64 or 96 bytes, got ${buf.length}.`);
+        }
+        return Keypair.fromSecretKey(Uint8Array.from(buf.subarray(0, 64)));
+    }
+    const decoded = bs58.decode(text);
+    if (decoded.length !== 64) {
+        throw new Error(`Base58 Solana key must decode to 64 bytes, got ${decoded.length}.`);
+    }
+    return Keypair.fromSecretKey(decoded);
+}
+export function isSolanaLocalMode() {
+    return Boolean((process.env.AGENTWALLET_SOLANA_KEY || '').trim() ||
+        (process.env.AGENTWALLET_SOLANA_KEYFILE || '').trim());
+}
+export function getSolanaKeypair() {
+    if (cached)
+        return cached;
+    const inline = (process.env.AGENTWALLET_SOLANA_KEY || '').trim();
+    const file = (process.env.AGENTWALLET_SOLANA_KEYFILE || '').trim();
+    let raw = inline;
+    if (!raw && file) {
+        try {
+            raw = readFileSync(file, 'utf8');
+        }
+        catch (e) {
+            throw new Error(`Could not read AGENTWALLET_SOLANA_KEYFILE at ${file}: ${e.message}`);
+        }
+    }
+    if (!raw)
+        throw new Error('Solana local signing is not configured.');
+    try {
+        cached = parseSolanaKey(raw);
+    }
+    catch (e) {
+        // Re-thrown deliberately without the key material in the message.
+        throw new Error(`Invalid Solana key: ${e.message}`);
+    }
+    return cached;
+}
+export function getSolanaAddress() {
+    return getSolanaKeypair().publicKey.toBase58();
+}
+/* ── Connection ──────────────────────────────────────────────────── */
+const DEFAULT_SOLANA_RPC = {
+    900: 'https://api.mainnet-beta.solana.com',
+    901: 'https://api.devnet.solana.com',
+    902: 'https://api.testnet.solana.com',
+};
+export function resolveSolanaRpc(chainId = 900) {
+    const explicit = (process.env.AGENTWALLET_SOLANA_RPC || '').trim();
+    if (explicit)
+        return explicit;
+    const fallback = DEFAULT_SOLANA_RPC[chainId];
+    if (fallback)
+        return fallback;
+    throw new Error(`No Solana RPC for chain ${chainId}. Set AGENTWALLET_SOLANA_RPC.`);
+}
+function connection(chainId = 900) {
+    return new Connection(resolveSolanaRpc(chainId), 'confirmed');
+}
+/* ── Guards ──────────────────────────────────────────────────────── */
+function assertWithinSolCap(lamports) {
+    const cap = (process.env.AGENTWALLET_MAX_TX_SOL || '').trim();
+    if (!cap)
+        return;
+    if (!/^\d+(\.\d+)?$/.test(cap)) {
+        throw new Error(`AGENTWALLET_MAX_TX_SOL must be a decimal number, got "${cap}".`);
+    }
+    const [whole, frac = ''] = cap.split('.');
+    const capLamports = BigInt(whole + frac.padEnd(9, '0').slice(0, 9));
+    if (lamports > capLamports) {
+        throw new Error(`Blocked by local guard: amount exceeds AGENTWALLET_MAX_TX_SOL (${cap} SOL).`);
+    }
+}
+/* ── Reads ───────────────────────────────────────────────────────── */
+export async function localSolBalance(chainId = 900) {
+    const conn = connection(chainId);
+    const owner = getSolanaKeypair().publicKey;
+    const lamports = await conn.getBalance(owner);
+    return {
+        address: owner.toBase58(),
+        chain_id: chainId,
+        balance_lamports: String(lamports),
+        balance: String(lamports / LAMPORTS_PER_SOL),
+        mode: 'local',
+    };
+}
+/** Which token program owns this mint: classic SPL or Token-2022. */
+async function tokenProgramFor(conn, mint) {
+    const info = await conn.getAccountInfo(mint);
+    if (!info)
+        throw new Error(`Mint ${mint.toBase58()} not found on this cluster.`);
+    if (info.owner.equals(TOKEN_2022_PROGRAM))
+        return TOKEN_2022_PROGRAM;
+    return TOKEN_PROGRAM;
+}
+function associatedTokenAddress(owner, mint, tokenProgram) {
+    const [ata] = PublicKey.findProgramAddressSync([owner.toBuffer(), tokenProgram.toBuffer(), mint.toBuffer()], ASSOCIATED_TOKEN_PROGRAM);
+    return ata;
+}
+export async function localSplBalance(mintStr, chainId = 900) {
+    const conn = connection(chainId);
+    const owner = getSolanaKeypair().publicKey;
+    const mint = new PublicKey(mintStr);
+    const tokenProgram = await tokenProgramFor(conn, mint);
+    const ata = associatedTokenAddress(owner, mint, tokenProgram);
+    const res = await conn.getTokenAccountBalance(ata).catch(() => null);
+    return {
+        address: owner.toBase58(),
+        chain_id: chainId,
+        mint: mintStr,
+        token_account: ata.toBase58(),
+        balance_raw: res?.value.amount ?? '0',
+        balance: res?.value.uiAmountString ?? '0',
+        decimals: res?.value.decimals ?? 0,
+        mode: 'local',
+    };
+}
+export async function localSolTransfer(to, lamports, chainId = 900) {
+    const amount = BigInt(lamports);
+    assertWithinSolCap(amount);
+    const conn = connection(chainId);
+    const payer = getSolanaKeypair();
+    const tx = new Transaction().add(SystemProgram.transfer({
+        fromPubkey: payer.publicKey,
+        toPubkey: new PublicKey(to),
+        lamports: Number(amount),
+    }));
+    const signature = await sendAndConfirmTransaction(conn, tx, [payer]);
+    return {
+        signature,
+        from: payer.publicKey.toBase58(),
+        to,
+        value: lamports,
+        chain_id: chainId,
+        mode: 'local',
+        signed_locally: true,
+    };
+}
+/** SPL transferChecked, opcode 12: amount as u64 LE followed by decimals. */
+function transferCheckedIx(tokenProgram, source, mint, dest, owner, amount, decimals) {
+    const data = Buffer.alloc(10);
+    data.writeUInt8(12, 0);
+    data.writeBigUInt64LE(amount, 1);
+    data.writeUInt8(decimals, 9);
+    return new TransactionInstruction({
+        programId: tokenProgram,
+        keys: [
+            { pubkey: source, isSigner: false, isWritable: true },
+            { pubkey: mint, isSigner: false, isWritable: false },
+            { pubkey: dest, isSigner: false, isWritable: true },
+            { pubkey: owner, isSigner: true, isWritable: false },
+        ],
+        data,
+    });
+}
+/** Associated token account create, idempotent variant (opcode 1). */
+function createAtaIdempotentIx(payer, ata, owner, mint, tokenProgram) {
+    return new TransactionInstruction({
+        programId: ASSOCIATED_TOKEN_PROGRAM,
+        keys: [
+            { pubkey: payer, isSigner: true, isWritable: true },
+            { pubkey: ata, isSigner: false, isWritable: true },
+            { pubkey: owner, isSigner: false, isWritable: false },
+            { pubkey: mint, isSigner: false, isWritable: false },
+            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+            { pubkey: tokenProgram, isSigner: false, isWritable: false },
+        ],
+        data: Buffer.from([1]),
+    });
+}
+/**
+ * Transfer SPL tokens. The recipient's associated account is created if it does
+ * not exist, using the idempotent instruction so a race cannot fail the send.
+ */
+export async function localSplTransfer(mintStr, to, rawAmount, decimals, chainId = 900) {
+    const conn = connection(chainId);
+    const payer = getSolanaKeypair();
+    const mint = new PublicKey(mintStr);
+    const recipient = new PublicKey(to);
+    const tokenProgram = await tokenProgramFor(conn, mint);
+    const sourceAta = associatedTokenAddress(payer.publicKey, mint, tokenProgram);
+    const destAta = associatedTokenAddress(recipient, mint, tokenProgram);
+    const tx = new Transaction();
+    const destInfo = await conn.getAccountInfo(destAta);
+    if (!destInfo) {
+        tx.add(createAtaIdempotentIx(payer.publicKey, destAta, recipient, mint, tokenProgram));
+    }
+    tx.add(transferCheckedIx(tokenProgram, sourceAta, mint, destAta, payer.publicKey, BigInt(rawAmount), decimals));
+    const signature = await sendAndConfirmTransaction(conn, tx, [payer]);
+    return {
+        signature,
+        from: payer.publicKey.toBase58(),
+        to,
+        value: rawAmount,
+        chain_id: chainId,
+        mode: 'local',
+        signed_locally: true,
+    };
+}
+export function solanaWalletRecord() {
+    return {
+        id: 'local-solana',
+        address: getSolanaAddress(),
+        wallet_type: 'solana',
+        mode: 'local',
+        custody: 'self',
+        note: 'Signed in-process. The secret key is never sent to AgentWallet servers.',
+    };
+}

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/package.json

@@ -1,8 +1,8 @@
 {
   "name": "agentwallet-mcp",
   "mcpName": "io.github.hifriendbot/agentwallet",
-  "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",
+  "version": "1.10.0",
+  "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",
   "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,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.11.4",
+    "@solana/web3.js": "^1.98.4",
+    "bs58": "^6.0.0",
+    "viem": "^2.55.10",
     "zod": "^3.24.0"
   },
   "devDependencies": {