bitbooth-docs

# BitBooth

> The multi-chain x402 payment gateway for AI agents. **18 paid HTTP endpoints**, **5 mainnet chains**, **real on-chain settlement**, **~$2/month to run on AWS Lambda**.

**Live:** [app.heinrichstech.com](https://app.heinrichstech.com)
**Playground:** [app.heinrichstech.com/demo](https://app.heinrichstech.com/demo)
**API reference:** [app.heinrichstech.com/docs](https://app.heinrichstech.com/docs)
**Bazaar manifest:** [app.heinrichstech.com/bazaar.json](https://app.heinrichstech.com/bazaar.json)
**A2A agent card:** [app.heinrichstech.com/.well-known/agent.json](https://app.heinrichstech.com/.well-known/agent.json)

---

## What is this?

BitBooth implements the [x402 protocol](https://x402.gitbook.io) — Coinbase's spec for "HTTP 402 Payment Required + on-chain settlement." Drop a paywall in front of any HTTP endpoint, and AI agents pay per call from their own wallet. No accounts, no API keys, no signups. Non-custodial — the agent pays your wallet directly, BitBooth never touches the funds.

```
1. Agent calls a paywalled endpoint with no payment
2. Server returns HTTP 402 with a multi-chain `accepts[]` array
3. Agent picks one entry (whatever chain it holds liquidity on) and signs
4. Agent retries the request with X-PAYMENT header
5. Server verifies + settles + unlocks the response
```

The whole loop is ~3 seconds on Base mainnet.

## Why multi-chain?

Every BitBooth endpoint advertises up to **9 (network, asset) tuples** in every 402 challenge:

| Network | Asset | Facilitator |
|---|---|---|
| Base mainnet (eip155:8453) | USDC | Coinbase CDP |
| Base mainnet | Chainlink LINK | Self-hosted onchain verifier |
| Solana mainnet | USDC SPL | Coinbase CDP |
| XRPL native (xrpl:0) | XRP | [T54 XRPL Facilitator](https://www.t54.ai) |
| XRPL native | RLUSD (Ripple issuer) | T54 |
| XRPL native | USDC IOU (Bitstamp issuer) | T54 |
| Stellar pubnet | XLM | Self-hosted Horizon |
| Stellar pubnet | USDC (Circle issuer) | Self-hosted Horizon |
| XRPL EVM Sidechain (eip155:1440000) | Native XRP | Self-hosted onchain verifier |

Agents pick the chain they already hold. No bridging, no swaps, no friction.

## Quick start

### Pay one endpoint with curl (no payment yet — see the 402 challenge)

```bash
curl -s -X POST https://app.heinrichstech.com/v1/cdp/echo \
  -H 'content-type: application/json' \
  -d '{"message":"hello from agent"}'
```

You'll get back a `402` response body containing `resource`, `accepts[]`, and an `extensions.bazaar` block.

### Install the MCP server for any Claude / Cursor / Continue agent

```bash
npm install -g @bitbooth/mcp-fetch
```

Or in your MCP client config (Claude Desktop, Cursor, etc.):

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

Testnet by default (Base Sepolia). Opt into mainnet explicitly with `BITBOOTH_CHAIN_ID=8453`.

### Or build your own buyer

See `examples/` for runnable demos:
- `01-curl-fetch.sh` — pure shell, sees the 402 challenge
- `02-node-evm-pay.mjs` — Node + ethers, signs EIP-3009 transferWithAuthorization on Base
- `03-node-xrpl-pay.mjs` — Node + xrpl.js, signs an XRPL Payment tx through the T54 facilitator
- `04-mcp-config.json` — drop-in MCP client config
- `05-langchain-agent.py` — LangChain agent that fetches paid URLs

## The endpoint catalog

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

Full schemas in [`openapi.yaml`](./openapi.yaml). Live manifest at [`/bazaar.json`](https://app.heinrichstech.com/bazaar.json).

## Documentation

- [`docs/INTEGRATION.md`](./docs/INTEGRATION.md) — integration guide (buyer + seller patterns)
- [`docs/ENDPOINTS.md`](./docs/ENDPOINTS.md) — full endpoint catalog with examples
- [`docs/XRPL.md`](./docs/XRPL.md) — XRPL native + XRPL EVM Sidechain integration notes
- [`openapi.yaml`](./openapi.yaml) — full OpenAPI spec for every paid endpoint
- [`examples/`](./examples/) — runnable demos

## About

BitBooth is built and operated by **[Heinrichs Software Solutions Company](https://heinrichstech.com)** — a veteran-owned business based in Tallahassee, Florida. SDVOSB-pending, CAGE-registered, SAM.gov-registered. Solo-built. Production-grade testing (~2,400+ Vitest tests, 92% coverage on core payment + middleware paths). Approved under [Anthropic's Cyber Verification Program](https://www.anthropic.com) for dual-use cybersecurity work.

## License

MIT — see [LICENSE](./LICENSE).

This repository contains the **public documentation, OpenAPI spec, and runnable examples** for BitBooth. The gateway source code is operated privately during a federal-procurement-posture scrub; for technical-interview-grade source access, contact `derek@heinrichstech.com`.