Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Payment Protocol

The MCP server implements a payment protocol for web browsing using HTTP 402 Payment Required responses, enabling access to paid content.

Overview

How It Works

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.

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.

Technical Details

402 Response Format

Servers implementing 402 payments should return payment details in the X-Payment-Required header:

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