L402 Toolkit

l402工具包

用于Node.js服务器和AI代理钱包的JavaScript L402实现。

L402 将闪电支付与马卡龙凭证相结合——支付 *是* 认证令牌。没有帐户，没有会话，没有Cookie。支付一次，即可访问资源。该工具包提供了两个方面：一个服务器模块用于控制Lightning支付墙后面的资源，另一个MCP服务器为AI代理提供了一个预算有限的钱包来支付它们。

里面是什么

l402.js --服务器端L402模块

为任何Node.js HTTP服务器插入L402协议。一个依赖(macaroons.js)，没有框架意见。

• 通过LND REST API创建Lightning发票
• 为每个资源添加标记的杏仁饼（不仅仅是URL路径门控）
• 无状态地验证令牌——没有数据库，只有密码学
• 检查客户端令牌-- getTokenInfo() 读取过期和资源而不进行验证
• 使用 http.createServer()、表达、禁食或其他任何事情

const l402 = require('./l402');
l402.initLnd();

// In your route handler:
const authorized = await l402.handleL402Auth(req, res, 'resource-id');
if (!authorized) return; // 402 challenge already sent
// Serve the resource...

mcp/lnd-wallet-mcp.js --AI代理钱包

主控程序 为AI代理（Claude Code、Cursor等）提供主权Lightning钱包的服务器。6个工具，预算执行，直接连接到本地LND节点。

该代理运行自己的LND中微子节点-无托管服务，无API密钥，无平台费用。马卡龙的烘焙权限受到限制：支付、解码、余额和发票。代理无法打开通道、在链上发送或访问种子。

example-server.js -财富Cookie API

L402门控幸运饼干服务器。付10个萨茨，赚大钱。演示对代理友好的发现模式：免费 /api 带有服务描述、消费提示和分步的端点 l402_flow 响应中嵌入的指令。

example-catalog-server.js --多资源目录

具有多种资源类型的L402门控目录。演示完整代理发现模式：免费浏览、搜索、402个响应中的使用提示、每个结果的解析URL以及不同的使用类型（API响应、浏览器、下载、显示）。

export L402_SECRET=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
export LND_MACAROON_PATH=/path/to/invoice.macaroon
node example-server.js
# → http://localhost:3000/api/fortune

快速开始

服务器（网关资源）

git clone https://github.com/EricRHadley/l402-toolkit.git
cd l402-toolkit
npm install

# Configure (see docs/ARCHITECTURE.md for full setup)
export L402_SECRET=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
export LND_MACAROON_PATH=/path/to/your/invoice.macaroon
export LND_TLS_CERT_PATH=/path/to/your/tls.cert
export LND_REST_HOST=https://your-lnd-node:8080

node example-server.js
# → http://localhost:3000/api (service info)
# → http://localhost:3000/api/fortune (L402-gated, 10 sats)

代理人（资源付费）

cd l402-toolkit/mcp
npm install

# Bake a restricted macaroon (LND must be running)
../setup/bake-agent-macaroon.sh

# Copy TLS cert
cp ~/.lnd/tls.cert credentials/

# Register in Claude Code (~/.claude.json)

{
  "mcpServers": {
    "lnd-wallet": {
      "command": "node",
      "args": ["/absolute/path/to/l402-toolkit/mcp/lnd-wallet-mcp.js"],
      "env": {
        "LND_REST_HOST": "https://localhost:8080",
        "BUDGET_SATS": "1000"
      }
    }
  }
}

重新启动克劳德代码。代理人现在有钱包工具，可以支付L402发票。

L402的工作原理

1. Client requests a resource
2. Server returns 402 with WWW-Authenticate: L402 macaroon="...", invoice="lnbc..."
3. Client pays the Lightning invoice → receives preimage
4. Client re-requests with: Authorization: L402 :

5. Server verifies: SHA256(preimage) == payment_hash, caveats valid, HMAC valid
6. Resource served

马卡龙的标识符是闪电支付哈希。预映像是唯一SHA256与该哈希匹配的值。这将凭证与付款进行加密绑定——如果不支付发票，就无法伪造令牌。

看 docs/ARCHITECTURE.md 了解完整的协议演练、设计决策和代理钱包设置指南。

代理人对代理人付款

钱包是双向的。代理人可以为服务付费，也可以为工作付费。

Agent A (buyer)                          Agent B (seller)
─────────────                            ─────────────
                    "Do this task"
                  ─────────────────►
                                         create_invoice(500, "research task")
                    "lnbc5u1pn..."
                  ◄─────────────────
decode_invoice(...)
pay_invoice("lnbc5u1pn...")
                    preimage
                  ─────────────────►
                                         check_invoice(payment_hash)
                                         → SETTLED
                    [delivers work]
                  ◄─────────────────

没有市场平台。没有托管服务。没有账户。BOLT11发票只是一个字符串——通过HTTP、电子邮件、Nostr、聊天消息或任何方式传递。闪电网络结算付款，无论发票是如何发送的。

每张已付款发票都是一张加密收据：预映像证明付款已发生，付款哈希将其链接到特定请求，金额和时间戳被纳入其中。代理将交易历史作为开展业务的自然副产品进行积累，不需要单独的信誉系统。

用例

• 赏金 --代理发布了一个有固定预算的任务。另一位代理人负责这项工作，开具发票，并在交货时收到付款。
• 资源共享 --拥有Claude Max订阅的代理将研究能力出售给没有订阅的代理。500个卫星用于深入分析，50个卫星用于快速查找。
• 数据源 --监控链上数据的代理为实时警报创建发票。其他代理通过按警报付费进行订阅。
• 计算市场 --具有GPU访问发票的代理用于推理作业。按代币支付，结算闪电。

无论是人类为视频支付10个卫星，还是代理人为研究任务支付500个卫星，协议都是一样的。 create_invoice + pay_invoice + check_invoice --三个工具，任何用例。

让您的服务代理变得友好

想要AI代理在不需要预先书面说明的情况下发现并支付您的L402服务吗？看 docs/AGENT-DISCOVERY.md 用于12种模式，使您的402响应能够自我描述——信息丰富的响应体、消费提示、免费发现端点、服务目录注册和令牌生命周期管理。

仓库结构

l402-toolkit/
├── l402.js                  # L402 protocol module (server-side)
├── example-server.js        # Fortune cookie API (single-resource demo)
├── example-catalog-server.js # Media catalog (multi-resource demo)
├── package.json             # macaroons.js dependency
├── mcp/
│   ├── lnd-wallet-mcp.js   # MCP agent wallet server
│   ├── package.json         # @modelcontextprotocol/sdk, zod
│   └── CLAUDE.md            # Agent instructions for L402 flow
├── setup/
│   ├── neutrino-lnd.conf   # LND neutrino config (copy to ~/.lnd/)
│   └── bake-agent-macaroon.sh  # Creates restricted macaroon
├── docs/
│   ├── ARCHITECTURE.md      # Protocol docs, design decisions, setup guide
│   └── AGENT-DISCOVERY.md   # 11 patterns for agent-friendly L402 services
└── LICENSE                  # MIT

为什么存在

L402规范自2019年以来就存在了（最初是LSAT），但实现情况很少：

• 光圈 是一个Go反向代理，非常适合在基础架构级别对API进行门控，但它在URL路径级别运行，需要部署一个单独的进程
• 螺栓墙 是Express中间件——锁定到Express，使用弃用的依赖项，3年没有更新，仍然使用旧的“LSAT”头格式
• 郎链比特币 表明AI代理可以为API付费，但它被锁定在LangChain/Python上，没有预算执行，并且在不验证金额的情况下支付发票

该工具包是：

• 无框架 --vanilla Node.js，适用于任何HTTP服务器
• 资源级别门控 --每资源警告，而不仅仅是URL路径
• 代理就绪 --MCP钱包可与任何兼容MCP的AI工具配合使用
• 主权 --代理运行自己的LND节点，没有托管服务
• 最小化 --l402.js有1个依赖项，MCP服务器有2个依赖项
• 维护 --当前L402规范术语，正在积极开发

现场制作

该工具包为真实的主网L402服务提供支持：

• l402.目录 --为启用L402的API打开服务注册表。发现服务，验证它们是否接受真实的闪电支付，并跟踪正常运行时间。API的免费发现 GET /api.
• hyperdope.com --闪电门控视频内容。通过L402为每个视频支付10个sats，通过HLS流式传输，其中包含经过令牌认证的片段。

两个服务都运行 l402.js 从这个用于发票创建、马卡龙铸造和令牌验证的工具包中。目录的健康检查器使用MCP代理钱包支付真实发票并端到端验证服务。

许可证

麻省理工学院