agentwallet-mcp 1.7.1 → 1.7.3

package/README.md

@@ -1,8 +1,8 @@
 # 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.
+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.
 
-**No KYC. No KYT. No approval process. No transaction monitoring. No one can block your wallet.**
+**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.**
 
 <p align="center">
   <img src="assets/demo.svg" alt="AgentWallet demo — AI agent pays x402 invoice automatically" width="800">
@@ -10,7 +10,7 @@ Permissionless wallet infrastructure for AI agents. Create wallets, sign transac
 
 ## Features
 
-- **28 MCP tools** — create wallets, send transactions, approve tokens, wrap ETH, transfer SPL tokens, pay and accept x402 payments, and more
+- **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
@@ -25,6 +25,7 @@ Permissionless wallet infrastructure for AI agents. Create wallets, sign transac
 - **6,000 free operations/month**
 - **$0.0005 per x402 verification** (50% less expensive than Coinbase)
 - **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
 
 ## Quick Start
@@ -43,19 +44,23 @@ Add to your config:
       "args": ["-y", "agentwallet-mcp"],
       "env": {
         "AGENTWALLET_USER": "your_username",
-        "AGENTWALLET_PASS": "your_api_key"
+        "AGENTWALLET_PASS": "your_api_key",
+        "AGENTWALLET_WALLET_ID": "1"
       }
     }
   }
 }
 ```
 
+> `AGENTWALLET_WALLET_ID` is optional. Set it to enable x402 auto-pay — when you exceed the free tier without a credit card, the MCP server will automatically pay for operations with USDC from this wallet.
+
 ### Claude Code
 
 ```bash
 claude mcp add agentwallet \
   -e AGENTWALLET_USER=your_username \
   -e AGENTWALLET_PASS=your_api_key \
+  -e AGENTWALLET_WALLET_ID=1 \
   -- npx -y agentwallet-mcp
 ```
 
@@ -72,7 +77,8 @@ Add to your settings:
         "args": ["-y", "agentwallet-mcp"],
         "env": {
           "AGENTWALLET_USER": "your_username",
-          "AGENTWALLET_PASS": "your_api_key"
+          "AGENTWALLET_PASS": "your_api_key",
+          "AGENTWALLET_WALLET_ID": "1"
         }
       }
     }
@@ -107,6 +113,7 @@ 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 |
+| `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 |
 | `pause_wallet` | Emergency pause a wallet |
@@ -200,9 +207,20 @@ On-chain verification ensures every payment is real. Replay protection prevents
 | Free Operations / Month | 5,000 | **6,000** |
 | Cost Per Operation | $0.005 | **$0.00345** |
 | x402 Verification Cost | $0.001 | **$0.0005** |
+| Free x402 Verifications / Month | 1,000 | **1,000** |
 | x402 Acceptance (Paywalls) | No | **Yes** |
+| Pay for API Fees with Crypto | No (credit card only) | **Yes (USDC via x402)** |
 | Supported Chains | 8 EVM + Solana | **Any EVM + Solana** |
-| Token Tools | Yes | **ERC-20 + SPL (28 tools)** |
+| Token Tools | Yes | **ERC-20 + SPL (29 tools)** |
+| MCP Server | Yes | **Yes** |
+
+## 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.
+
+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.
 
 ## Built-in Guards
 

package/build/index.js

@@ -16,13 +16,17 @@ import { z } from 'zod';
 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
-// ─── API Helper ─────────────────────────────────────────────────
-async function api(path, method = 'GET', body) {
+const X402_WALLET_ID = process.env.AGENTWALLET_WALLET_ID || ''; // Wallet ID for x402 auto-pay
+/**
+ * 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) {
     const url = `${API_BASE}${path}`;
     const headers = {
         'Content-Type': 'application/json',
+        ...extraHeaders,
     };
-    // Add basic auth if credentials provided
     if (API_USER && API_PASS) {
         headers['Authorization'] = 'Basic ' + Buffer.from(`${API_USER}:${API_PASS}`).toString('base64');
     }
@@ -32,12 +36,80 @@ async function api(path, method = 'GET', body) {
     }
     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']) {
+        return handleX402Payment(data, path, method, body);
+    }
     if (!res.ok) {
         const error = data.error || `HTTP ${res.status}`;
         throw new Error(error);
     }
     return data;
 }
+/**
+ * Handle x402 auto-payment: pay on-chain, then retry the original request
+ */
+async function handleX402Payment(x402Data, originalPath, originalMethod, originalBody) {
+    const accepts = x402Data.accepts;
+    if (!accepts || accepts.length === 0) {
+        throw new Error('402 Payment Required but no payment options available.');
+    }
+    const accept = accepts[0]; // Use first option
+    const tokenAddress = accept.extra?.token || '';
+    const amount = accept.maxAmountRequired;
+    const payTo = accept.payTo;
+    const decimals = accept.requiredDecimals || 6;
+    // Determine chain_id from network string (CAIP-2, plain name, or raw ID)
+    const network = accept.network || '';
+    const chainId = resolveChainId(network) ?? 8453;
+    // Convert human-readable amount to raw (e.g. "0.01" with 6 decimals = "10000")
+    const rawAmount = parseUnits(amount, decimals);
+    // Send payment using our wallet (with X-AGW-SKIP-X402 to prevent recursion)
+    let txHash;
+    try {
+        if (tokenAddress) {
+            // ERC-20/SPL token transfer
+            const isSOL = isSolanaChain(chainId);
+            const sendResult = await api(`/wallets/${X402_WALLET_ID}/send`, 'POST', isSOL
+                ? { chain_id: chainId, to: payTo, value: rawAmount, token_mint: tokenAddress, token_decimals: decimals }
+                : { chain_id: chainId, to: tokenAddress, value: '0', data: buildErc20TransferData(payTo, rawAmount) }, { 'X-AGW-SKIP-X402': 'true' });
+            txHash = sendResult.tx_hash || sendResult.signature || '';
+        }
+        else {
+            // Native transfer
+            const sendResult = await api(`/wallets/${X402_WALLET_ID}/send`, 'POST', { chain_id: chainId, to: payTo, value: rawAmount }, { 'X-AGW-SKIP-X402': 'true' });
+            txHash = sendResult.tx_hash || sendResult.signature || '';
+        }
+    }
+    catch (e) {
+        throw new Error(`x402 auto-pay failed: ${e.message}. Original error: ${x402Data.error}`);
+    }
+    if (!txHash) {
+        throw new Error('x402 auto-pay: no transaction hash returned.');
+    }
+    // Build X-PAYMENT header (base64-encoded JSON proof)
+    const proof = {
+        x402Version: 1,
+        scheme: 'exact',
+        network: network,
+        payload: { txHash },
+    };
+    const paymentHeader = Buffer.from(JSON.stringify(proof)).toString('base64');
+    // Wait briefly for tx confirmation (EVM ~2s, Solana ~6s)
+    const waitMs = isSolanaChain(chainId) ? 8000 : 3000;
+    await new Promise(resolve => setTimeout(resolve, waitMs));
+    // Retry original request with payment proof
+    return api(originalPath, originalMethod, originalBody, { 'X-PAYMENT': paymentHeader });
+}
+/**
+ * Build ERC-20 transfer(address,uint256) calldata
+ */
+function buildErc20TransferData(to, amount) {
+    // transfer(address,uint256) selector = 0xa9059cbb
+    const addressPadded = to.slice(2).toLowerCase().padStart(64, '0');
+    const amountHex = BigInt(amount).toString(16).padStart(64, '0');
+    return '0xa9059cbb' + addressPadded + amountHex;
+}
 function jsonResponse(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
@@ -144,7 +216,83 @@ function resolveChainId(network) {
 // ─── Server ──────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'agentwallet',
-    version: '1.7.0',
+    version: '1.7.2',
+}, {
+    instructions: `AgentWallet gives AI agents their own blockchain wallets. Private keys are encrypted server-side and never exposed — agents sign and broadcast transactions without ever touching raw keys.
+
+## Getting Started
+1. Call list_wallets to see existing wallets, or create_wallet to make a new one.
+2. Fund the wallet by sending tokens to its address from an external source.
+3. Use transfer (native tokens) or transfer_token (ERC-20/SPL tokens) to send funds.
+
+## Supported Chains
+- **EVM chains:** Ethereum (1), Base (8453), Arbitrum (42161), Optimism (10), Polygon (137), Avalanche (43114), BSC (56), Zora (7777777), PulseChain (369)
+- **Solana:** Mainnet (900), Devnet (901)
+- Call get_chains for the full list with native tokens and stablecoin contract addresses.
+
+## EVM vs Solana
+- **Addresses:** EVM uses 0x-prefixed hex (42 chars). Solana uses Base58 (32-44 chars).
+- **Native tokens:** EVM = ETH/POL/BNB/etc (18 decimals, wei). Solana = SOL (9 decimals, lamports).
+- **Token standards:** EVM uses ERC-20. Solana uses SPL tokens.
+- **EVM-only tools:** approve_token, get_allowance, wrap_eth, unwrap_eth, call_contract, get_token_info. These do not work on Solana.
+- **Works on both:** create_wallet, transfer, transfer_token, send_transaction, sign_transaction, get_balance, get_token_balance.
+
+## Common Workflows
+
+### Send native tokens (ETH, SOL, etc.)
+Use the transfer tool with a human-readable amount (e.g. "0.1" ETH). It auto-converts to wei/lamports.
+
+### Send ERC-20 or SPL tokens
+Use transfer_token. You need: wallet_id, token contract address, recipient, amount, chain_id, and decimals (6 for USDC, 18 for most ERC-20s). Call get_chains to find stablecoin addresses.
+
+### Interact with DeFi (EVM only)
+1. Check allowance with get_allowance.
+2. If needed, call approve_token to let the DeFi contract spend your tokens.
+3. Use send_transaction with the contract's calldata to execute the interaction.
+
+### Wrap/unwrap native tokens (EVM only)
+Use wrap_eth to convert ETH → WETH (required by many DeFi protocols). Use unwrap_eth to convert back.
+
+### Read on-chain data (EVM only)
+Use call_contract for gas-free read-only calls (eth_call). Provide ABI-encoded calldata.
+
+## x402 Payments — Paying for Resources
+The pay_x402 tool handles the full x402 payment flow automatically:
+1. Fetches the URL.
+2. If the server returns HTTP 402, parses the payment requirements.
+3. Pays on-chain using your wallet.
+4. Retries the request with proof of payment.
+Always set max_payment to prevent overspending (e.g. "1.00" for max 1 USDC).
+
+## x402 Paywalls — Accepting Payments
+Create paywalls to charge other agents for accessing your resources:
+1. create_paywall — set price, token, chain, and the resource URL to protect.
+2. Share the access URL. Clients that pay on-chain get the resource; others get HTTP 402.
+3. list_paywalls and get_paywall_payments to track revenue.
+4. get_x402_revenue for aggregate stats across all paywalls.
+
+## Wallet Security
+- Use pause_wallet to immediately freeze a wallet if compromised. No transactions can be signed while paused.
+- Use unpause_wallet to resume operations.
+- Use delete_wallet to permanently disable a wallet.
+- Wallets have server-enforced spending limits.
+
+## Tool Selection Guide
+| Goal | Tool |
+|------|------|
+| Send ETH/SOL/native tokens | transfer |
+| Send USDC/ERC-20/SPL tokens | transfer_token |
+| Check native balance | get_balance |
+| Check token balance | get_token_balance |
+| Look up token details | get_token_info (EVM only) |
+| Approve DeFi spending | approve_token (EVM only) |
+| Check approval amount | get_allowance (EVM only) |
+| Read smart contract | call_contract (EVM only) |
+| Custom transaction | send_transaction |
+| Sign without broadcasting | sign_transaction |
+| Pay for x402 resource | pay_x402 |
+| Charge for your resource | create_paywall |
+| Check usage/billing | get_usage |`,
 });
 // ─── Tool: create_wallet ─────────────────────────────────────────
 server.tool('create_wallet', 'Create a new EVM or Solana wallet. Returns the wallet ID and address. ' +
@@ -615,8 +763,8 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
     if (blockedHosts.includes(hostname) || blockedPrefixes.some(p => hostname.startsWith(p))) {
         throw new Error('URL points to a private/internal address. Only public URLs are allowed.');
     }
-    if (!['http:', 'https:'].includes(urlObj.protocol)) {
-        throw new Error('Only http: and https: URLs are supported.');
+    if (urlObj.protocol !== 'https:') {
+        throw new Error('Only HTTPS URLs are supported for x402 payments.');
     }
     // Step 1: Make initial request
     const reqOptions = {
@@ -783,6 +931,17 @@ server.tool('get_usage', 'Get the current month\'s usage statistics. ' +
     const data = await api('/usage');
     return jsonResponse(data);
 });
+// ─── Tool: buy_verification_credits ─────────────────────────────
+server.tool('buy_verification_credits', 'Buy x402 verification credits with USDC on-chain. ' +
+    'Paywall owners need credits to process verifications beyond the free tier (1,000/month) ' +
+    'when they don\'t have Stripe billing configured. ' +
+    'Returns 402 payment instructions — pay on-chain and retry with proof.', {
+    count: z.number().int().min(100).default(1000)
+        .describe('Number of verification credits to purchase (min 100, default 1000)'),
+}, async ({ count }) => {
+    const data = await api('/billing/verification-credits', 'POST', { count });
+    return jsonResponse(data);
+});
 // ─── Tool: pause_wallet ──────────────────────────────────────────
 server.tool('pause_wallet', 'Emergency pause a wallet. No transactions can be signed while paused.', {
     wallet_id: z.number().int().describe('Wallet ID to pause'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwallet-mcp",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "MCP server for AgentWallet — lets AI agents create wallets, sign transactions, broadcast on EVM + Solana, pay x402 invoices, and accept x402 payments",
   "type": "module",
   "main": "build/index.js",