# SpendFuel

> https://spendfuel.app
> Spend control plane + discovery layer for Cloudflare Wallets and x402 / MCP tools.

SpendFuel helps agents and humans discover, evaluate, and safely spend on paid APIs and MCP servers. Rankings use real paid outcomes. Primary interface is MCP + JSON APIs; web UI is secondary.

## Base URL

- Production: https://spendfuel.app
- Local: http://127.0.0.1:8787

## Agent interfaces

- MCP Streamable HTTP: POST /mcp
- MCP SSE (legacy): GET/POST /sse
- OpenAPI: GET /openapi.yaml
- This file: GET /llms.txt

## JSON API (v1)

### Health
GET /api/v1/health

### Catalog
GET /api/v1/catalog
Query params:
- q: free-text search
- category: e.g. search, data, vision, compute
- max_price: number (USD)
- verified: true|false
- sort: rank|price|success_rate|newest
- limit: 1-100 (default 50)
- offset: pagination

GET /api/v1/catalog/categories

### Tool detail
GET /api/v1/tools/{slug}

### Recommendations
GET /api/v1/recommend?goal={text}&budget_usd={n}&limit={n}

## MCP tools

| Tool | Status | Purpose |
|------|--------|---------|
| search_tools | live | Filter catalog by capability, price, reliability |
| recommend_tools | live | Goal + budget aware recommendations |
| get_tool | live | Full tool details |
| report_outcome | stub (Phase 2) | Report success/failure after use |
| get_spend_summary | stub (Phase 3) | Wallet burn rate / budget |

## Design principles for agents

1. Prefer recommend_tools when you have a spend cap.
2. Prefer verified listings when reliability matters.
3. Call report_outcome after paid usage (when available) so rankings improve.
4. Responses are compact JSON to minimize tokens.
5. Catalog GETs are edge-cached (~30s); expect x-cache headers.

## Ownership claims (Phase 1)

- DNS TXT record
- `/.well-known/spendfuel-claim` file
- Cloudflare account ownership proof (preferred)

## Roadmap (high level)

- Phase 0: foundation (current)
- Phase 1: inventory seeding + claim verification
- Phase 2: full agent MCP + ranking feedback
- Phase 3: wallet analytics + reputation
- Phase 4: policy engine, teams, monetization