agentwallet-mcp 1.9.0 → 1.10.0

package/README.md

@@ -4,7 +4,7 @@ Permissionless wallet infrastructure for AI agents. Create wallets, sign transac
 
 **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.**
+**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
 
@@ -12,9 +12,9 @@ Permissionless wallet infrastructure for AI agents. Create wallets, sign transac
 |---|---|---|
 | 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 |
+| 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_AUTOPAY` | Server-side limits, pause, rate limits |
+| 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.
@@ -43,35 +43,57 @@ Use `AGENTWALLET_KEYFILE=/path/to/key` instead if you would rather keep the key
 
 `AGENTWALLET_MAX_TX_NATIVE` is a per-transaction ceiling in native units. 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.
+### 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
 
-- **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.
+- **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% under Coinbase CDP list pricing, checked 2026-07-29)
+- **$0.00345 per operation**
 - **6,000 free operations/month**
-- **$0.0005 per x402 verification** (50% under Coinbase, checked 2026-07-29)
+- **$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
 
@@ -239,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% under Coinbase as of 2026-07-29.
+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** |
@@ -261,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

@@ -14,6 +14,11 @@ 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 || '';
@@ -38,21 +43,43 @@ function localChainId(body, qs) {
         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.');
+/**
+ * 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)) {
-        if (body?.token_mint)
-            refuseSolanaLocally();
         const chainId = localChainId(body, qs);
-        if (SOLANA_CHAIN_IDS.has(chainId))
-            refuseSolanaLocally();
+        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 || '');
@@ -65,16 +92,27 @@ async function routeLocally(path, method, body) {
     // GET /wallets/{id}/balance
     if (method === 'GET' && /^\/wallets\/[^/]*\/balance$/.test(rawPath)) {
         const chainId = localChainId(body, qs);
-        if (SOLANA_CHAIN_IDS.has(chainId))
-            refuseSolanaLocally();
+        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);
-        if (SOLANA_CHAIN_IDS.has(chainId))
-            refuseSolanaLocally();
-        const token = qs.get('token') || qs.get('token_address') || '';
+        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}".`);
         }
@@ -88,11 +126,18 @@ async function routeLocally(path, method, body) {
         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();
+    // 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 ' +
@@ -112,7 +157,7 @@ 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()) {
+    if (anyLocalMode()) {
         const handled = await routeLocally(path, method, body);
         if (handled !== NOT_HANDLED)
             return handled;
@@ -132,7 +177,7 @@ 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 a wallet or a local key is configured
-    if (res.status === 402 && (X402_WALLET_ID || isLocalMode()) && !extraHeaders?.['X-PAYMENT']) {
+    if (res.status === 402 && (X402_WALLET_ID || anyLocalMode()) && !extraHeaders?.['X-PAYMENT']) {
         return handleX402Payment(data, path, method, body);
     }
     if (!res.ok) {
@@ -1193,31 +1238,53 @@ server.tool('get_x402_revenue', 'Get aggregate x402 revenue statistics across al
 // ─── 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()) {
+    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 (or AGENTWALLET_KEYFILE) and restart. ' +
+            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.',
         });
     }
-    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({
+    const report = {
         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',
+        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 ' +
@@ -1225,12 +1292,12 @@ server.tool('export_wallet_key', 'Explain how to export the private key of a hos
     'performed by this tool.', {
     wallet_id: z.number().int().optional().describe('Hosted wallet ID to export'),
 }, async ({ wallet_id }) => {
-    if (isLocalMode()) {
+    if (anyLocalMode()) {
         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.',
+            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({
@@ -1252,12 +1319,17 @@ async function main() {
     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()) {
+    if (anyLocalMode()) {
         try {
-            console.error(`AgentWallet MCP: LOCAL signing mode. Address ${getLocalAddress()}. Key never leaves this machine.`);
+            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 the key could not be loaded: ${e.message}`);
+            console.error(`AgentWallet MCP: local signing configured but a key could not be loaded: ${e.message}`);
             process.exit(1);
         }
     }

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

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