# WaaS - Lightning Sub-Wallet as a Service for Autonomous AI Agents

> Instant programmatic Lightning sub-wallets, budgets, and scoped NWC (Nostr Wallet Connect) connection strings for autonomous AI agents, multi-agent frameworks, and autonomous bots, provisioned via L402 paywall.

## Overview
WaaS (Wallet-as-a-Service) provides hosted Lightning sub-wallet provisioning for agent developers and autonomous AI agents, with permission-scoped NWC (Nostr Wallet Connect) access and defined spending limits. Agents discover pricing, pay an L402 Lightning challenge, and immediately receive scoped credentials to spend and receive satoshis under operator custody.

- **Base URL**: https://waas.ch4t.buzz
- **API Spec (OpenAPI 3.1)**: https://waas.ch4t.buzz/openapi.json
- **AI Plugin Manifest**: https://waas.ch4t.buzz/.well-known/ai-plugin.json
- **Protocol**: HTTP REST + L402 (Lightning Network HTTP 402 Payment Required) + NIP-47 (NWC)

## Key Endpoints

### Discovery & Public Endpoints
- `GET /api/v1/pricing`: Returns live satoshi pricing tiers for all services (wallet provisioning, NWC apps, research, MCP).
- `GET /api/v1/stats`: Live aggregate gateway metrics (requests and satoshi volumes).
- `GET /health`: Health probe reporting API and lightning node operational status.
- `GET /openapi.json`: Complete OpenAPI 3.1 schema.

### L402 Paid Services
- `POST /api/v1/wallet/provision`: Programmatically mints an isolated sub-wallet with optional custom Lightning Address. Requires L402 Macaroon + Lightning preimage payment.
- `POST /api/v1/nwc/app`: Mints scoped, budgeted Nostr Wallet Connect (NIP-47) pairing strings for agent payment execution.
- `POST /mcp/v1/messages`: Model Context Protocol (MCP) JSON-RPC execution endpoint wrapped with L402 micropayments.

## Architecture & Security Invariants
- **Custody & Blast Radius**: Hosted Lightning sub-wallet provisioning operates under operator custody on Alby Hub with permission-scoped, budget-capped NWC (NIP-47) credentials to strictly bound blast radius.
- **Macaroon Caveat Binding**: Payment parameters (budget, duration, wallet limits) are cryptographically bound in caveat tokens at challenge generation.
- **Settlement Integrity**: All operations settle against operator-run Alby Hub LDK node backend.

## Quickstart for AI Agents
1. Fetch live pricing:
   `curl -s https://waas.ch4t.buzz/api/v1/pricing`
2. Issue an unauthenticated POST request to `/api/v1/wallet/provision` to trigger an HTTP 402 challenge.
3. Parse the `WWW-Authenticate` header containing `L402 macaroon="..." invoice="..."`.
4. Pay the Bolt11 invoice via your parent Lightning node or NWC client.
5. Re-send the request with `Authorization: L402 <macaroon>:<preimage>`.
6. Receive your active sub-wallet connection credentials and budgeted NWC URI.