@bitbooth/mcp-fetch

@bitbooth/mcp-fetch

An agent-facing x402 catalog and buyer shipped as one MCP server. Discover and preflight BitBooth APIs for free, fetch a URL over Base USDC, or explicitly opt into XRPL mainnet RLUSD for stateful page-change detection and XRPL wallet-runway monitoring.

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, call the gateway's separate POST /v1/cdp/render-pro Playwright endpoint with an x402-aware HTTP client.

🧭 Scope: discover_bitbooth and preflight_bitbooth are free and available in every rail mode, even without a wallet credential. Base remains the default paid rail and exposes fetch. Explicit xrpl-rlusd mode exposes watch_page and watch_xrpl_wallet, then signs the x402 v2 XRPL payment proof. The live catalog at /bazaar.json is canonical.

✅ Verified on-chain — BitBooth's XRPL merchant receipts are public on the XRPL AI profile.

🛡️ Testnet by default. A fresh install uses Base Sepolia. XRPL is mainnet-only and requires both an explicit rail selection and a separate XRPL seed.

Install

Version 2.2 required: the gateway now requires a request-bound EIP-191 proof signed by the same wallet that sent the USDC transfer. Version 1.x's constant marker is rejected. Keep the ^2.2.0 pin below so installation fails closed until the hardened release is available.

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:

For free catalog discovery and preflight, no wallet is required:

{
  "mcpServers": {
    "bitbooth": {
      "command": "npx",
      "args": ["-y", "@bitbooth/mcp-fetch@^2.2.0"]
    }
  }
}

Add a dedicated testnet wallet to enable the paid fetch tool:

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

Claude Code

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

Set your agent wallet key:

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

Global install

npm install -g @bitbooth/mcp-fetch@^2.2.0
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

Every install exposes two free tools that never sign or submit a payment:

discover_bitbooth(
  query: "repair malformed JSON",
  category: "utility",
  maxPriceUsd: 0.01,
  network: "eip155:8453",
  limit: 10
)

preflight_bitbooth(
  route: "json-repair",
  maxPriceUsd: 0.01,
  network: "eip155:8453"
)

discover_bitbooth fetches and validates the live catalog, then returns concise JSON with matching routes and advertised payment requirements. Set configuredOnly: true to filter to the MCP server's configured network and asset instead of browsing all rails.

preflight_bitbooth accepts an exact route name, path, or URL and either selects one compatible advertised requirement under the hard price ceiling or returns a structured no_match. If network or asset is explicit, that filter wins, but it does not reconfigure the buyer: the selected requirement must still match the server's configured payment rail. Otherwise preflight uses that configured rail automatically. Its output always contains paymentAuthorized: false. A buyer must still compare the selection with the live HTTP 402 challenge before signing.

With a Base wallet configured, your agent also gets the paid 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).

XRPL RLUSD agent watches

XRPL mode replaces the paid fetch tool with two paid watch tools. The free discovery and preflight tools remain available:

watch_page(url: "https://example.com/pricing")

watch_xrpl_wallet(
  address: "rAgentWallet...",
  minCallsRemaining: 10,
  minSpendableXrpDrops: "1000",
  allowedDestinations: ["rKnownMerchant..."]
)

watch_page stores a lightweight content fingerprint, then reports meaningful changes on later calls. watch_xrpl_wallet returns OK, WARN, or CRITICAL with spendable XRP after reserves, RLUSD trust-line and paid-call runway, recent validated activity, unfamiliar destinations, and payer-scoped baseline deltas. Omitted wallet-watch policy fields use server defaults: 0.001 RLUSD per planned call, 10 calls remaining, 1,000 spendable drops, no known destinations, and 50 recent transactions.

To opt in, use a dedicated low-balance payment wallet that holds only the RLUSD and XRP gas budget intended for this agent:

{
  "mcpServers": {
    "bitbooth-watch": {
      "command": "npx",
      "args": ["-y", "@bitbooth/mcp-fetch@^2.2.0"],
      "env": {
        "BITBOOTH_PAYMENT_RAIL": "xrpl-rlusd",
        "BITBOOTH_XRPL_SEED": "sEd<dedicated-agent-seed>",
        "BITBOOTH_MAX_PER_CALL_USD": "0.001",
        "BITBOOTH_DAILY_LIMIT_USD": "0.10"
      }
    }
  }
}

This is real mainnet spend. BITBOOTH_AGENT_KEY is never used as an XRPL seed, and setting only BITBOOTH_XRPL_SEED does not enable XRPL payments. Monitoring the payment wallet itself works, but its own watch payment changes that wallet; for cleaner incident signals, pay from a separate low-balance watchdog wallet.

Need JS-rendered SPAs or dashboards? The BitBooth gateway also exposes POST /v1/cdp/render-pro ($0.05, Playwright rendering) directly over HTTP. See the live endpoint catalog.

Pricing

Item	Cost
discover_bitbooth	Free — reads the public live catalog
preflight_bitbooth	Free — selects a requirement but never signs or pays
fast/full	0.005 USDC per fetch
watch_page	0.001 RLUSD per fingerprint comparison
watch_xrpl_wallet	0.001 RLUSD per wallet runway/activity check
Gas	Base gas as applicable; XRPL fee is capped at 100 drops by default
Default chain	Base Sepolia (testnet). Explicit opt-in for mainnet.

Configuration

Env var	Description	Default
BITBOOTH_AGENT_KEY	Dedicated EVM agent private key (required only for the paid Base fetch tool)	—
BITBOOTH_PAYMENT_RAIL	base or explicit mainnet opt-in xrpl-rlusd	base
BITBOOTH_XRPL_SEED	Dedicated XRPL seed; required only for xrpl-rlusd	—
BITBOOTH_CHAIN_ID	84532 = Base Sepolia (default, free testnet). 8453 = Base mainnet (real USDC — opt-in).	84532
BITBOOTH_API_URL	BitBooth gateway URL	https://app.heinrichstech.com
BITBOOTH_RPC_URL	EVM RPC endpoint	https://base-sepolia-rpc.publicnode.com
BITBOOTH_CONFIRMATIONS	Tx confirmations to wait before retry (minimum two)	2
BITBOOTH_API_KEY	Optional tenant API key (for higher rate limits)	—
BITBOOTH_MAX_PER_CALL_USD	Maximum stablecoin amount accepted from one challenge	0.10 Base / 0.001 XRPL
BITBOOTH_DAILY_LIMIT_USD	Per-wallet, per-UTC-day reservation cap for the current process	1.00 Base / 0.10 XRPL
BITBOOTH_XRPL_WS_URL	Credential-free WSS endpoint used only to autofill and ledger-bind the signed transaction	wss://xrplcluster.com/
BITBOOTH_XRPL_MAX_FEE_DROPS	Maximum XRP network fee allowed in an autofilled transaction	100

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.

XRPL safety pins

XRPL mode refuses to pay unless every live PAYMENT-REQUIRED challenge matches all of these values:

• HTTPS origin https://app.heinrichstech.com
• network xrpl:0, scheme exact, and the canonical hex-encoded RLUSD currency
• Ripple RLUSD issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De
• BitBooth recipient rfryheo6yzFdLWj8qUQtZc7zG9MKkBkUEy
• exact requested resource URL, a bounded one-time invoice, and the expected source tag
• exactly 0.001000 RLUSD for either XRPL watch tool

The transaction is last-ledger bounded, partial payments are forbidden, and autofilled recipient, amount, issuer, invoice, memo, and fee fields are checked again before signing. The signed payload is sent as PAYMENT-SIGNATURE; it and the seed are never printed.

watch_page rejects credential-bearing URLs, localhost and .local names, and literal private, loopback, or link-local IPs before requesting a challenge. BitBooth also resolves and checks DNS server-side before settlement to cover rebinding and hostname-to-private-address cases. watch_xrpl_wallet validates classic addresses, numeric bounds, activity limits, and a maximum 25-address allowlist before requesting a challenge.

Programmatic use

Catalog discovery and preflight can be used without constructing a wallet client:

import { createCatalogClient } from '@bitbooth/mcp-fetch/catalog-client';

const catalog = createCatalogClient({ chainId: 8453 });
const choices = await catalog.discover({ query: 'monitor', maxPriceUsd: 0.01 });
const checkout = await catalog.preflight({ route: 'web-watch', maxPriceUsd: 0.001 });
console.log(choices.resources, checkout);

For automatic payment:

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);

const watcher = createX402Client({
  paymentRail: 'xrpl-rlusd',
  xrplSeed: process.env.DEDICATED_XRPL_AGENT_SEED,
  maxPerCallUsd: '0.001',
  dailyLimitUsd: '0.10',
});
const result = await watcher.watchPageWithPayment('https://example.com/pricing');
console.log(result.changed, result.hashes.current, result.baseline);

const health = await watcher.watchXrplWalletWithPayment({
  address: 'rAgentWallet...',
  minCallsRemaining: 10,
  minSpendableXrpDrops: '1000',
  allowedDestinations: ['rKnownMerchant...'],
});
console.log(health.status, health.runway, health.alerts);

How it works

The free catalog client performs one credential-free GET /bazaar.json, validates the complete remote payload with Zod, and filters locally. It sends no API key, wallet key, seed, signature, or payment header. Preflight is advisory: the eventual buyer must validate the fresh HTTP 402 challenge again.

For Base payments, the package performs the existing request-bound USDC transfer flow. In XRPL mode it reads the base64 PAYMENT-REQUIRED v2 header, selects exactly one pinned RLUSD requirement, signs an invoice-bound XRPL Payment, and retries with the base64 PAYMENT-SIGNATURE. The full XRPL lifecycle is serialized per wallet, including across package clients in one process. At most one unresolved proof is retained per wallet; exact-request retries reuse it byte-for-byte, while a different request is blocked until the first resolves. The proof clears only after HTTP 200.

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

What endpoints can my agent call

Every mode exposes discover_bitbooth and preflight_bitbooth. Paid tool exposure follows the selected rail: fetch on Base; watch_page and watch_xrpl_wallet on XRPL RLUSD. Agents can call the rest of BitBooth over plain HTTP with a compatible x402 buyer. Prices and route inventory change, so /bazaar.json and the fresh HTTP 402 challenge are canonical.

Federal posture

BitBooth is operated by a service-disabled veteran-owned small business (SDVOSB certified) with an active CAGE code and SAM.gov registration. Defense and federal-contractor teams can procure implementation and managed-operations support through an identifiable U.S. supplier. Details are on the landing page.

Security notes

• BITBOOTH_AGENT_KEY and BITBOOTH_XRPL_SEED are secrets. Use separate dedicated agent wallets, never a personal or treasury wallet.
• Discovery-only installs need neither secret. The catalog client never forwards BITBOOTH_API_KEY or any payment credential to /bazaar.json.
• Default config uses testnet. Never set mainnet keys in a testnet config.
• Base validates the recipient from each payment challenge; both XRPL watch tools additionally pin the recipient in code. If delivery fails after settlement, the XRPL proof is retained for safe replay; retry the byte-identical tool request and do not manually submit another payment.
• Spend reservations are shared by all package clients in one Node process and reset on process restart. They prevent concurrent calls from exceeding that process's configured cap; the dedicated wallet's deliberately small balance is the durable cross-restart ceiling.

License

MIT