HTTP 402 AI Tollbooth
Free MCP troubleshooting-preview tools; purchases stay human-directed.
Open source Repository Open in the app JSON README (API)
About
Free MCP troubleshooting-preview tools; purchases stay human-directed.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- robotfleet-hq
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.0
- Last push
- 2026-09-07T12:20:53Z
- Repository state
- ativo
- License
- MIT
- Added
- 2026-09-07 16:03:59
- Updated
- 2026-09-07 16:03:59
- Origin id
io.github.RobotFleet-HQ/http-402-ai-tollbooth
README
# HTTP 402 AI Tollbooth
> Agent-ready developer troubleshooting data, sold per request over Bitcoin Lightning.
**Live:** https://http-402-ai-tollbooth.rsaun-lightning.workers.dev
HTTP 402 AI Tollbooth gives developers and AI agents three useful records free, then unlocks complete structured datasets with a BOLT11 Lightning payment. There are no accounts, subscriptions, credit cards, or API keys.
This is a public, documentation and example repository. The production Worker implementation remains private and is not included here.
## Try it now
List the complete catalog:
```bash
curl -sS https://http-402-ai-tollbooth.rsaun-lightning.workers.dev/api/catalog
```
Preview exactly three records without payment:
```bash
curl -sS https://http-402-ai-tollbooth.rsaun-lightning.workers.dev/api/preview/api-error-fixes
```
Request the full product and receive an HTTP 402 Lightning challenge:
```bash
curl -i https://http-402-ai-tollbooth.rsaun-lightning.workers.dev/api/data/api-error-fixes
```
The last command creates an invoice. Do not run it unless you intentionally want a payment challenge; simply requesting it does not spend sats.
## Why agents use it
- 203 products across DevOps, APIs, ML/AI, Web/Frontend, and Databases
- Entry, Standard, and Premium datasets with 50, 100, or 200 records
- Exactly three free records per product for try-before-you-buy discovery
- Stable `error_code`, `description`, and `programmatic_fix` fields
- HTTP 402 and Bitcoin Lightning payments without user accounts
- OpenAPI 3.1, MCP discovery metadata, and `llms.txt`
- Deterministic fallback generation for resilient dataset delivery
- Durable one-time redemption and replay protection
- Future x402 settlement is documented but remains disabled pending verification
## Architecture
```text
AI agent / developer
|
| HTTPS: catalog, preview, paid dataset
v
Cloudflare Worker
| | |
| | +--> Alby --> Bitcoin Lightning invoice
| |
| +--> Durable Objects --> atomic redemption + counters
|
+--> Workers KV --> invoice challenges + generated dataset cache
```
## Pricing
| Tier | Price | Records |
|---|---:|---:|
| Entry | 2,000 sats | 50 |
| Standard | 5,000 sats | 100 |
| Premium | 10,000 sats | 200 |
See [the pricing rationale](docs/PRICING.md), including the live-verified 2,000-sat receiving floor.
## How to pay
1. Request a paid product endpoint.
2. Receive `402 Payment Required` with a BOLT11 invoice and payment hash.
3. Pay the invoice in a Lightning wallet.
4. Retry the same endpoint with `X-Payment-Hash` and `X-Payment-Preimage`.
5. Receive the full dataset once; replayed proofs are rejected.
Never publish or share a payment preimage before using it for its intended redemption. Future Solana USDC/x402 support is disabled until its manual verification process is completed.
## Discovery documents
- [Smithery server card](docs/server-card.json)
- [OpenAPI 3.1 document](docs/openapi.json)
- [llms.txt](docs/llms.txt)
- [Billboard integration summary](BILLBOARD.md)
- [Official MCP Registry readiness](docs/MCP-REGISTRY-SUBMISSION.md)
## Integrations
- **MCP metadata:** tool descriptions for catalog, preview, and purchase discovery
- **MCP transport:** a live Streamable HTTP JSON-RPC endpoint at `/mcp` with four read-only tools
- **OpenAPI:** complete HTTP endpoint descriptions for agent frameworks
- **LLMs.txt:** concise machine-readable project and payment guidance
Connect an MCP client to `https://http-402-ai-tollbooth.rsaun-lightning.workers.dev/mcp`. The server supports `list_products`, `preview_product`, `list_payment_methods`, and `buy_product`. The last tool only returns payment directions and an HTTP 402 challenge; it never pays an invoice or creates a purchase on the caller's behalf.
For a complete no-payment example, see [the Node agent recovery sample](examples/node-agent-recovery/).
## Runnable free sample
The sample shows how an agent can inspect malformed JSON, retry a transient `429` once after `Retry-After`, and safely stop when a response is not recoverable. It uses Node 22+ built-ins only:
```bash
cd examples/node-agent-recovery
npm test
npm start
```
The demo calls only the public three-record preview endpoint. It does not call a paid route, create an invoice, or automatically replay a payment proof.
## License
The documentation in this billboard repository is available under the MIT License. The private production source code is not covered by this repository or license.