BitBooth

Pay-per-call x402 endpoints for AI agents on Base mainnet. Six paid endpoints live, settling through the Coinbase CDP Facilitator, plus an MCP fetch server on npm. No API keys, no signup, no humans in the loop.

npm install @bitbooth/mcp-fetch

Built on the x402 protocol (Coinbase + Linux Foundation). All six paid endpoints have settled real USDC on Base mainnet via the CDP Facilitator.

💰 Six paid endpoints live on Base mainnet. Discoverable at /bazaar.json and listed in awesome-x402 (PR pending). All six settle through the Coinbase CDP Facilitator (api.cdp.coinbase.com/platform/v2/x402). No API keys, no signup, no humans in the loop.

🛡️ Testnet by default for the MCP fetch package. A fresh @bitbooth/mcp-fetch install spends free Base Sepolia USDC, not real money. Opt into mainnet explicitly by setting BITBOOTH_CHAIN_ID=8453.

🛒 Self-hosted bazaar discovery. Every paid endpoint is enumerated at /bazaar.json so agents can crawl the catalog directly. Each entry carries the canonical bazaar extension fields (discoverable, category, tags, info, schema).

---

Six paid endpoints live on Base mainnet

Path	Price	What it does
POST /v1/cdp/echo	0.001 USDC	x402 reference implementation. Smallest possible paid endpoint — useful as an integration sanity check.
POST /v1/cdp/json-repair	0.001 USDC	Repairs malformed JSON output from LLM tool calls. Optional JSON Schema validation pass.
POST /v1/cdp/faker	0.001 USDC	Synthetic test data via @faker-js/faker. Declarative templates, seeded reproducibility, 1–100 records per call.
POST /v1/cdp/render-pro	0.05 USDC	Full Playwright JS rendering + Mozilla Readability extraction → markdown. Handles SPAs that naive HTTP fetch cannot.
POST /v1/cdp/web-diff	0.05 USDC	Renders a URL fresh and returns a structured diff against a previous markdown snapshot the caller supplies. Built for monitoring agents.
POST /v1/cdp/approval-safety	0.05 USDC	Pre-flight risk check for ERC-20 approve(spender, amount). Flags unlimited approvals to fresh contracts, EOA spenders, copycat tokens, known-malicious spenders.

All six share the same withCdpX402(spec, inner) middleware — single source of truth for verification, settlement, and bazaar shape. Each one returns a canonical x402 v2 challenge to a request that arrives without an X-Payment header.

curl -i -X POST https://app.heinrichstech.com/v1/cdp/echo
# HTTP/1.1 402 Payment Required
# content-type: application/json
#
# {
#   "x402Version": 2,
#   "error": "X-PAYMENT header is required",
#   "resource": {
#     "url": "https://app.heinrichstech.com/v1/cdp/echo",
#     "description": "BitBooth echo endpoint — pays a tiny USDC fee, returns a JSON echo. Reference implementation of the x402 + CDP Facilitator + Bazaar discovery loop.",
#     "mimeType": "application/json"
#   },
#   "accepts": [{
#     "scheme": "exact",
#     "network": "eip155:8453",
#     "amount": "1000",
#     "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
#     "payTo": "0xDa2F35d283c42dd60B965322394bc658a5c1769F",
#     "maxTimeoutSeconds": 300,
#     "extra": { "name": "USD Coin", "version": "2" }
#   }],
#   "extensions": { "bazaar": { "discoverable": true, "category": "utility", "tags": [...], "info": {...}, "schema": {...} } }
# }

Try it right now

The flagship agent-native endpoint. No API key. No signup. Just pay.

# 1. Hit the endpoint — get a 402 with a payment challenge
curl -X POST https://app.heinrichstech.com/v1/fetch \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","mode":"fast"}'

# HTTP/1.1 402 Payment Required
# {
#   "error": { "code": "PAYMENT_REQUIRED", "message": "Payment required" },
#   "challenge": {
#     "nonce": "bc98010eb4f84ab6c25b9a34188dcec0",
#     "expiresAt": 1778092838,
#     "resource": "/v1/fetch",
#     "accepts": [{
#       "scheme": "exact",
#       "network": "eip155:84532",
#       "payTo": "0xDa2F35d283c42dd60B965322394bc658a5c1769F",
#       "asset": "USDC@0x036CbD53842c5426634e7929541eC2318f3dCF7e",
#       "amount": "5000"
#     }],
#     "amountWei": "5000",
#     "assetSymbol": "USDC",
#     "chainId": 84532
#   }
# }

# 2. Agent signs + sends 0.005 USDC on Base Sepolia to payTo
# 3. Agent retries with X-Payment header containing the tx hash
# 4. Gets 200 OK + clean markdown back

For full Playwright JS rendering on real-money mainnet, use /v1/cdp/render-pro (0.05 USDC on Base mainnet).

Install as an MCP server

One line and any Claude Code / Cursor / Windsurf / Continue agent can use it:

npm install @bitbooth/mcp-fetch   # 1.0.2 on npm

Add to your MCP config:

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

See packages/mcp-fetch/README.md for full configuration.

How it works

Agent                         BitBooth                        Your API
  │                              │                               │
  │── POST /v1/cdp/echo ────────►│                               │
  │◄── 402 Payment Required ─────│  (challenge: amount, nonce)   │
  │                              │                               │
  │── send USDC on-chain ────────────────────────────────────►   │
  │── retry with X-Payment ─────►│                               │
  │                              │── verify via CDP Facilitator ►│
  │                              │◄── confirmed ─────────────    │
  │                              │── execute handler ────────►   │
  │◄── 200 OK ──────────────────────────────────────────────────│

1. Agent calls a paywalled endpoint
2. Server returns 402 Payment Required with a signed challenge (amount, nonce, payTo, expiry)
3. Agent signs and sends the payment from its wallet
4. Agent retries with the tx hash (or signed authorization) in the X-Payment header
5. BitBooth verifies on-chain via the configured facilitator (CDP for the /v1/cdp/* suite, native verifier for everything else), checks replay protection, executes the handler
6. Server responds 200 OK

One round-trip. Verified end-to-end on Base Mainnet via the Coinbase CDP Facilitator today.

Networks

Network	Asset	Used by	Status
Base Mainnet (eip155:8453)	USDC	All six /v1/cdp/* paid endpoints	✅ Live — settling via Coinbase CDP Facilitator. 12+ confirmed real-money settlements.
Base Sepolia (eip155:84532)	USDC	/v1/fetch testnet path + @bitbooth/mcp-fetch default	✅ End-to-end verified, free testnet USDC, development only

Adapter code for additional rails (XRPL, BSC, Solana, Stellar) lives in src/adapters/ for future expansion but is not currently advertised in the live accepts[] array. The current focus is the six Base mainnet endpoints.

API

Method	Path	Auth	Description
POST	/v1/cdp/echo	x402 (CDP)	Reference paid endpoint. 0.001 USDC on Base mainnet.
POST	/v1/cdp/json-repair	x402 (CDP)	Repair LLM tool-call JSON. Optional schema validation. 0.001 USDC.
POST	/v1/cdp/faker	x402 (CDP)	Synthetic data via @faker-js/faker. 0.001 USDC.
POST	/v1/cdp/render-pro	x402 (CDP)	Playwright JS rendering + Readability extraction. 0.05 USDC.
POST	/v1/cdp/web-diff	x402 (CDP)	Render fresh + diff vs caller-supplied previous markdown. 0.05 USDC.
POST	/v1/cdp/approval-safety	x402 (CDP)	ERC-20 approve() pre-flight risk assessment. 0.05 USDC.
GET	/bazaar.json	—	Self-hosted catalog of all paid endpoints (canonical bazaar shape).
POST	/v1/fetch	x402 only	URL → clean markdown. Modes: fast / full. No API key. Pay-per-call on Base Sepolia testnet.
POST	/v1/resource	API key + x402	Paywalled resource (tenant-configured pricing)
POST	/v1/resource/premium	API key + x402	Premium resource (2× price)
POST	/v1/resource/bulk	API key + x402	Bulk operations (amount × item count)
GET	/v1/payments	API key	Payment history (cursor pagination)
GET	/v1/health	—	Health check
GET	/v1/health/ready	—	Readiness (DDB + RPC + secrets)

Full spec in openapi.yaml.

Architecture

bitbooth-gateway/
├── src/
│   ├── routes/          # HTTP route tables
│   ├── controllers/
│   │   ├── cdp-echo.controller.js
│   │   ├── cdp-json-repair.controller.js
│   │   ├── cdp-faker.controller.js
│   │   ├── cdp-render-pro.controller.js
│   │   ├── cdp-web-diff.controller.js
│   │   ├── cdp-approval-safety.controller.js
│   │   ├── bazaar.controller.js     # serves /bazaar.json catalog
│   │   └── (fetch, payments, portal, admin, ...)
│   ├── services/        # Business logic, orchestration
│   ├── adapters/
│   │   ├── base/        #   Base mainnet + Sepolia (viem)
│   │   ├── bsc/         #   BSC mainnet + testnet (viem)
│   │   ├── xrpl/        #   Native XRPL (xrpl.js)
│   │   ├── xrpl-evm/    #   XRPL EVM Sidechain (ethers)
│   │   ├── solana/      #   Solana mainnet + devnet (@solana/web3.js)
│   │   ├── stellar/     #   Stellar pubnet + testnet (stellar-sdk)
│   │   └── ows/         #   Open Wallet Standard
│   ├── middleware/
│   │   ├── x402.middleware.js       # native verifier (XRPL, BSC, Solana, Stellar)
│   │   ├── cdp-x402.middleware.js   # CDP Facilitator wrapper for /v1/cdp/*
│   │   └── (auth, rate-limit, idempotency, errors, CORS)
│   ├── validators/      # Zod schemas (every boundary validated)
│   ├── repositories/    # DynamoDB (10 tables)
│   ├── handlers/        # Lambda entry points (api / fetch / proxy / webhook / dlq-sweep)
│   └── lib/             # Config, logger, errors, crypto, metrics, secrets
├── infra/               # AWS CDK (Lambda + API GW + DDB + Secrets Manager + WAF)
├── packages/
│   ├── mcp-fetch/       # @bitbooth/mcp-fetch — MCP server for fetch tool
│   ├── langchain-bitbooth/  # LangChain tool wrapper
│   └── bitbooth-py/     # Python client
├── tests/               # 3,400+ unit tests + integration tests
├── scripts/             # Smoke tests, load tests, ops tools
└── docs/                # Deploy guide, integration guide, ADRs

Stack

• Runtime: Node 20, pure JavaScript (ESM), no TypeScript
• Cloud: AWS Lambda, API Gateway, DynamoDB, Secrets Manager, CloudWatch
• Network: Base Mainnet for all paid endpoints (/v1/cdp/*); Base Sepolia for the MCP fetch testnet path
• Facilitator: Coinbase CDP for every paid endpoint (api.cdp.coinbase.com/platform/v2/x402)
• Protocol: x402 V2 (HTTP 402 Payment Required) + bazaar discovery extension
• Validation: Zod at every boundary
• Testing: Vitest — 3,400+ tests, all passing
• Infra: AWS CDK (stage-aware: dev/staging/prod)
• Deploy: esbuild bundles per-Lambda, cdk deploy

What's built

• Six paid endpoints on Base mainnet (/v1/cdp/*) — echo, json-repair, faker, render-pro, web-diff, approval-safety. All settle through the Coinbase CDP Facilitator. Discoverable at /bazaar.json and listed in awesome-x402 (PR pending merge).
• x402 V2 protocol — challenge/response with nonce-based replay protection, on-chain settlement via the CDP Facilitator. Verified end-to-end on Base Mainnet today.
• Self-hosted bazaar discovery at /bazaar.json — canonical resource catalog with discoverable, category, tags, info, schema fields per resource so agents can enumerate the surface programmatically.
• MCP server — @bitbooth/mcp-fetch v1.0.2 on npm. One-line install for any Claude Code / Cursor / Windsurf / Continue agent.
• Agent-native fetch endpoint (/v1/fetch) — zero signup, zero API key, pure pay-per-call. Two modes: fast (0.005 USDC, raw HTML → markdown) and full (0.005 USDC, article extraction via Readability + Turndown). For full Playwright JS rendering on mainnet, use the dedicated /v1/cdp/render-pro endpoint above.
• Multi-tenant SaaS — self-service signup, API keys, per-route pricing, session-based client portal.
• Fraud prevention — velocity rules, nonce tracking, amount bounds, configurable thresholds.
• Rate limiting — token bucket, 4 tiers (Free/Starter/Growth/Scale), per-IP for anonymous callers.
• Idempotency — 24h result caching via DynamoDB TTL.
• Admin console — branded admin at app.heinrichstech.com/admin with Tenants, Metrics, Earnings (Grafana-style), self-service password rotation.
• Webhook DLQ — retry with exponential backoff, max-age cleanup.
• Observability — CloudWatch alarms, structured pino logging with redaction.
• OpenAPI 3.0 spec at /openapi.yaml, auto-validated against live routes in CI.

Quick start

npm install           # install deps
npm run lint          # eslint --max-warnings=0
npm test              # 3,400+ tests, ~20s
npm run build         # esbuild bundles to dist/
npm run cdk:synth     # validates CDK stack (STAGE=dev)

Deploy

# Staging (Base Sepolia, free testnet USDC)
STAGE=staging npm run cdk:deploy:staging

# Production (Base mainnet, real USDC + CDP Facilitator)
STAGE=prod npm run cdk:deploy:prod

Full walkthrough in docs/DEPLOY.md.

Testing

npm test                          # run all 3,400+ unit tests
npm run test:integration          # requires LocalStack + testnet RPC
npm run test:coverage             # coverage report (target ≥80% on services/ and middleware/)
npm run smoke:cdp                 # 29-assertion negative-path smoke against the live deployment

Docs

• CLAUDE.md — development conventions and non-negotiables (read before contributing)
• openapi.yaml — full API specification
• docs/DEPLOY.md — CDK deployment guide
• docs/RUNBOOK.md — operational runbook (alerts, incident response)
• docs/integration-guide.md — 5-minute API integration walkthrough
• docs/BAZAAR_RESOURCES.md — paid-endpoint catalog (mirror of /bazaar.json)
• docs/adr/ — architecture decision records
• packages/mcp-fetch/README.md — MCP server for AI agents

Security

• No secrets in code — all loaded from AWS Secrets Manager at cold start
• Least-privilege IAM per Lambda
• x402 endpoints verify the on-chain transaction (or signed EIP-3009 authorization for the CDP suite), check nonce against DDB for replay protection, enforce a ≤ 120s payment window
• Webhooks verify HMAC before any business logic
• Logger redacts API keys, private keys, signed payloads
• Input size limits: JSON body ≤ 100KB unless explicitly opted in
• Rate limits via API Gateway usage plans + per-account token bucket

See CLAUDE.md for the full security posture.

Contributing

This is a working open-source x402 reference gateway. PRs welcome. Before opening one:

1. npm run lint must pass with zero warnings
2. npm test must pass all 3,400+ tests
3. npm audit --audit-level=high must return 0
4. Add Zod validators for any new request shape
5. No TypeScript — this is pure JavaScript + JSDoc typedefs (see CLAUDE.md)

License

MIT — free for commercial and personal use.

---

Links

• Six paid endpoints catalog (/bazaar.json)
• Live bazaar catalog (/bazaar.json)
• Live /v1/cdp/echo endpoint
• @bitbooth/mcp-fetch on npm
• awesome-x402 listing PR
• x402 V2 spec (Coinbase + Linux Foundation)
• .well-known/agent.json
• llms.txt