agentwallet-mcp 1.2.0 → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HiFriendbot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# AgentWallet MCP Server
+
+Permissionless EVM wallet infrastructure for AI agents. Create wallets, sign transactions, and broadcast on-chain — on any EVM chain.
+
+**No KYC. No KYT. No transaction monitoring. No one can block your wallet.**
+
+## Features
+
+- **21 MCP tools** — create wallets, send transactions, approve tokens, wrap ETH, pay x402 invoices, and more
+- **Any EVM chain** — Ethereum, Base, Polygon, BSC, Arbitrum, Optimism, Avalanche, Zora, PulseChain, and any other EVM-compatible chain
+- **x402 payments** — automatically pay for x402-enabled APIs and resources on any supported chain
+- **Secure** — Private keys encrypted at rest, decrypted only during signing, zeroed from memory immediately after
+- **Permissionless** — No identity verification, no compliance gatekeeping. Create a wallet and transact immediately.
+
+## Pricing
+
+- **$0.0069 per transaction** (31% less expensive than Coinbase CDP)
+- **6,000 free transactions/month**
+- No monthly fee, no tiers — just pay as you go
+
+## Quick Start
+
+Get your free API key at [hifriendbot.com/wallet](https://hifriendbot.com/wallet) (no credit card required).
+
+### Claude Desktop / OpenClaw
+
+Add to your config:
+
+```json
+{
+  "mcpServers": {
+    "agentwallet": {
+      "command": "npx",
+      "args": ["-y", "agentwallet-mcp"],
+      "env": {
+        "AGENTWALLET_USER": "your_username",
+        "AGENTWALLET_PASS": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add agentwallet \
+  -e AGENTWALLET_USER=your_username \
+  -e AGENTWALLET_PASS=your_api_key \
+  -- npx -y agentwallet-mcp
+```
+
+### VS Code
+
+Add to your settings:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "agentwallet": {
+        "command": "npx",
+        "args": ["-y", "agentwallet-mcp"],
+        "env": {
+          "AGENTWALLET_USER": "your_username",
+          "AGENTWALLET_PASS": "your_api_key"
+        }
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_wallet` | Create a new wallet on any EVM chain |
+| `list_wallets` | List all your wallets |
+| `get_wallet` | Get wallet details by ID |
+| `get_balance` | Check native token balance on any chain |
+| `get_token_balance` | Check ERC-20 token balance |
+| `get_token_info` | Get ERC-20 token name, symbol, and decimals |
+| `transfer` | Send native tokens (ETH, POL, BNB, etc.) |
+| `transfer_token` | Send ERC-20 tokens (USDC, USDT, etc.) |
+| `send_transaction` | Sign and broadcast a raw transaction |
+| `sign_transaction` | Sign a transaction without broadcasting |
+| `call_contract` | Read-only contract call (eth_call) |
+| `approve_token` | Approve ERC-20 token spending for DeFi |
+| `get_allowance` | Check ERC-20 token allowance |
+| `wrap_eth` | Wrap native tokens to WETH/WAVAX/etc. |
+| `unwrap_eth` | Unwrap WETH back to native tokens |
+| `pay_x402` | Pay x402 invoices automatically (fetch, pay, retry) |
+| `get_usage` | Check your monthly usage and billing |
+| `get_chains` | List all supported chains |
+| `pause_wallet` | Emergency pause a wallet |
+| `unpause_wallet` | Resume a paused wallet |
+| `delete_wallet` | Delete a wallet |
+
+## Supported Chains
+
+| Chain | ID | Native Token | Stablecoin |
+|-------|-----|-------------|------------|
+| Ethereum | 1 | ETH | USDC |
+| Base | 8453 | ETH | USDC |
+| Polygon | 137 | POL | USDC |
+| BSC | 56 | BNB | USDT |
+| Arbitrum | 42161 | ETH | USDC |
+| Optimism | 10 | ETH | USDC |
+| Avalanche | 43114 | AVAX | USDC |
+| Zora | 7777777 | ETH | USDC |
+| PulseChain | 369 | PLS | USDC |
+
+## Use Case: GuessMarket
+
+Pair with [guessmarket-mcp](https://www.npmjs.com/package/guessmarket-mcp) to let your AI agent trade prediction markets:
+
+1. Create a wallet on Base
+2. Approve USDC spending
+3. Buy YES/NO shares on prediction markets
+4. Provide liquidity and earn trading fees
+5. Claim winnings
+
+All on-chain. All through MCP. No frontend needed.
+
+## x402 Payments
+
+AgentWallet natively supports the [x402 open payment standard](https://x402.org). When your Ai agent encounters an API that returns HTTP 402 Payment Required, the `pay_x402` tool handles the entire flow automatically:
+
+1. Fetches the URL and detects the 402 response
+2. Parses the payment requirements (amount, token, chain)
+3. Executes the on-chain payment from your wallet
+4. Retries the request with proof of payment
+5. Returns the final response
+
+**Always set `max_payment` to control spending:**
+
+```
+pay_x402(
+  url="https://api.example.com/premium-data",
+  wallet_id=1,
+  max_payment="1.00"
+)
+```
+
+Supports ERC-20 tokens (USDC, USDT) and native tokens on any chain. Compatible with x402 V1 and V2 (CAIP-2 chain identifiers).
+
+## Security
+
+- Private keys are generated server-side and encrypted at rest
+- Keys are decrypted only during transaction signing and zeroed from memory immediately after
+- EIP-1559 transactions only with gas safety caps
+- Emergency pause: freeze any wallet or all wallets instantly
+- Bug bounty program: $50–$500 for responsible disclosure ([details](https://hifriendbot.com/wallet))
+
+## Links
+
+- **Website:** [hifriendbot.com/wallet](https://hifriendbot.com/wallet)
+- **npm:** [agentwallet-mcp](https://www.npmjs.com/package/agentwallet-mcp)
+- **Security:** [security@hifriendbot.com](mailto:security@hifriendbot.com)
+
+## License
+
+MIT

package/build/index.js

@@ -80,9 +80,38 @@ function encodeUint256(value) {
     return hex.padStart(64, '0');
 }
 // ─── Server ──────────────────────────────────────────────────────
+// ─── x402 Network Mapping ──────────────────────────────────────
+const X402_NETWORKS = {
+    'ethereum': 1,
+    'base': 8453,
+    'base-sepolia': 84532,
+    'polygon': 137,
+    'arbitrum': 42161,
+    'optimism': 10,
+    'bsc': 56,
+    'avalanche': 43114,
+    'zora': 7777777,
+    'pulsechain': 369,
+};
+/**
+ * Resolve an x402 network identifier to a chain ID.
+ * Supports plain names ("base"), CAIP-2 format ("eip155:8453"), and raw chain IDs ("8453").
+ */
+function resolveChainId(network) {
+    if (X402_NETWORKS[network])
+        return X402_NETWORKS[network];
+    const caipMatch = network.match(/^eip155:(\d+)$/);
+    if (caipMatch)
+        return parseInt(caipMatch[1], 10);
+    const num = parseInt(network, 10);
+    if (!isNaN(num) && num > 0)
+        return num;
+    return null;
+}
+// ─── Server ──────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'agentwallet',
-    version: '1.2.0',
+    version: '1.3.0',
 });
 // ─── Tool: create_wallet ─────────────────────────────────────────
 server.tool('create_wallet', 'Create a new EVM wallet. Returns the wallet ID and address. ' +
@@ -425,6 +454,181 @@ server.tool('get_token_info', 'Get the name, symbol, and decimals of any ERC-20
         decimals,
     });
 });
+// ─── Tool: pay_x402 ─────────────────────────────────────────────
+server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the server returns HTTP 402 Payment Required, ' +
+    'parses the payment requirements, executes the on-chain payment, and retries the request with ' +
+    'proof of payment. Returns the final response. Supports the x402 open payment standard ' +
+    '(https://x402.org). Set max_payment to prevent overspending.', {
+    url: z.string().url().describe('The URL to access (will handle 402 payment if required)'),
+    wallet_id: z.number().int().describe('Wallet ID to pay from'),
+    method: z.string().default('GET').describe('HTTP method (GET, POST, PUT, DELETE)'),
+    headers: z.string().optional().describe('Optional JSON string of additional request headers'),
+    body: z.string().optional().describe('Optional request body for POST/PUT requests'),
+    max_payment: z.string().optional().describe('Maximum payment in human-readable format (e.g. "1.00" for 1 USDC). ' +
+        'Rejects payments above this amount. Strongly recommended to prevent overspending.'),
+    prefer_chain: z.number().int().optional().describe('Preferred chain ID if the server accepts payment on multiple chains ' +
+        '(e.g. 8453 for Base, 1 for Ethereum)'),
+}, async ({ url, wallet_id, method, headers: headersJson, body: reqBody, max_payment, prefer_chain }) => {
+    // Build request headers
+    const reqHeaders = { Accept: 'application/json' };
+    if (headersJson) {
+        try {
+            Object.assign(reqHeaders, JSON.parse(headersJson));
+        }
+        catch {
+            throw new Error('Invalid headers JSON. Must be a JSON object (e.g. {"Authorization": "Bearer ..."}).');
+        }
+    }
+    // Validate URL — block private IPs and cloud metadata endpoints
+    const urlObj = new URL(url);
+    const hostname = urlObj.hostname.toLowerCase();
+    const blockedHosts = ['localhost', '127.0.0.1', '0.0.0.0', '[::1]', '169.254.169.254', 'metadata.google.internal'];
+    const blockedPrefixes = ['10.', '172.16.', '172.17.', '172.18.', '172.19.', '172.20.', '172.21.',
+        '172.22.', '172.23.', '172.24.', '172.25.', '172.26.', '172.27.', '172.28.', '172.29.',
+        '172.30.', '172.31.', '192.168.'];
+    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.');
+    }
+    // Step 1: Make initial request
+    const reqOptions = {
+        method,
+        headers: reqHeaders,
+        signal: AbortSignal.timeout(30_000), // 30s timeout
+    };
+    if (reqBody && method !== 'GET') {
+        reqOptions.body = reqBody;
+        if (!reqHeaders['Content-Type'])
+            reqHeaders['Content-Type'] = 'application/json';
+    }
+    const initialRes = await fetch(url, reqOptions);
+    // If not 402, return the response as-is (no payment needed)
+    if (initialRes.status !== 402) {
+        const text = await initialRes.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = text;
+        }
+        return jsonResponse({
+            status: initialRes.status,
+            payment_required: false,
+            response: parsed,
+        });
+    }
+    // Step 2: Parse x402 payment requirements from 402 response
+    let paymentInfo;
+    try {
+        paymentInfo = await initialRes.json();
+    }
+    catch {
+        throw new Error('402 response body is not valid JSON. This server may not support x402.');
+    }
+    if (!paymentInfo.accepts || paymentInfo.accepts.length === 0) {
+        throw new Error('402 response has no payment options in "accepts" array.');
+    }
+    const options = paymentInfo.accepts;
+    let option;
+    if (prefer_chain) {
+        option = options.find(a => resolveChainId(a.network) === prefer_chain) || options[0];
+    }
+    else {
+        option = options[0];
+    }
+    // Resolve the chain
+    const chainId = resolveChainId(option.network);
+    if (!chainId) {
+        throw new Error(`Unsupported x402 network: "${option.network}". ` +
+            `Supported: ${Object.keys(X402_NETWORKS).join(', ')}, or any CAIP-2 / numeric chain ID.`);
+    }
+    // Calculate human-readable amount
+    const amount = formatUnits(option.maxAmountRequired, option.requiredDecimals);
+    // Step 4: Check spending limit
+    if (max_payment) {
+        const maxRaw = parseUnits(max_payment, option.requiredDecimals);
+        if (BigInt(option.maxAmountRequired) > BigInt(maxRaw)) {
+            return jsonResponse({
+                status: 402,
+                payment_required: true,
+                payment_made: false,
+                error: `Payment of ${amount} ${option.extra?.name || 'tokens'} exceeds your max_payment limit of ${max_payment}`,
+                required_amount: amount,
+                max_allowed: max_payment,
+                token: option.extra?.name || 'native',
+                network: option.network,
+                chain_id: chainId,
+                pay_to: option.payTo,
+                description: option.description,
+            });
+        }
+    }
+    // Step 5: Execute payment
+    let txResult;
+    if (option.extra?.token) {
+        // ERC-20 token payment (e.g. USDC)
+        const calldata = '0xa9059cbb' + padAddress(option.payTo) + encodeUint256(option.maxAmountRequired);
+        txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', {
+            to: option.extra.token,
+            value: '0',
+            data: calldata,
+            chain_id: chainId,
+        }));
+    }
+    else {
+        // Native token payment (ETH, etc.)
+        txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', {
+            to: option.payTo,
+            value: option.maxAmountRequired,
+            data: '',
+            chain_id: chainId,
+        }));
+    }
+    const txHash = txResult.tx_hash;
+    // Step 6: Build x402 payment proof and retry
+    const paymentProof = {
+        x402Version: paymentInfo.x402Version || 1,
+        scheme: option.scheme,
+        network: option.network,
+        payload: { txHash },
+    };
+    const paymentHeader = Buffer.from(JSON.stringify(paymentProof)).toString('base64');
+    const retryHeaders = { ...reqHeaders, 'X-PAYMENT': paymentHeader };
+    const retryOptions = {
+        method,
+        headers: retryHeaders,
+        signal: AbortSignal.timeout(30_000),
+    };
+    if (reqBody && method !== 'GET') {
+        retryOptions.body = reqBody;
+    }
+    const retryRes = await fetch(url, retryOptions);
+    const retryText = await retryRes.text();
+    let retryParsed;
+    try {
+        retryParsed = JSON.parse(retryText);
+    }
+    catch {
+        retryParsed = retryText;
+    }
+    return jsonResponse({
+        status: retryRes.status,
+        payment_required: true,
+        payment_made: true,
+        amount,
+        token: option.extra?.name || 'native',
+        token_address: option.extra?.token || null,
+        network: option.network,
+        chain_id: chainId,
+        pay_to: option.payTo,
+        tx_hash: txHash,
+        description: option.description,
+        response: retryParsed,
+    });
+});
 // ─── Tool: get_usage ─────────────────────────────────────────────
 server.tool('get_usage', 'Get the current month\'s usage statistics. ' +
     'Returns operations count, tier info, remaining quota, and fees.', {}, async () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentwallet-mcp",
-  "version": "1.2.0",
-  "description": "MCP server for AgentWallet — lets AI agents create wallets, sign transactions, and broadcast on any EVM chain",
+  "version": "1.3.0",
+  "description": "MCP server for AgentWallet — lets AI agents create wallets, sign transactions, broadcast on any EVM chain, and pay x402 invoices",
   "type": "module",
   "main": "build/index.js",
   "bin": {
@@ -36,6 +36,9 @@
     "erc20",
     "token-transfer",
     "transaction-signing",
+    "x402",
+    "http-402",
+    "agent-payments",
     "agentwallet"
   ],
   "author": "HiFriendbot (https://hifriendbot.com)",