# BitBooth — x402 Payment Gateway

> BitBooth is a production multi-chain x402 payment gateway that lets AI agents pay for APIs in stablecoin per-request — no API keys, no signup, no humans in the loop. Zero-friction agent-native commerce on XRPL, Solana, Stellar, and Base.

## What it is

BitBooth implements the [x402 V2 protocol](https://x402.gitbook.io) (Coinbase Foundation + Linux Foundation). Any HTTP API can be wrapped: when an agent calls a paid endpoint, the server returns `HTTP 402 Payment Required` with a challenge. The agent pays on-chain, retries with the payment proof, and receives the data. One round-trip, sub-10s for EVM/Solana/Stellar, sub-second for Lightning.

## Live agent-native endpoint

Pay-per-fetch URL → Markdown converter, **zero signup required**:

```
POST https://x76se73jxd.execute-api.us-east-2.amazonaws.com/staging/v1/fetch
Content-Type: application/json

{ "url": "https://example.com", "mode": "fast" }
```

First call returns `HTTP 402` with an x402 challenge. Pay 0.005 USDC on Base Sepolia, retry with the `X-Payment` header, receive markdown. One round-trip, ~8s end-to-end.

## Pricing

| Endpoint | Price | Notes |
|---|---|---|
| `/v1/fetch` (fast) | **0.005 USDC** | Raw HTML → Markdown, no API key |
| `/v1/fetch` (full) | **0.005 USDC** | Readability article extraction, no API key |
| `/v1/resource` | varies | Tenant-configured, requires API key |

Default chain: **Base Sepolia** testnet. Circle Sepolia USDC from https://faucet.circle.com. Mainnet Base opt-in via `BITBOOTH_CHAIN_ID=8453`.

## MCP integration (recommended)

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

In Claude Desktop / Claude Code / Cursor / any MCP host:

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

Agent gets a `fetch(url, mode)` tool that pays via x402 automatically.

## Supported chains

| Network | CAIP-2 | Asset | Status |
|---|---|---|---|
| Base Sepolia | `eip155:84532` | USDC | Live (default) |
| Base Mainnet | `eip155:8453` | USDC | Live (opt-in) |
| XRPL EVM Sidechain | `eip155:1440002` | USDC | Live |
| XRPL Mainnet | `xrpl:0` | USDC, RLUSD, XRP | Live |
| XRPL Testnet | `xrpl:1` | XRP | Live |
| Solana Mainnet | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | USDC-SPL | Live |
| Solana Devnet | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` | USDC-SPL | Live |
| Stellar Testnet | — | XLM | Live |
| Bitcoin Lightning (L402) | — | sats | Q2 2026 roadmap |

## Protocol guarantees

- **Replay protection:** nonce-based, per-payment, DynamoDB TTL 24h
- **Idempotency:** `X-Idempotency-Key` header, same request = same outcome
- **Fraud prevention:** pre-payment velocity checks, max-amount ceilings, nonce-reuse tracking
- **Rate limits:** per-IP (anonymous) or per-tenant (API key), 60 req/min default free tier

## Links

- **[Landing page](https://heinrichstech.com/bitbooth.html):** live 6-chain race demo
- **[GitHub](https://github.com/Drock91/bitbooth-gateway):** MIT source, 3,317 tests
- **[npm @bitbooth/mcp-fetch](https://www.npmjs.com/package/@bitbooth/mcp-fetch):** MCP server
- **[x402 V2 spec](https://x402.gitbook.io):** Coinbase + Linux Foundation protocol
- **[.well-known/agent.json](https://heinrichstech.com/.well-known/agent.json):** machine-readable manifest
- **[Full context](https://heinrichstech.com/llms-full.txt):** extended technical docs

## Optional

- [Company Homepage](https://heinrichstech.com/): Heinrichs Software Solutions LLC