@bitbooth/mcp-fetch

The first working x402 reference implementation, shipped as an MCP server. Fetches any URL, pays the gateway from the agent wallet via the x402 protocol, returns clean markdown.

What makes this worth paying for: mode: "render" uses Playwright to render JavaScript-heavy pages (SPAs, dashboards, dynamic content) that the free @modelcontextprotocol/server-fetch can't crawl. mode: "full" extracts article content via Mozilla Readability + Turndown for cleaner markdown than raw HTML conversion.

🛣️ Coming next: shared cache layer (multiple agents hitting the same URL split the payment), YouTube transcript extraction, PDF → markdown. Track it: https://github.com/Drock91/bitbooth-gateway/blob/main/GOALS.md

✅ Verified end-to-end on live mainnet — last real payment landed in 1.3s (proof).

🛡️ Testnet by default. Defaults to Base Sepolia so a fresh install spends free testnet USDC, not real money. Opt into mainnet explicitly (see below).

Install

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "bitbooth-fetch": {
      "command": "npx",
      "args": ["-y", "@bitbooth/mcp-fetch"],
      "env": {
        "BITBOOTH_AGENT_KEY": "0x<your-testnet-wallet-private-key>"
      }
    }
  }
}

Claude Code

claude mcp add bitbooth-fetch -- npx -y @bitbooth/mcp-fetch

Set your agent wallet key:

export BITBOOTH_AGENT_KEY="0x<your-testnet-wallet-private-key>"

Global install

npm install -g @bitbooth/mcp-fetch
mcp-fetch   # runs on stdio

Get a testnet wallet + USDC (free, 2 minutes)

1. Generate an EVM wallet or use an existing one you control
2. Fund it with Base Sepolia ETH (gas): https://www.alchemy.com/faucets/base-sepolia
3. Fund it with Base Sepolia USDC: https://faucet.circle.com (select Base Sepolia)
4. Set BITBOOTH_AGENT_KEY to the wallet's private key (0x...)

Usage

Once installed, your agent gets a fetch tool:

fetch(url: "https://example.com", mode: "render")

Modes:

| Mode | Price | Description | Best for | | -------- | ---------- | ---------------------------------------------- | ---------------------------- | | fast | 0.005 USDC | Raw HTML converted to markdown | Quick lookups, static pages | | full | 0.005 USDC | Article extraction (Readability) then markdown | Blog posts, docs, news | | render | 0.02 USDC | Playwright JS rendering then markdown | SPAs, dashboards, dynamic JS |

Returns markdown with title, body, and metadata (URL, timestamp, content length, truncation status).

Pricing

| Item | Cost | | ------------- | ---------------------------------------------------- | | fast/full | 0.005 USDC per fetch | | render | 0.02 USDC per fetch (Playwright is expensive) | | Gas | ~$0.0001 per tx on Base (mainnet) / free (testnet) | | Default chain | Base Sepolia (testnet). Explicit opt-in for mainnet. |

Configuration

| Env var | Description | Default | | ------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------- | | BITBOOTH_AGENT_KEY | Agent wallet private key (required, 0x-prefixed hex) | — | | BITBOOTH_CHAIN_ID | 84532 = Base Sepolia (default, free testnet). 8453 = Base mainnet (real USDC — opt-in). | 84532 | | BITBOOTH_API_URL | BitBooth gateway URL | staging endpoint (Base Sepolia) | | BITBOOTH_RPC_URL | EVM RPC endpoint | https://base-sepolia-rpc.publicnode.com | | BITBOOTH_CONFIRMATIONS | Tx confirmations to wait before retry | 1 | | BITBOOTH_API_KEY | Optional tenant API key (for higher rate limits) | — |

Mainnet opt-in

When you've tested against Sepolia and want to run against real Base mainnet:

export BITBOOTH_CHAIN_ID=8453
export BITBOOTH_API_URL=https://app.heinrichstech.com
export BITBOOTH_RPC_URL=https://base-rpc.publicnode.com   # or your own RPC
export BITBOOTH_AGENT_KEY=0x<mainnet-wallet-with-real-USDC>

The package prints a warning banner to stderr whenever mainnet is active so a misconfig can't silently drain a real wallet.

The same app.heinrichstech.com gateway also accepts XRPL Mainnet payments (XRP, USDC-via-Bitstamp, RLUSD-via-Ripple). Native XRPL support in this MCP package is on the roadmap — track it at https://github.com/Drock91/bitbooth-gateway/issues

Programmatic use

import { createX402Client } from '@bitbooth/mcp-fetch/x402-client';

const client = createX402Client({ agentKey: process.env.AGENT_KEY });
const result = await client.fetchWithPayment('https://example.com', 'fast');
console.log(result.markdown);

How it works

1. Your agent calls fetch(url) via MCP
2. The server POST /v1/fetchs to BitBooth
3. BitBooth returns HTTP 402 with a payment challenge { nonce, payTo, amountWei }
4. The server transfers USDC on Base to payTo
5. Waits for 1 confirmation, retries with the x-payment header
6. Returns the fetched content as markdown

Zero human in the loop. Zero signup. Just pay-per-call via x402.

Security notes

• BITBOOTH_AGENT_KEY is a private key — treat it like a password. Use a dedicated wallet for this agent, not your personal wallet.
• Default config uses testnet. Never set mainnet keys in a testnet config.
• The package makes an outbound payment transaction to the BitBooth payTo address on every successful fetch. If the service is unavailable, the retry request fails but the payment was still sent on-chain — refunds require contacting the operator.

License

MIT