install in 30 seconds

Get your agent paying for fetches.

BitBooth is an MCP server that lets any AI agent fetch URLs and get back clean markdown — paying per call via the x402 protocol. Free testnet by default. Opt into real money explicitly.

Honest framing: the fetch+markdown logic in v1.0.x is functionally equivalent to the free @modelcontextprotocol/server-fetch. Install BitBooth to understand the x402 protocol. The version that's worth paying for ships in 2 weeks (JS rendering via Playwright). Track GOALS.md.

1. Pick your MCP client

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "bitbooth-fetch": {
      "command": "npx",
      "args": ["-y", "@bitbooth/mcp-fetch"],
      "env": {
        "BITBOOTH_AGENT_KEY": "0xYOUR_BASE_SEPOLIA_TESTNET_PRIVATE_KEY"
      }
    }
  }
}

Restart Claude Desktop. Your agent now has a fetch tool.

claude mcp add bitbooth-fetch -- npx -y @bitbooth/mcp-fetch
export BITBOOTH_AGENT_KEY="0xYOUR_BASE_SEPOLIA_TESTNET_PRIVATE_KEY"

Cursor → Settings → MCP → "Edit in settings.json":

{
  "mcpServers": {
    "bitbooth-fetch": {
      "command": "npx",
      "args": ["-y", "@bitbooth/mcp-fetch"],
      "env": { "BITBOOTH_AGENT_KEY": "0xYOUR_TESTNET_PK" }
    }
  }
}

Edit ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@bitbooth/mcp-fetch"],
          "env": { "BITBOOTH_AGENT_KEY": "0xYOUR_TESTNET_PK" }
        }
      }
    ]
  }
}

If you're building your own agent client, BitBooth speaks the standard MCP 2025-06-18 protocol over stdio. To verify the package boots:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}' | \
  BITBOOTH_AGENT_KEY=0xYOUR_PK npx -y @bitbooth/mcp-fetch

Returns the standard MCP initialize response. The package exposes one tool: fetch(url, mode).

2. Get a testnet wallet (free, 2 minutes)

Generate or use an EVM wallet you already control

Any wallet works — MetaMask, Rabby, hardware wallets. Use a dedicated wallet for the agent. Don't put your personal wallet's private key in agent configs.

Get free Base Sepolia ETH (for gas)

alchemy.com/faucets/base-sepolia — paste your wallet address, get a small amount of test ETH.

Get free Base Sepolia USDC (for payments)

faucet.circle.com → select Base Sepolia → drip 10 USDC. Enough for ~2,000 fetches.

Set `BITBOOTH_AGENT_KEY`

Use the wallet's private key (the 0x-prefixed hex string). It goes in the env block of your MCP config (see step 1).

3. Use it from your agent

Once installed, your agent has access to a fetch tool. Try a prompt like:

"Use the bitbooth-fetch tool to fetch https://example.com and summarize what you see."

The agent will pay 0.005 USDC on Base Sepolia (free testnet money), the gateway will return clean markdown, and the agent will read it. Total round-trip: ~1.3 seconds.

4. Modes + pricing

Mode	What it does	Best for	Price
`fast` (default)	Raw HTML → markdown	Quick lookups, simple pages	0.005 USDC
`full`	Article extraction → markdown	Blog posts, docs, news	0.005 USDC
`render` (coming Q2)	JS-rendered via Playwright	SPAs, dashboards, JS-heavy	0.02 USDC

5. Going to mainnet (real money)

Default is testnet. When you opt in, the package prints a stderr warning every fetch so you can't accidentally drain a real wallet. Set these env vars only after you've verified the testnet flow works:

# Real Base mainnet (USDC) — 0.005 USDC per fetch (~$0.005)
export BITBOOTH_CHAIN_ID=8453
export BITBOOTH_API_URL=https://app.heinrichstech.com
export BITBOOTH_RPC_URL=https://base-rpc.publicnode.com
export BITBOOTH_AGENT_KEY=0xWALLET_FUNDED_WITH_REAL_USDC

Today's only end-to-end-verified real money rail is XRPL Mainnet (XRP). Native XRPL signing in this MCP package is roadmapped (track GitHub issues). For now, pay-per-call mainnet via the npm package = Base Mainnet USDC.

6. Configuration reference

Env var	Default	Purpose
`BITBOOTH_AGENT_KEY`	required	0x-prefixed EVM wallet private key. Use a dedicated wallet.
`BITBOOTH_CHAIN_ID`	`84532`	`84532` = Base Sepolia (testnet). `8453` = Base Mainnet (real money).
`BITBOOTH_API_URL`	`https://app.heinrichstech.com`	BitBooth gateway endpoint.
`BITBOOTH_RPC_URL`	chain default	EVM RPC node URL.
`BITBOOTH_CONFIRMATIONS`	`1`	Tx confirmations to wait before retrying with X-Payment.
`BITBOOTH_API_KEY`	none	Optional tenant API key for higher rate limits (sign up at /dashboard).

7. Troubleshooting

Symptom	Fix
`Agent wallet key required`	`BITBOOTH_AGENT_KEY` env var is unset. Check your MCP config's `env` block.
`Wallet 0x... has no ETH for gas`	Hit alchemy.com/faucets/base-sepolia with your wallet address.
`Wallet 0x... has no USDC`	Hit faucet.circle.com → Base Sepolia → 10 USDC.
`Unexpected HTTP 502`	Gateway upstream is briefly down. Retry in ~30s. File an issue if persistent.
Tool doesn't appear in agent	Restart your MCP client. Check the client's MCP server logs for boot errors.

8. What's next

GOALS.md — full roadmap, prioritized
API Reference — Swagger UI for the gateway endpoints
SMOKE_TEST.md — 30-second install verification
examples/ — runnable demos (curl, Node EVM, Node XRPL, LangChain)
x402 V2 spec — the underlying protocol

Get your agent paying for fetches.

1. Pick your MCP client

2. Get a testnet wallet (free, 2 minutes)

Generate or use an EVM wallet you already control

Get free Base Sepolia ETH (for gas)

Get free Base Sepolia USDC (for payments)

Set BITBOOTH_AGENT_KEY

3. Use it from your agent

4. Modes + pricing

5. Going to mainnet (real money)

6. Configuration reference

7. Troubleshooting

8. What's next

Set `BITBOOTH_AGENT_KEY`