# MCP Wallets > Ethereum wallet operations through Model Context Protocol ## Examples Practical examples demonstrating MCP Wallet Server capabilities. These show how AI agents and applications can interact with Ethereum wallets programmatically. ### Balance Inquiry Check the ETH balance of any Ethereum address: :::code-group ```json [Request] { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "mcpwallet_get_balance", "arguments": { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } } } ``` ```json [Response] { "jsonrpc": "2.0", "id": 1, "result": { "balance": "42.0691337" } } ``` ::: :::info Balances are returned in ETH (not wei) for readability. ::: ### Transaction Execution Send ETH to another address with automatic gas estimation: :::code-group ```json [Request] { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "mcpwallet_send_transaction", "arguments": { "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "amount": "0.01" } } } ``` ```json [Expected Response] { "jsonrpc": "2.0", "id": 2, "result": { "txHash": "0x1234567890abcdef...", "status": "confirmed" } } ``` ::: :::warning Transactions are executed immediately. Ensure addresses and amounts are correct. ::: ### HTTP 402 Payment Required Access premium web content protected by HTTP 402 Payment Required responses with automatic payment processing: :::code-group ```json [Request] { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "mcpwallet_browse_with_payment", "arguments": { "url": "https://premium-content.example.com/article" } } } ``` ```json [Response] { "jsonrpc": "2.0", "id": 3, "result": { "content": "Premium article content...", "paymentProcessed": true } } ``` ::: :::info This tool automatically handles HTTP 402 Payment Required responses by processing the required payment and retrying the request. ::: ### Advanced Workflow Combine operations for complex interactions: ```json [Workflow Example] // 1. Check balance first { "method": "tools/call", "params": { "name": "mcpwallet_get_balance", "arguments": { "address": "0x..." } } } // 2. Send payment if sufficient balance { "method": "tools/call", "params": { "name": "mcpwallet_send_transaction", "arguments": { "to": "0x...", "amount": "0.1" } } } // 3. Access paid content { "method": "tools/call", "params": { "name": "mcpwallet_browse_with_payment", "arguments": { "url": "https://paid.example.com" } } } ``` :::tip These examples work with any MCP-compatible client. The server handles all Ethereum interactions transparently. ::: ## HTTP 402 Payments HTTP 402 "Payment Required" is an underutilized HTTP status code designed for programmatic payments, enabling seamless monetization of digital content for AI agents and automated systems. ### What is HTTP 402? HTTP 402 "Payment Required" is a proposed HTTP status code that allows servers to require payment before fulfilling a request. Unlike traditional paywalls requiring user interaction, 402 enables automatic payments that work with AI agents, crawlers, and APIs. :::info HTTP 402 transforms content monetization by creating economic barriers for abusive access while allowing legitimate automated systems to pay for premium resources. ::: ### How MCP Server Handles 402 Payments The MCP Wallet Server includes a `mcpwallet_browse_with_payment` tool that automatically detects 402 responses and processes payments using the integrated Ethereum wallet. #### Example Usage :::code-group ```json [Request] { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "mcpwallet_browse_with_payment", "arguments": { "url": "https://premium-api.example.com/data" } } } ``` ```json [Response] { "jsonrpc": "2.0", "id": 1, "result": { "content": "{\"premium\": \"data\"}", "paymentProcessed": true } } ``` ::: #### Payment Flow 1. **Content Request**: Agent requests paid content via MCP tool 2. **402 Detection**: Server receives 402 Payment Required response 3. **Payment Processing**: Wallet automatically sends required payment 4. **Content Access**: Request retries with payment proof, receives full content ### Benefits for Content Creators #### Aggressive Crawler Prevention Traditional rate limiting fails against distributed botnets. 402 payments create economic barriers that make mass scraping expensive while allowing legitimate users to pay. #### Flexible Monetization Set dynamic pricing based on: * Content type and quality * User/agent type * Time of access * Usage volume #### Built-in Rate Limiting Each request carries its own payment, naturally limiting abusive patterns. Economics handles rate limiting automatically. #### DDoS Protection Attackers must spend real money to overwhelm servers, creating natural economic defense. ### Payment Mechanisms The 402 protocol supports various payment methods: #### Native Ethereum ```json { "network": "eip155:1", "token": "0x0000000000000000000000000000000000000000", "recipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "amount": "1000000000000000000" } ``` #### ERC20 Tokens ```json { "network": "eip155:1", "token": "0xA0b86a33E6441e88C5F2712C3E9b74B8E5f5c4b4", "recipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "amount": "1000000" } ``` ### Real-World Applications #### Financial Data Providers Charge per query for premium market data, ensuring only serious users access. #### AI Training Data Monetize datasets for machine learning, funding better data collection. #### News and Journalism Support quality journalism directly through reader and AI payments. #### Research and Academia Monetize academic papers and research tools while keeping them accessible. ### MCP Integration The Model Context Protocol standardizes agent interaction with paid content. The `mcpwallet_browse_with_payment` tool handles payments transparently, enabling agents to: * Access real-time financial data * Use premium APIs automatically * Build applications with paid datasets * Create value-added services :::tip With MCP, agents can access paid content without custom integration for each service. ::: ### Getting Started Implement 402 payments in your service and let AI agents pay automatically. Check the [Payment Protocol](/mcp-server-payment-protocol) docs for technical details. The web is about to get a lot more valuable – one payment at a time! 🚀 ## Payment Protocol The MCP server implements a payment protocol for web browsing using HTTP 402 Payment Required responses, enabling access to paid content. ### Overview :::info HTTP 402 is a proposed status code for "Payment Required". The MCP server detects these responses and automatically processes payments using the integrated Ethereum wallet, making paid web content accessible to AI agents. ::: ### How It Works ::::steps #### Content Request The client (AI agent) requests access to a URL via the `mcpwallet_browse_with_payment` tool. #### Payment Detection If the server receives a 402 Payment Required response, it parses the payment details from the response headers or body. :::tip Payment details typically include recipient address, amount, and currency (ETH). ::: #### Payment Processing The integrated wallet automatically sends the required payment to the specified address. #### Content Retrieval With payment proof, the server retries the request and receives the full content. #### Response Delivery The paid content is returned to the client, with `paymentProcessed: true` indicating successful payment. :::: ### Consent Flow For transactions requiring explicit user consent, the server launches a local Express server on port 3000 displaying a consent UI. :::warning The consent UI allows users to review and approve/deny payments before execution, ensuring secure and transparent transactions. ::: ### Technical Details #### 402 Response Format Servers implementing 402 payments should return payment details in the `X-Payment-Required` header: ```http HTTP/1.1 402 Payment Required X-Payment-Required: {"mechanisms":[{"network":"eip155:1","token":"0x0000000000000000000000000000000000000000","recipient":"0x742d35Cc6634C0532925a3b844Bc454e4438f44e","amount":"1000000000000000000"}]} Content-Type: application/json { "error": "Payment required", "mechanisms": [ { "network": "eip155:1", "token": "0x0000000000000000000000000000000000000000", "recipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "amount": "1000000000000000000" } ] } ``` #### Automatic Processing The MCP server handles: * Gas estimation and transaction signing * Payment verification * Retry logic for content access * Error handling for failed payments :::success This protocol enables AI agents to access premium content programmatically, opening new possibilities for automated research and content consumption. ::: ## Setup Detailed setup instructions for the MCP Wallet Server. ### Prerequisites :::info Before proceeding, ensure you have: * Node.js 18+ installed * Package manager: npm or bun * An MCP-compatible client (e.g., Claude Desktop) * Basic command line knowledge ::: ### Installation ::::steps #### Clone the Repository Clone the project and navigate to the directory: :::code-group ```bash [npm] git clone https://github.com/mmsaki/accounts.git cd accounts ``` ```bash [bun] git clone https://github.com/mmsaki/accounts.git cd accounts ``` ::: #### Install Dependencies Install project dependencies: :::code-group ```bash [npm] npm install ``` ```bash [bun] bun install ``` ::: #### Build the MCP Server Navigate to the MCP server directory and build: :::code-group ```bash [npm] cd mcp-server npm install npm run build ``` ```bash [bun] cd mcp-server bun install bun run build ``` ::: :::tip The build process compiles TypeScript and prepares the server for execution. ::: #### Configure Your MCP Client Create or update your MCP configuration file (typically `mcp.json` or similar): ```json [mcp.json] { "$schema": "https://opencode.ai/config.json", "mcp": { "wallet-server": { "type": "local", "command": ["node", "./mcp-server/dist/index.js"], "enabled": true } } } ``` :::warning Update the `command` path to match your actual project structure and built server location. ::: #### Launch and Verify Start your MCP client with the new configuration. Test connectivity by calling one of the tools. :::success Your MCP Wallet Server is now ready to handle Ethereum operations! ::: :::: ## MCP Server Overview The MCP (Model Context Protocol) server provides comprehensive wallet functionality for Ethereum interactions, enabling AI agents to perform blockchain operations seamlessly. ### Features :::info The server offers three core capabilities: * **Balance Checking**: Query ETH balances for any address * **Transaction Sending**: Send ETH with automatic gas estimation * **Paid Content Access**: Browse web content with automatic 402 payment handling ::: ### Quick Start ::::steps #### Install Dependencies Navigate to the MCP server directory and install: :::code-group ```bash [npm] cd mcp-server npm install ``` ```bash [bun] cd mcp-server bun install ``` ::: #### Build the Server Compile the TypeScript code: ```bash npm run build ``` #### Configure MCP Client Add to your MCP configuration file: ```json [mcp.json] { "$schema": "https://opencode.ai/config.json", "mcp": { "wallet-server": { "type": "local", "command": ["node", "./mcp-server/dist/index.js"], "enabled": true } } } ``` :::warning Ensure the command path points to your built server executable. ::: #### Start Using Launch your MCP client and call tools like `mcpwallet_get_balance` for wallet operations. :::: ### Architecture The MCP server is built with a modular architecture: | Layer | Purpose | | ---------------------- | ---------------------------------------------------- | | **MCP Protocol Layer** | Handles JSON-RPC communication with MCP clients | | **Wallet Layer** | Manages Ethereum transactions using Viem library | | **Payment Layer** | Processes HTTP 402 Payment Required responses | | **Consent Layer** | Optional user approval UI for sensitive transactions | :::tip This layered design ensures security, modularity, and easy maintenance. ::: ### Related Sections * [Payment Protocol](/mcp-server-payment-protocol) - Deep dive into HTTP 402 implementation * [API](/mcp-server-api) - Complete API reference for all tools * [Setup](/mcp-server-setup) - Detailed installation and configuration * [Examples](/mcp-server-examples) - Practical usage patterns and workflows ## Balance Inquiry Query the ETH balance of an Ethereum address. :::code-group ```json [Request] { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "mcpwallet_get_balance", "arguments": { "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" } } } ``` ```json [Response] { "jsonrpc": "2.0", "id": 1, "result": { "balance": "15.234567" } } ``` ::: :::info Balances are returned in ETH for easy readability. ::: ## HTTP 402 Payment Required Access premium web content protected by HTTP 402 Payment Required responses with automatic payment processing. :::code-group ```json [Request] { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "mcpwallet_browse_with_payment", "arguments": { "url": "https://premium-content.example.com/article" } } } ``` ```json [Response] { "jsonrpc": "2.0", "id": 3, "result": { "content": "Premium article content...", "paymentProcessed": true } } ``` ::: :::info This tool automatically handles HTTP 402 Payment Required responses by processing the required payment and retrying the request. ::: :::tip The `paymentProcessed` flag indicates whether a payment was made to access the content. ::: ## MCP Server Examples Practical examples demonstrating how to use the MCP Wallet Server tools in your applications. ### Advanced Workflow Combine multiple tools for complex operations: ```json [Multi-Step Workflow] // Step 1: Check balance before sending { "method": "tools/call", "params": { "name": "mcpwallet_get_balance", "arguments": { "address": "0x..." } } } // Step 2: Send payment if sufficient balance { "method": "tools/call", "params": { "name": "mcpwallet_send_transaction", "arguments": { "to": "0x...", "amount": "0.1" } } } // Step 3: Access paid content { "method": "tools/call", "params": { "name": "mcpwallet_browse_with_payment", "arguments": { "url": "https://paid.example.com" } } } ``` :::success These examples demonstrate the full range of MCP Wallet Server capabilities for Ethereum operations and paid content access. ::: ## Send Transaction Send ETH to another address with automatic gas handling. :::code-group ```json [Request] { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "mcpwallet_send_transaction", "arguments": { "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "amount": "0.1" } } } ``` ```json [Response] { "jsonrpc": "2.0", "id": 2, "result": { "txHash": "0xabcdef1234567890...", "status": "confirmed" } } ``` ::: :::warning Transactions are irreversible. Double-check addresses and amounts. ::: ## browse\_with\_payment Browses a URL and automatically handles any 402 payment responses by paying for access using the wallet. ### Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------- | | `url` | string | Yes | The URL to browse (must be HTTP/HTTPS) | ### Returns ```json { "content": "Full page content...", "paymentProcessed": true } ``` :::tip This tool seamlessly handles 402 Payment Required responses, making paid content accessible to AI agents. ::: ### Example :::code-group ```json [Request] { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "mcpwallet_browse_with_payment", "arguments": { "url": "https://premium-content.example.com/article" } } } ``` ```json [Response] { "jsonrpc": "2.0", "id": 3, "result": { "content": "Premium article content...", "paymentProcessed": true } } ``` ::: ## get\_balance Retrieves the current ETH balance of an Ethereum address. ### Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `address` | string | Yes | Valid Ethereum address (0x-prefixed) | ### Returns ```json { "balance": "42.0691337" } ``` :::info Balances are returned in ETH (not wei) for readability. ::: ### Example :::code-group ```json [Request] { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "mcpwallet_get_balance", "arguments": { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } } } ``` ```json [Response] { "jsonrpc": "2.0", "id": 1, "result": { "balance": "42.0691337" } } ``` ::: ## API The MCP server exposes three primary tools through the MCP protocol for Ethereum wallet operations and paid content access. ### Error Handling All tools may return error responses in case of invalid parameters or execution failures: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid address format" } } ``` :::info Common error codes include invalid parameters (-32602) and internal errors (-32603). ::: ## send\_transaction Sends ETH from the wallet to a specified recipient address with automatic gas estimation. ### Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------- | | `to` | string | Yes | Recipient Ethereum address (0x-prefixed) | | `amount` | string | Yes | Amount of ETH to send (e.g., "0.1") | ### Returns ```json { "txHash": "0x1234567890abcdef...", "status": "confirmed" } ``` :::warning Transactions are executed immediately. Ensure addresses and amounts are correct before calling. ::: ### Example :::code-group ```json [Request] { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "mcpwallet_send_transaction", "arguments": { "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "amount": "0.01" } } } ``` ```json [Response] { "jsonrpc": "2.0", "id": 2, "result": { "txHash": "0x1234567890abcdef...", "status": "confirmed" } } ``` ::: ## The Future of Content Monetization AI agents pay for premium data access, and crawlers are kept at bay by a simple payment wall. Welcome to the world of HTTP 402 Payment Required, we transform how you monetize digital content. ### What is HTTP 402? HTTP 402 "Payment Required" is an underutilized HTTP status code designed for scenarios where a server requires payment before fulfilling a request. Unlike traditional paywalls that require user interaction, 402 enables programmatic payments that work seamlessly with automated systems like AI agents, crawlers, and APIs. ### How Agents Can Use 402 Payments In the MCP (Model Context Protocol) ecosystem, agents can now access paid content automatically: ```json // Agent requests premium content GET /premium-article HTTP/1.1 // Server responds with payment requirements HTTP/1.1 402 Payment Required X-Payment-Required: {"mechanisms": [{"network": "eip155:1", "token": "0xA0b86a33E6441e88C5F2712C3E9b74B8E5f5c4b4", "recipient": "0x...", "amount": "1000000"}]} // Agent processes payment automatically // Then retries with payment proof GET /premium-article HTTP/1.1 X-Payment: 0xtransactionhash ``` This enables AI agents to: * Access real-time financial data * Use premium APIs without manual intervention * Build richer applications with paid datasets * Create value-added services on top of monetized content ### Benefits for Content Creators #### 1. **Aggressive Crawler Prevention** Traditional rate limiting struggles with distributed botnets. 402 payments create an economic barrier that makes mass scraping prohibitively expensive while allowing legitimate users and agents to pay for access. #### 2. **Flexible Monetization** Creators can set dynamic pricing based on: * Content type and quality * User/agent type * Time of access * Usage volume #### 3. **Built-in Rate Limiting** Each request carries its own payment, naturally limiting abusive access patterns. No more complex rate limiting rules – economics handles it automatically. #### 4. **DDoS Protection** Attackers would need to spend real money to overwhelm your servers. This creates a natural economic defense against denial-of-service attacks. ### Flexible Payment Infrastructure The beauty of 402 lies in its token-agnostic design: #### **Native Ethereum** ```json { "network": "eip155:1", "token": "0x0000000000000000000000000000000000000000", // ETH "recipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "amount": "1000000000000000000" // 1 ETH in wei } ``` #### **ERC20 Tokens** ```json { "network": "eip155:1", "token": "0xA0b86a33E6441e88C5F2712C3E9b74B8E5f5c4b4", // USDC "recipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "amount": "1000000" // 1 USDC (6 decimals) } ``` #### **Future Possibilities** * Stablecoins for price stability * Creator tokens for community building * NFT access tokens for exclusive content * Cross-chain payments via bridges ### Real-World Applications #### **Financial Data Providers** Bloomberg, Reuters, and financial APIs can charge per query, ensuring only serious users access premium market data. #### **AI Training Data** Datasets for machine learning can be monetized per access, funding better data collection and curation. #### **News and Journalism** Quality journalism can be supported directly by readers and AI systems that value accurate information. #### **Research and Academia** Academic papers, datasets, and research tools can be monetized while remaining accessible to those willing to pay. ### The MCP Advantage The Model Context Protocol makes 402 payments even more powerful by standardizing how agents interact with paid content. With tools like `mcpwallet_browse_with_payment`, agents can seamlessly handle payments without custom integration for each service. ### Getting Started Ready to implement 402 payments? Check out our [MCP Server documentation](/mcp_server_overview) to start building the future of web monetization. The web is about to get a lot more valuable – one payment at a time! 🚀 ## Blog ::blog-posts