L402 Gateway

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
• An LNbits instance with admin API key
• Node.js 18+

1. Install dependencies

npm install

2. Create D1 database

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

3. Run migrations

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

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

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:

{
  "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 for full specification.

---

Quick Integration (Web Paywalls)

<!-- 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

License

ISC