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