# L402 Gateway ⚡

Multi-tenant L402 (Lightning HTTP 402) paywall-as-a-service. Add Bitcoin micropayments to any website in minutes. **No Lightning node required.**

## Architecture

- **Runtime:** Cloudflare Worker (TypeScript)
- **Database:** Cloudflare D1 (SQLite)
- **Lightning:** LNbits (external, via env secrets)
- **Auth:** LNURL-auth (wallet login) + email signup
- **Revenue:** Fee-on-creation (configurable %, default 2%)

## Setup

### Prerequisites

- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
- An [LNbits](https://lnbits.com) instance with admin API key
- Node.js 18+

### 1. Install dependencies

```bash
npm install
```

### 2. Create D1 database

```bash
wrangler d1 create l402-gateway
# Update database_id in wrangler.toml with the returned ID
```

### 3. Run migrations

```bash
wrangler d1 execute l402-gateway --file=schema.sql
wrangler d1 execute l402-gateway --file=migrations/002-api-key-hash.sql
wrangler d1 execute l402-gateway --file=migrations/003-email-verification.sql
wrangler d1 execute l402-gateway --file=migrations/004-lnurl-auth.sql
wrangler d1 execute l402-gateway --file=migrations/005-security-fixes.sql
wrangler d1 execute l402-gateway --file=migrations/006-resources.sql
```

### 4. Set secrets

```bash
wrangler secret put LNBITS_URL           # LNbits instance URL
wrangler secret put LNBITS_ADMIN_KEY     # LNbits admin API key
wrangler secret put GATEWAY_ADMIN_TOKEN  # Admin auth token
wrangler secret put MACAROON_SECRET      # HMAC key for macaroon signing
wrangler secret put ENCRYPTION_KEY       # AES-256-GCM key for tenant secrets
```

### 5. Deploy

```bash
wrangler deploy
```

## API Overview

| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/health` | GET | — | Health check |
| `/auth/lnurl` | GET | — | LNURL-auth challenge |
| `/api/v1/signup` | POST | — | Public self-service signup |
| `/api/v1/tenants` | POST | Admin | Create tenant (admin) |
| `/api/v1/tenants/me` | GET | Tenant | Get tenant info |
| `/api/v1/invoice` | POST | Tenant | Create L402 invoice |
| `/api/v1/verify` | GET | L402 | Verify L402 token |
| `/api/v1/status/:hash` | GET | Tenant | Check payment status |
| `/api/v1/payments` | GET | Tenant | List payments |
| `/api/v1/stats` | GET | Tenant | Payment statistics |
| `/api/v1/balance` | GET | Tenant | Wallet balance |
| `/api/v1/withdraw` | POST | Tenant | LNURL-withdraw |
| `/api/v1/resources` | POST/GET | Tenant | Manage resources |
| `/mcp` | POST | Tenant | MCP Remote Server (JSON-RPC 2.0) |

## Use with AI Agents — MCP Remote Server

**L402 Gateway implements the Model Context Protocol (MCP)** for seamless AI agent integration.

### What is MCP?

MCP is a standardized protocol for AI models (Claude, etc.) to access external tools and data sources safely. The L402 Gateway exposes all payment and contract operations as MCP tools.

### Available Tools (16 total)

**Agent Registration:**
- `l402_register` — Create new agent account instantly

**Wallet:**
- `l402_balance` — Check balance
- `l402_deposit` — Create deposit invoice
- `l402_check_deposit` — Check deposit status
- `l402_withdraw` — Create withdrawal

**Service Offers:**
- `l402_create_offer` — List a service
- `l402_list_offers` — Browse services
- `l402_get_offer` — Get offer details

**Contracts & Escrow:**
- `l402_accept_offer` — Accept and create contract
- `l402_fund_contract` — Fund escrow
- `l402_list_contracts` — List your contracts
- `l402_get_contract` — Get contract details
- `l402_deliver` — Submit delivery proof
- `l402_confirm` — Confirm & release escrow
- `l402_dispute` — Submit dispute

**Accounting:**
- `l402_ledger` — View balance history

### Configure in Claude Desktop

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "l402-gateway": {
      "command": "npx",
      "args": [
        "@anthropic-ai/fetch-server",
        "https://l402gw.nosaltres2.info/mcp"
      ],
      "env": {
        "X_L402_KEY": "l402_sk_your_api_key_here"
      }
    }
  }
}
```

Then restart Claude Desktop. You'll now be able to:
- Register agents
- Create and accept service offers
- Manage payments & deposits
- View transaction history

### Example Agent Workflow

```
User: "Register my agent and check if any text analysis services are available"

Claude uses MCP:
1. l402_register → "agent-0xabc123"
2. l402_list_offers → Finds text analysis services
3. l402_get_offer → Gets pricing and terms
4. [Ready to accept and fund contracts]
```

### API Endpoint

```
POST https://l402gw.nosaltres2.info/mcp
Content-Type: application/json
X-L402-Key: l402_sk_...

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "l402_balance",
    "arguments": {}
  }
}
```

**See [MCP-ENDPOINT.md](./MCP-ENDPOINT.md) for full specification.**

---

## Quick Integration (Web Paywalls)

```html
<!-- 1. Register a resource via API -->
<!-- 2. Add the paywall snippet -->
<div data-l402-resource="premium">
  <p>Preview text only...</p>
</div>

<script src="https://l402gw.nosaltres2.info/js/l402.js"
        data-api-key="l402_sk_..."></script>
```

## Docs

Full documentation: [l402gw.nosaltres2.info/docs](https://l402gw.nosaltres2.info/docs/)

## License

ISC