agentwallet-mcp 1.0.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

@@ -41,16 +41,83 @@ async function api(path, method = 'GET', body) {
 function jsonResponse(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
+// ─── EVM Helpers ──────────────────────────────────────────────────
+/**
+ * Convert a human-readable amount (e.g. "0.1") to raw units string given decimals.
+ * Uses BigInt for precision — no floating-point errors.
+ */
+function parseUnits(amount, decimals) {
+    if (!/^\d+(\.\d+)?$/.test(amount)) {
+        throw new Error(`Invalid amount "${amount}". Must be a positive number (e.g. "0.1" or "100").`);
+    }
+    const [whole, frac = ''] = amount.split('.');
+    const fracPadded = frac.slice(0, decimals).padEnd(decimals, '0');
+    const raw = BigInt(whole + fracPadded);
+    return raw.toString();
+}
+/**
+ * Format raw units to human-readable string given decimals.
+ */
+function formatUnits(raw, decimals) {
+    const padded = raw.padStart(decimals + 1, '0');
+    const whole = padded.slice(0, padded.length - decimals) || '0';
+    const frac = padded.slice(padded.length - decimals);
+    // Trim trailing zeros but keep at least one decimal
+    const trimmed = frac.replace(/0+$/, '') || '0';
+    return `${whole}.${trimmed}`;
+}
+/**
+ * Pad an address to 32 bytes (64 hex chars) for ABI encoding.
+ */
+function padAddress(address) {
+    return address.slice(2).toLowerCase().padStart(64, '0');
+}
+/**
+ * Encode a uint256 as 32 bytes hex (64 chars).
+ */
+function encodeUint256(value) {
+    const hex = BigInt(value).toString(16);
+    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.0.0',
+    version: '1.3.0',
 });
 // ─── Tool: create_wallet ─────────────────────────────────────────
 server.tool('create_wallet', 'Create a new EVM wallet. Returns the wallet ID and address. ' +
     'Private key is encrypted server-side and never exposed.', {
     label: z.string().default('').describe('Friendly name for the wallet'),
-    chain_id: z.number().int().default(1).describe('Default chain ID (1=Ethereum, 8453=Base, 137=Polygon, 56=BSC, 369=PulseChain)'),
+    chain_id: z.number().int().default(8453).describe('Default chain ID (1=Ethereum, 8453=Base, 42161=Arbitrum, 10=Optimism, 137=Polygon, 43114=Avalanche, 56=BSC, 7777777=Zora, 369=PulseChain)'),
 }, async ({ label, chain_id }) => {
     const data = await api('/wallets', 'POST', { label, chain_id });
     return jsonResponse(data);
@@ -129,6 +196,439 @@ server.tool('send_transaction', 'Sign and broadcast an EVM transaction. ' +
     const result = await api(`/wallets/${wallet_id}/send`, 'POST', body);
     return jsonResponse(result);
 });
+// ─── Tool: transfer ─────────────────────────────────────────────
+server.tool('transfer', 'Send native tokens (ETH, AVAX, BNB, POL, PLS) to an address. ' +
+    'Specify the amount in human-readable format (e.g. "0.1" for 0.1 ETH). ' +
+    'The amount is converted to wei automatically. Signs and broadcasts the transaction.', {
+    wallet_id: z.number().int().describe('Wallet ID to send from'),
+    to: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('Destination address'),
+    amount: z.string().describe('Amount to send in human-readable format (e.g. "0.1" for 0.1 ETH)'),
+    chain_id: z.number().int().describe('Chain ID (1=Ethereum, 8453=Base, 42161=Arbitrum, 10=Optimism, 137=Polygon, 43114=Avalanche, 56=BSC, 7777777=Zora, 369=PulseChain)'),
+}, async ({ wallet_id, to, amount, chain_id }) => {
+    // Convert human-readable to wei (18 decimals for all native tokens)
+    const valueWei = parseUnits(amount, 18);
+    const result = await api(`/wallets/${wallet_id}/send`, 'POST', {
+        to,
+        value: valueWei,
+        chain_id,
+        data: '',
+    });
+    return jsonResponse({
+        ...result,
+        amount,
+        chain_id,
+    });
+});
+// ─── Tool: get_token_balance ────────────────────────────────────
+server.tool('get_token_balance', 'Get the ERC-20 token balance for a wallet on a specific chain. ' +
+    'Returns the raw balance and human-readable balance. ' +
+    'Use get_chains to find stablecoin addresses for each chain.', {
+    wallet_id: z.number().int().describe('Wallet ID to check'),
+    token: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('ERC-20 token contract address'),
+    chain_id: z.number().int().describe('Chain ID to check on'),
+    decimals: z.number().int().default(18).describe('Token decimals (6 for USDC, 18 for most tokens)'),
+}, async ({ wallet_id, token, chain_id, decimals }) => {
+    const params = `?chain_id=${chain_id}&token=${token}`;
+    const data = await api(`/wallets/${wallet_id}/token-balance${params}`);
+    const balanceFormatted = formatUnits(data.balance_raw, decimals);
+    return jsonResponse({
+        ...data,
+        balance: balanceFormatted,
+        decimals,
+    });
+});
+// ─── Tool: transfer_token ───────────────────────────────────────
+server.tool('transfer_token', 'Send ERC-20 tokens (USDC, USDT, etc.) to an address. ' +
+    'Specify the amount in human-readable format (e.g. "100" for 100 USDC). ' +
+    'Signs and broadcasts the transaction. Use get_chains to find stablecoin addresses.', {
+    wallet_id: z.number().int().describe('Wallet ID to send from'),
+    token: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('ERC-20 token contract address'),
+    to: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('Recipient address'),
+    amount: z.string().describe('Amount in human-readable format (e.g. "100" for 100 USDC)'),
+    chain_id: z.number().int().describe('Chain ID'),
+    decimals: z.number().int().default(18).describe('Token decimals (6 for USDC, 18 for most tokens)'),
+}, async ({ wallet_id, token, to, amount, chain_id, decimals }) => {
+    // Encode ERC-20 transfer(address, uint256) calldata
+    const rawAmount = parseUnits(amount, decimals);
+    const calldata = '0xa9059cbb' + padAddress(to) + encodeUint256(rawAmount);
+    const result = await api(`/wallets/${wallet_id}/send`, 'POST', {
+        to: token, // Send TX to the token contract
+        value: '0', // No native value for token transfers
+        data: calldata,
+        chain_id,
+    });
+    return jsonResponse({
+        ...result,
+        token,
+        recipient: to,
+        amount,
+        decimals,
+    });
+});
+// ─── Tool: call_contract ────────────────────────────────────────
+server.tool('call_contract', 'Execute a read-only call against a smart contract (eth_call). ' +
+    'Returns the raw hex result. Does not cost gas or modify state. ' +
+    'Useful for reading on-chain data like token balances, prices, positions.', {
+    chain_id: z.number().int().describe('Chain ID'),
+    to: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('Contract address'),
+    data: z.string().describe('ABI-encoded calldata (0x-prefixed hex)'),
+}, async ({ chain_id, to, data }) => {
+    const result = await api('/eth-call', 'POST', { chain_id, to, data });
+    return jsonResponse(result);
+});
+// ─── Tool: approve_token ────────────────────────────────────────
+server.tool('approve_token', 'Approve a spender contract to transfer ERC-20 tokens on your behalf. ' +
+    'Required before interacting with any DeFi protocol (DEXs, lending, etc.). ' +
+    'Use amount "max" for unlimited approval, or specify an exact amount.', {
+    wallet_id: z.number().int().describe('Wallet ID'),
+    token: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('ERC-20 token contract address'),
+    spender: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('Contract address to approve as spender'),
+    amount: z.string().describe('Amount to approve in human-readable format (e.g. "1000"), or "max" for unlimited'),
+    chain_id: z.number().int().describe('Chain ID'),
+    decimals: z.number().int().default(18).describe('Token decimals (6 for USDC, 18 for most tokens)'),
+}, async ({ wallet_id, token, spender, amount, chain_id, decimals }) => {
+    // approve(address spender, uint256 amount) — selector: 0x095ea7b3
+    let rawAmount;
+    if (amount.toLowerCase() === 'max') {
+        rawAmount = (BigInt(2) ** BigInt(256) - BigInt(1)).toString();
+    }
+    else {
+        rawAmount = parseUnits(amount, decimals);
+    }
+    const calldata = '0x095ea7b3' + padAddress(spender) + encodeUint256(rawAmount);
+    const result = await api(`/wallets/${wallet_id}/send`, 'POST', {
+        to: token,
+        value: '0',
+        data: calldata,
+        chain_id,
+    });
+    return jsonResponse({
+        ...result,
+        token,
+        spender,
+        amount: amount.toLowerCase() === 'max' ? 'unlimited' : amount,
+    });
+});
+// ─── Tool: get_allowance ────────────────────────────────────────
+server.tool('get_allowance', 'Check how many ERC-20 tokens a spender is approved to transfer. ' +
+    'Returns the allowance in both raw and human-readable format. ' +
+    'Use this to check if an approval is needed before a DeFi transaction.', {
+    wallet_id: z.number().int().describe('Wallet ID (used to determine the owner address)'),
+    token: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('ERC-20 token contract address'),
+    spender: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('Spender contract address to check'),
+    chain_id: z.number().int().describe('Chain ID'),
+    decimals: z.number().int().default(18).describe('Token decimals (6 for USDC, 18 for most tokens)'),
+}, async ({ wallet_id, token, spender, chain_id, decimals }) => {
+    // First get the wallet address
+    const wallet = await api(`/wallets/${wallet_id}`);
+    // allowance(address owner, address spender) — selector: 0xdd62ed3e
+    const calldata = '0xdd62ed3e' + padAddress(wallet.address) + padAddress(spender);
+    const result = await api('/eth-call', 'POST', { chain_id, to: token, data: calldata });
+    // Parse uint256 result
+    const rawHex = result.result.replace('0x', '');
+    const raw = BigInt('0x' + (rawHex || '0')).toString();
+    const maxUint256 = (BigInt(2) ** BigInt(256) - BigInt(1)).toString();
+    return jsonResponse({
+        token,
+        spender,
+        allowance_raw: raw,
+        allowance: raw === maxUint256 ? 'unlimited' : formatUnits(raw, decimals),
+        is_unlimited: raw === maxUint256,
+        decimals,
+    });
+});
+// ─── WETH / Wrapped Native Token addresses ──────────────────────
+const WRAPPED_NATIVE = {
+    1: { address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', symbol: 'WETH' },
+    8453: { address: '0x4200000000000000000000000000000000000006', symbol: 'WETH' },
+    42161: { address: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1', symbol: 'WETH' },
+    10: { address: '0x4200000000000000000000000000000000000006', symbol: 'WETH' },
+    137: { address: '0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270', symbol: 'WPOL' },
+    56: { address: '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c', symbol: 'WBNB' },
+    43114: { address: '0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7', symbol: 'WAVAX' },
+    7777777: { address: '0x4200000000000000000000000000000000000006', symbol: 'WETH' },
+    369: { address: '0xA1077a294dDE1B09bB078844df40758a5D0f9a27', symbol: 'WPLS' },
+};
+// ─── Tool: wrap_eth ─────────────────────────────────────────────
+server.tool('wrap_eth', 'Wrap native tokens (ETH, AVAX, BNB, POL, PLS) into their wrapped ERC-20 version (WETH, WAVAX, etc.). ' +
+    'Required for most DeFi protocols that use ERC-20 tokens instead of raw native tokens. ' +
+    'Specify amount in human-readable format (e.g. "0.5" for 0.5 ETH).', {
+    wallet_id: z.number().int().describe('Wallet ID'),
+    amount: z.string().describe('Amount to wrap in human-readable format (e.g. "0.5")'),
+    chain_id: z.number().int().describe('Chain ID'),
+}, async ({ wallet_id, amount, chain_id }) => {
+    const wrapped = WRAPPED_NATIVE[chain_id];
+    if (!wrapped) {
+        throw new Error(`No wrapped native token configured for chain ${chain_id}`);
+    }
+    // WETH deposit() payable — selector: 0xd0e30db0
+    const valueWei = parseUnits(amount, 18);
+    const result = await api(`/wallets/${wallet_id}/send`, 'POST', {
+        to: wrapped.address,
+        value: valueWei,
+        data: '0xd0e30db0',
+        chain_id,
+    });
+    return jsonResponse({
+        ...result,
+        wrapped_token: wrapped.symbol,
+        wrapped_address: wrapped.address,
+        amount,
+    });
+});
+// ─── Tool: unwrap_eth ───────────────────────────────────────────
+server.tool('unwrap_eth', 'Unwrap wrapped tokens (WETH, WAVAX, WBNB, etc.) back to native tokens. ' +
+    'Specify amount in human-readable format (e.g. "0.5" for 0.5 WETH).', {
+    wallet_id: z.number().int().describe('Wallet ID'),
+    amount: z.string().describe('Amount to unwrap in human-readable format (e.g. "0.5")'),
+    chain_id: z.number().int().describe('Chain ID'),
+}, async ({ wallet_id, amount, chain_id }) => {
+    const wrapped = WRAPPED_NATIVE[chain_id];
+    if (!wrapped) {
+        throw new Error(`No wrapped native token configured for chain ${chain_id}`);
+    }
+    // WETH withdraw(uint256) — selector: 0x2e1a7d4d
+    const rawAmount = parseUnits(amount, 18);
+    const calldata = '0x2e1a7d4d' + encodeUint256(rawAmount);
+    const result = await api(`/wallets/${wallet_id}/send`, 'POST', {
+        to: wrapped.address,
+        value: '0',
+        data: calldata,
+        chain_id,
+    });
+    return jsonResponse({
+        ...result,
+        unwrapped_token: wrapped.symbol,
+        amount,
+    });
+});
+// ─── Tool: get_token_info ───────────────────────────────────────
+/**
+ * Decode an ABI-encoded string return value from hex.
+ * Handles malformed data gracefully — returns empty string on any parsing failure.
+ */
+function decodeAbiString(hex) {
+    try {
+        const clean = hex.replace('0x', '');
+        if (clean.length < 128)
+            return ''; // offset + length minimum
+        // First 32 bytes = offset, next 32 bytes at that offset = length
+        const offset = parseInt(clean.slice(0, 64), 16) * 2;
+        if (isNaN(offset) || offset + 64 > clean.length)
+            return '';
+        const length = parseInt(clean.slice(offset, offset + 64), 16);
+        if (isNaN(length) || length === 0)
+            return '';
+        const dataHex = clean.slice(offset + 64, offset + 64 + length * 2);
+        const pairs = dataHex.match(/.{2}/g);
+        if (!pairs)
+            return '';
+        // Convert hex to UTF-8
+        const bytes = new Uint8Array(pairs.map(b => parseInt(b, 16)));
+        return new TextDecoder().decode(bytes);
+    }
+    catch {
+        return '';
+    }
+}
+server.tool('get_token_info', 'Get the name, symbol, and decimals of any ERC-20 token by its contract address. ' +
+    'Useful for discovering token details before transfers or approvals.', {
+    token: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('ERC-20 token contract address'),
+    chain_id: z.number().int().describe('Chain ID'),
+}, async ({ token, chain_id }) => {
+    // Make 3 parallel eth_call requests: name(), symbol(), decimals()
+    const [nameResult, symbolResult, decimalsResult] = await Promise.all([
+        api('/eth-call', 'POST', { chain_id, to: token, data: '0x06fdde03' }).catch(() => ({ result: '0x' })),
+        api('/eth-call', 'POST', { chain_id, to: token, data: '0x95d89b41' }).catch(() => ({ result: '0x' })),
+        api('/eth-call', 'POST', { chain_id, to: token, data: '0x313ce567' }).catch(() => ({ result: '0x' })),
+    ]);
+    const name = decodeAbiString(nameResult.result);
+    const symbol = decodeAbiString(symbolResult.result);
+    const decimalsHex = decimalsResult.result.replace('0x', '');
+    const decimals = decimalsHex ? parseInt(decimalsHex, 16) : 0;
+    return jsonResponse({
+        token,
+        chain_id,
+        name: name || 'Unknown',
+        symbol: symbol || 'Unknown',
+        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.0.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": {
@@ -26,10 +26,19 @@
     "evm",
     "ethereum",
     "base",
+    "arbitrum",
+    "optimism",
     "polygon",
+    "avalanche",
     "bsc",
+    "zora",
     "pulsechain",
+    "erc20",
+    "token-transfer",
     "transaction-signing",
+    "x402",
+    "http-402",
+    "agent-payments",
     "agentwallet"
   ],
   "author": "HiFriendbot (https://hifriendbot.com)",