@bitbooth/mcp-fetch

@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: "full" extracts article content via Mozilla Readability + Turndown for cleaner markdown than raw HTML conversion. For JS-heavy pages (SPAs, dashboards, dynamic content), pair this with the gateway's POST /v1/cdp/render-pro Playwright endpoint or install @bitbooth/mcp-routes for full coverage of all 18 paid endpoints.

🛣️ Coming next: shared cache layer (multiple agents hitting the same URL split the payment), YouTube transcript extraction, PDF → markdown. Track it at app.heinrichstech.com and on the docs repo: https://github.com/Drock91/bitbooth-docs

✅ 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

MCP-native — drop into Claude Desktop, Claude Code, Cursor, Windsurf, Continue, or any MCP-compatible client. The snippet below matches the canonical install on app.heinrichstech.com.

Claude Desktop / Cursor / Windsurf / Continue

Paste into claude_desktop_config.json (Claude Desktop), .cursorrules.mcp.json (Cursor), or your client's MCP config:

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

Claude Code

claude mcp add bitbooth -- 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)

• Generate an EVM wallet or use an existing one you control
• Fund it with Base Sepolia ETH (gas): https://www.alchemy.com/faucets/base-sepolia
• Fund it with Base Sepolia USDC: https://faucet.circle.com (select Base Sepolia)
• 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: "full")

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

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

Need JS-rendered SPAs / dashboards? The BitBooth gateway also exposes POST /v1/cdp/render-pro ($0.05, Playwright rendering) directly over HTTP — see the endpoint catalog or pair with @bitbooth/mcp-routes for full coverage of all 13 paid endpoints.

Pricing

Item	Cost
fast/full	0.005 USDC per fetch
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-docs/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

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

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

What endpoints can my agent call

This package exposes a single fetch tool. The agent's wallet still has access to the full BitBooth catalog over plain HTTP (POST with an x402-aware client) once it holds USDC on Base. Live prices:

Endpoint	Price	Category
/v1/cdp/echo	0.001 USDC	utility
/v1/cdp/json-repair	0.001 USDC	utility
/v1/cdp/faker	0.001 USDC	utility
/v1/cdp/webhook-sig-verify	0.001 USDC	utility
/v1/cdp/jwt-verify	0.001 USDC	utility
/v1/cdp/llm-tool-validate	0.002 USDC	utility
/v1/cdp/pii-redact	0.002 USDC	utility
/v1/cdp/rss	0.002 USDC	data
/v1/cdp/dns	0.002 USDC	data
/v1/cdp/ssl-info	0.002 USDC	security
/v1/cdp/x402-discover	0.005 USDC	utility
/v1/cdp/agent-credit-score	0.005 USDC	security
/v1/cdp/wallet-doctor	0.005 USDC	security
/v1/cdp/prompt-injection-scan	0.005 USDC	security
/v1/cdp/approval-safety	0.05 USDC	security
/v1/cdp/render-pro	0.05 USDC	data
/v1/cdp/web-diff	0.08 USDC	data

Live machine-readable catalog: /bazaar.json. To expose every endpoint as an MCP tool (rather than just fetch), pair this with @bitbooth/mcp-routes.

Federal posture

BitBooth is a service-disabled veteran-owned small business (SDVOSB) pending with an active CAGE code and SAM.gov registration — the only x402 gateway with a federal-procurement-ready paper trail. Defense and federal-contractor agents that need a verifiable supplier chain can settle calls here without trafficking through anonymous payment infrastructure. Differentiator details on the landing page.

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