402-mcp

402-mcp

Nostr： npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2

L402 客户端 MCP，让 AI Agent 获得经济自主能力。发现、支付并使用设有付费门槛的 Lightning 和 ecash API，并遵守你设定的限额：无需人工注册、无需 API 密钥、没有中间人。

• 发现 Nostr 上的付费 API，无需预先提供 URL
• 自动支付，支持 Lightning（NWC）、Cashu ecash、LNURLcash bearer notes，或由人工通过 QR 码完成支付
• 凭据会在静态存储时缓存并加密（AES-256-GCM）
• 适用于任何 L402 服务端：toll-booth、Aperture 或未来的任何实现

快速开始

无需安装：MCP 客户端首次启动时，npx 会获取 402-mcp。手动运行 npx 402-mcp 只会启动一个等待客户端通过标准输入连接的 stdio 服务（按 Ctrl+C 停止），因此可以用它检查服务是否能启动，但不能用它来实际使用服务。

1. 将其连接到 MCP 客户端

Claude Code：

claude mcp add 402-mcp -- npx 402-mcp

Claude Desktop 或 Cursor，在 MCP 配置文件中：

{
  "mcpServers": {
    "402-mcp": {
      "command": "npx",
      "args": ["402-mcp"]
    }
  }
}

2. 试用

向 Claude 提问：“使用 l402-search 搜索付费笑话 API”，无需钱包，只需发现 API。

3. 为调用付费（可选）：连接 NWC 钱包

402-mcp 会从私有文件读取 Nostr Wallet Connect URI，绝不会从环境变量或命令行读取。先创建仅所有者可访问的文件，再用编辑器将 URI 粘贴进去，以免它留在 shell 历史记录中：

mkdir -p ~/.402-mcp
touch ~/.402-mcp/wallet.nwc
chmod 600 ~/.402-mcp/wallet.nwc
# open ~/.402-mcp/wallet.nwc in an editor, paste the URI on one line, save

URI 由你的钱包服务提供，格式如下，请将占位符替换为你自己的值：

nostr+walletconnect://<wallet-pubkey-hex>?relay=<wss-relay-url>&secret=<secret-hex>

URI 需要包含 64 个字符的十六进制钱包公钥、1 到 8 个 relay 值，以及 64 个字符的十六进制 secret，还可以包含 lud16；其他任何参数都会被拒绝。文件必须是常规的非空文件，大小低于 8 KiB；在 macOS 和 Linux 上，若组用户和其他用户拥有任何权限，文件将被拒绝（chmod 600）。创建连接时，请授予 pay_invoice 权限并设置支出预算（授予 lookup_invoice 后，l402-reconcile 还可以向钱包查询结果未知的操作）。钱包必须支持 NIP-44 v2 加密。

然后使用绝对路径注册 402-mcp（运行命令时，shell 会展开 $HOME）：

claude mcp remove 402-mcp
claude mcp add 402-mcp -e NWC_URI_FILE="$HOME/.402-mcp/wallet.nwc" -e MAX_AUTO_PAY_SATS=1000 -- npx 402-mcp

对于 Claude Desktop 或 Cursor，请在同一个服务条目中添加 env 块。JSON 不会展开 ~ 或 $HOME，因此请写出你创建的文件的绝对路径：

{
  "mcpServers": {
    "402-mcp": {
      "command": "npx",
      "args": ["402-mcp"],
      "env": {
        "NWC_URI_FILE": "/absolute/path/to/.402-mcp/wallet.nwc",
        "MAX_AUTO_PAY_SATS": "1000"
      }
    }
  }
}

启动时会拒绝原始的 NWC_URI 变量。关于 Cashu、LNURLcash、完全不使用钱包以及首次付费调用，请参阅完整快速入门指南。

需要 Node.js 22.4 或更新版本。

工作原理

graph LR
    A["1. l402-config()"] --> B["2. l402-discover(url)"]
    B --> C["3. Agent reasons<br/>about pricing"]
    C --> D["4. l402-buy-credits()<br/>or l402-fetch(autoPay)"]
    E["5. l402-fetch(url)<br/>with stored credential"]
    D --> E
    E --> F["6. Data returned<br/>+ balance cached"]

会话示例：

Agent: "I need routing data from routing.example.com"

1. l402-config()
   -> nwcConfigured: true, maxAutoPaySats: 1000

2. l402-discover("https://routing.example.com/api/route")
   -> 10 sats/request, toll-booth detected, tiers available

3. Agent reasons: "I need ~20 requests. The 500-sat tier
   gives 555 credits. Better value."

4. l402-buy-credits(url, amountSats=500)
   -> Paid 500 sats, received 555 credits

5. l402-fetch("https://routing.example.com/api/route?from=...&to=...")
   -> 200 OK, route data, 545 credits remaining

第 5 步无需设置 autoPay：第 4 步已为该服务保存凭据，l402-fetch 会发送凭据。如果没有已保存的凭据，除非设置 autoPay: true，否则 l402-fetch 不会支付任何费用；它会改为返回价格和 paymentHash（参见支出限额）。

有关详细的架构和支付流程图，请参阅 docs/architecture.md。

配置

变量	默认值	描述
NWC_URI_FILE	-	包含 NWC bearer URI 的私有 0600 文件路径
CASHU_TOKENS	-	Cashu 令牌存储文件的路径。必须位于你的主目录中
LNURLCASH_NOTES	-	LNURLcash bearer 票据存储文件（LUD-25）的路径。必须位于你的主目录中
MAX_AUTO_PAY_SATS	1000	单笔自动付款的最高金额。超过此金额不会付款；挑战会返回给 Agent。0 表示禁用自动付款
MAX_SPEND_PER_MINUTE_SATS	10000	任意连续 60 秒内允许的自动支出金额。0 表示禁止所有自动付款。使用默认值时，以下每日上限会先触发（参见支出限额）
MAX_SPEND_PER_DAY_SATS	5000	任意连续 24 小时内允许的自动支出金额，记录在 ~/.402-mcp/spend-ledger.json 中，因此重启不会重置限额。0 表示禁止所有自动付款
CREDENTIAL_STORE	~/.402-mcp/credentials.json	持久化 macaroon/凭据存储。必须位于你的主目录中
TRANSPORT	stdio	传输模式：stdio 或 http
PORT	3402	HTTP 服务端口（当 TRANSPORT=http 时）
BIND_ADDRESS	127.0.0.1	HTTP 绑定地址
HTTP_AUTH_TOKEN_FILE	-	保存 bearer 令牌的私有 0600 文件，HTTP 客户端必须发送该令牌。TRANSPORT=http 时必填
HTTP_ALLOWED_HOSTS	-	HTTP 传输接受的额外 Host 标头值（逗号分隔），例如反向代理的名称
CORS_ORIGIN	disabled	HTTP 传输的 CORS 来源（* 或单个来源）。* 会记录警告：任何网站都可以调用该服务
TRANSPORT_PREFERENCE	onion,hns,https,http	多 URL 服务的首选传输顺序（逗号分隔）
TOR_PROXY	-	仅用于 .onion 地址的 SOCKS5 代理（例如 socks5h://127.0.0.1:9050）
SOCKS_PROXY	-	用于所有付费 API 请求的 SOCKS5 代理（例如 Tor 的 socks5h://127.0.0.1:9050）。设置此项或 TOR_PROXY，不要同时设置
HNS_GATEWAY_URL	https://query.hdns.io/	用于 Handshake 名称的 DNS-over-HTTPS 解析器。普通 DNS 无法解析的任何主机名都会在此查询
HUMAN_PAY_TIMEOUT_S	600	没有付款页面可供轮询时，人工付款方轮询服务以确认结算的时长，单位为秒
HUMAN_PAY_POLL_S	3	人工付款方的首次轮询间隔，单位为秒。间隔会逐渐增加至 30 秒
FETCH_TIMEOUT_MS	30000	每次出站 HTTP 请求的超时时间
FETCH_MAX_RETRIES	2	对非变更请求的重试次数。会改变资金状态的 POST 请求绝不重试
FETCH_MAX_RESPONSE_BYTES	10485760	可接受的最大响应正文（10 MiB）
SSRF_ALLOW_PRIVATE	false	允许请求私有地址和环回地址。仅限本地开发
ALLOW_INSECURE_TLS	false	当设置了 NODE_TLS_REJECT_UNAUTHORIZED=0 时确认相关风险。若未设置此项（或 SSRF_ALLOW_PRIVATE=true），402-mcp 在这种情况下会拒绝启动

启动时会拒绝 NWC_URI 和 HTTP_AUTH_TOKEN：这两个密钥只会从各自的 *_FILE 变量读取。支出限额、MAX_AUTO_PAY_SATS 和 FETCH_MAX_RETRIES 必须为非负整数；超时时间、大小限制和轮询间隔必须至少为 1；PORT 必须在 1 到 65535 之间。

传输方式的选择与回退

当 kind 31402 事件公布多个 URL（每种传输方式各一个）时，402-mcp 会根据你的配置选择最佳 URL：

1. 优先级优先：按 TRANSPORT_PREFERENCE 的顺序尝试 URL，默认值为 onion,hns,https,http。可用值为 onion、hns、https 和 http；其他值均无效。当 URL 的 TLD 为 .hns 时，会被视为 hns。如果 TLD 只是陌生的域名（如 .pub、.fyi），它更可能是 ICANN 域名，因此没有独立的优先级：它会被视为推测的 hns 域名，并在 hns 和 https 中排序靠后的那一种之后尝试；默认情况下，也就是在 https 之后。如果你从 TRANSPORT_PREFERENCE 中省略 hns，这类 URL 会最后尝试。
2. 能力筛选：除非设置了 TOR_PROXY 或 SOCKS_PROXY，否则会跳过 .onion URL，因此在没有代理时，默认顺序从 HNS 和 clearnet 开始。
3. 可用性回退：如果某种传输方式无法访问（连接被拒绝、超时），则会尝试下一个 URL。

服务可以通过不同传输方式公布同一服务的多个端点（定价和 macaroon 密钥相同）。这纯粹是为了抵御审查；切换传输方式时无需重新认证。.onion 端点需要 TOR_PROXY 或 SOCKS_PROXY。Handshake 端点无需配置，因为 HNS_GATEWAY_URL 有默认值；但在 SOCKS_PROXY 下除外，该设置会关闭 Handshake 查找（见 Tor 和 SOCKS5）。

跨传输方式使用凭据。 当向 l402-fetch 提供服务的 pubkey（来自 l402-search）时，它会以该公钥为键存储并查找凭据，因此一次购买即可用于 urls 中传入的所有传输方式 URL。如果没有提供 pubkey，凭据会以请求的来源为键。无论哪种情况，凭据都会记录其购买时经过的来源，且只会发送到这些来源，无论后续请求指定什么公钥。因此，通过 Tor 隐藏服务购买的 macaroon，在购买时两个 URL 都包含在 urls 中的情况下，也可用于 clearnet URL，并且绝不会发送到其他主机。

Tor 和 SOCKS5

• TOR_PROXY 通过代理发送 .onion 请求。其他所有连接都直接建立。
• SOCKS_PROXY 通过代理发送所有付费 API 请求，包括重定向。主机名由代理解析，而非本机解析，因此 Tor 代理会隐藏你的 IP 和你查询的名称。SSRF 防护仍会拒绝私有 IP 字面量和 localhost 等本地名称；它无法获知某个名称在远端解析出的地址，而 Tor 出口节点本来也会拒绝访问私有地址范围。

这两项设置都不涵盖钱包或发现流量：NWC 中继、Cashu 和 LNURLcash mint，以及 l402-search 查询所用的 Nostr 中继仍会直接连接。在 SOCKS_PROXY 下，Handshake 查找会关闭，因为 DNS-over-HTTPS 查询会绕过代理。

SOCKS5 支持由 undici 的 Socks5ProxyAgent 提供，Node 将其标记为实验性；配置代理时，预计 stderr 上会出现一条 ExperimentalWarning。

工具

Core L402（适用于任何服务）

工具	描述
l402-config	查看支付能力（钱包、限额、凭证数量）
l402-discover	探测端点，在不付款的情况下发现定价
l402-fetch-preview	查看端点的费用，无需付款；用于驱动付款确认小组件
l402-fetch	发起 HTTP 请求；设置 autoPay 且价格在限额内时，自动支付 402 挑战
l402-pay	按付款哈希支付 l402-fetch 或 l402-discover 返回的挑战。其他发票均需获得用户批准
l402-reconcile	列出或处理结果未知的付款；这些付款处理完毕前，暂停向对应服务自动付款
l402-credentials	列出已存储的凭证和缓存余额
l402-balance	查看某个服务的缓存额度余额
l402-search	在 Nostr 中继上发现 L402 服务（kind 31402 公告）
l402-store-token	存储从付款页面获取的 L402 令牌

小组件（MCP Apps 宿主）

工具	描述
l402-service-directory	可交互、可搜索的服务目录，列出通过 l402-search 找到的服务
l402-wallet-dashboard	可交互地查看钱包状态、限额和已存储的凭证

l402-fetch-preview 也提供付款确认小组件。

toll-booth 扩展

工具	描述
l402-buy-credits	浏览并购买批量折扣档位
l402-redeem-cashu	直接兑换 Cashu 令牌（无需经由 Lightning 往返）

参数和结果

* 表示必填参数。所有工具均以 JSON 文本响应；发生失败时会设置 MCP isError 标志。

工具	参数	返回值
l402-config	无	nwcConfigured、cashuConfigured、cashuBalanceSats、maxAutoPaySats、maxSpendPerMinuteSats、maxSpendPerDaySats、spentLast24HoursSats、credentialCount。不报告 LNURLcash 票据
l402-discover	url*、method（默认为 GET；也支持 POST、PUT、PATCH、DELETE、HEAD、OPTIONS）	url、costSats、invoice、macaroon、paymentHash；针对收费站还会返回 server 和 creditTiers。仅读取 L402 挑战，并缓存该挑战供 l402-pay 使用
l402-fetch-preview	url*、urls（批量，最多 10 个）、method、headers、pubkey	status（preview、free 或 error），以及 endpoint、protocol、costSats（x402 使用 costUsd）、paymentMethod（将用于付款的钱包）、paymentHash、expiresAt、message。提供 urls 时返回数组
l402-fetch	url*、urls（来自 l402-search 的所有传输 URL，最多 10 个）、pubkey（来自 l402-search）、method（与 l402-discover 相同）、headers（字符串对象）、body（字符串，最多 1,000,000 个字符）、autoPay（默认为 false）、maxCostSats（整数；降低此次调用的上限）、txHash（0x 加 64 个十六进制字符，用于已完成的 x402 付款）、paymentFlow（参见存储服务公告）。没有付款方式参数	已付款或免费：status、headers、body（标记为不可信内容）、creditsRemaining、satsPaid，以及在通过 IETF Payment、LNURLcash 或 xCashu 支付时的 paymentMethod。未付款挑战：status: 402、costSats、invoice、paymentHash、creditsExhausted、（如有提供）tiers、message。由人工付款：paymentUrl 或包含发票的二维码。失败时包含 paymentState（failed、unknown 或 blocked）或 error
l402-pay	paymentHash（来自 l402-fetch 或 l402-discover 挑战）、method（nwc、cashu、lnurlcash 或 human）、invoice 和 macaroon（仅适用于未生成挑战的发票；人工必须批准）	paid、paymentState（paid、failed、unknown 或 blocked）、credentialsStored、method，以及未成功时的 reason
l402-reconcile	paymentHash（64 个十六进制字符；省略则列出记录）、preimage（64 个十六进制字符）、abandon（布尔值；人工必须批准）	列表：unresolved（每项含 paymentHash、origins、costSats、protocol、method、createdAt）和 message。解决记录：paymentHash、resolved、state（settled、failed、pending 或 abandoned）、结算时的 credentialsStored、message
l402-credentials	无	credentials：每项包含 origin、origins、paymentHash、creditBalance、storedAt、lastUsed、server。绝不显示 Macaroon 和 preimage
l402-balance	origin*（URL，例如 https://api.example.com）	origin、creditsRemaining、lastUpdated、stale（超过 5 分钟时为 true）。如果该 origin 没有存储任何内容，则返回错误
l402-search	query*（最多 200 个字符）、topics（最多 10 个）、paymentMethod（公告 pmi 标签的第一个值：l402、cashu、xcashu、lnurlcash、x402 或 payment）、relays（最多 10 个 URL）、maxResults（1 到 100，默认 20）、timeout（1000 到 30000 ms，默认 5000）	服务数组：name、about、urls、pubkey、paymentMethods、pricing（capability、amount、unit）、topics、capabilities，以及存储服务的 storage。公告文本标记为不可信内容
l402-store-token	url、token（macaroon:preimage）	stored: true、origin，以及可从 macaroon 读取时的 paymentHash。如果 preimage 或 macaroon 格式错误，则返回错误
l402-buy-credits	url*（收费站服务）、amountSats（省略则列出套餐）、method（nwc、cashu 或 human）	不提供 amountSats 时：tiers。提供时：paid、amountSats、creditsReceived、credentialsStored、method；由人工付款时则改为返回二维码和 paymentHash
l402-redeem-cashu	url（收费站服务）、token（Cashu 令牌）	redeemed: true、creditsReceived、credentialsStored，以及在无法存储凭据时的 warning

支付方式

有两项独立选择决定如何支付 402：服务端发送了哪种质询；如果是 Lightning 发票，则由哪种付款方支付。

Lightning 发票的付款方。 对于 L402 或 IETF Payment 质询，l402-pay 和 l402-buy-credits 会按以下顺序使用第一个可用的付款方支付发票：

1. NWC（Nostr Wallet Connect）：完全自动；从已连接的钱包付款。设置了 NWC_URI_FILE 时可用。
2. Cashu：完全自动；熔解 ecash 令牌以支付发票。CASHU_TOKENS 存储中有余额时可用。
3. LNURLcash：完全自动；熔解 LUD-25 不记名票据以支付发票。LNURLCASH_NOTES 存储中有余额时可用。
4. 人工介入：仅在以上方式均不可用，或向 l402-pay 或 l402-buy-credits 传入 method: "human" 时使用。l402-fetch 不会等待：它会立即返回收费页面 URL，或二维码和发票。你从自己的钱包付款后，Agent 会调用 l402-pay，后者会轮询收费页面，最长等待 120 秒（如果没有付款页面，则轮询服务端的 /invoice-status/<hash> 端点，等待 HUMAN_PAY_TIMEOUT_S 秒）。只有服务端报告付款结算时才能确认结算；收费服务支持此功能，其他 L402 服务则不支持。如果价格高于 MAX_AUTO_PAY_SATS，人工付款方也不会接手：质询会以未付款状态返回给 Agent。

每笔付款只会选择一种付款方，且不会回退：如果付款失败，会报告失败，不会尝试下一个付款方。若要使用其他付款方，可向 l402-pay 传入 method（nwc、cashu、lnurlcash 或 human），或向 l402-buy-credits 传入 method（nwc、cashu 或 human）。l402-fetch 没有支付方式参数。你也可以只配置所需的方式。

服务端发送的质询。 l402-fetch 可处理四种 HTTP 402 质询变体，以及一种实验性的 x402 格式。当响应携带多种质询时，它会按下表顺序检查，并使用第一个可处理的质询。每种支付渠道都仍需满足 autoPay: true，且价格在限制范围内。

顺序	协议	质询标头	支付
1	LNURLcash（LUD-25）	X-LNURLcash: lnurlcashreq1…	从票据存储中取出不记名票据并直接交付（需要 LNURLCASH_NOTES）。不会经过上述付款方顺序
2	xCashu（NUT-18）	X-Cashu: creqA…	直接从 Cashu 存储中发送 ecash 令牌（需要 CASHU_TOKENS）。不会经过付款方顺序
3	x402（实验性自定义格式）	X-Payment-Required: x402 + JSON 正文	这是自定义格式，并非 x402 规范（该规范的服务端会发送 base64 编码的 PAYMENT-REQUIRED 标头），因此不支持真正的 x402 服务。支付详情会显示给用户，由用户从自己的钱包付款
4	IETF Payment（draft-ryan-httpauth-payment-01）	WWW-Authenticate: Payment	Lightning 发票，由上述付款方顺序中的付款方支付
5	L402	WWW-Authenticate: L402	Lightning 发票，由上述付款方顺序中的付款方支付

LNURLcash 会优先检查，因为不记名票据本身就是现成的资金，使用它付款无需经过 Lightning 跳转，也无需在铸币厂进行兑换：票据会直接放入重试标头，由服务端完成结算。如果价格与票据金额不完全相符，则会在铸币厂拆分一张票据，找零留在存储中。如果没有票据能覆盖费用，或未配置票据存储，则会照常尝试同一响应中的其余质询。上方列表中的 LNURLcash 付款方是另一条路径：它会熔解票据以支付 Lightning 发票。 l402-fetch-preview 会报告找到的挑战，但不会付款；它还会指出将用于付款的钱包（paymentMethod）。它检查挑战类型的顺序与 l402-fetch 不同（IETF Payment、L402、LNURLcash、xCashu、x402），因此，对于一次发送多种挑战的服务器，预览可能会显示与 l402-fetch 使用的支付方式不同的支付方式。

支出限额

402-mcp 会针对以下限额检查每笔自动付款，Agent 可通过 l402-config 查看这些限额：

• MAX_AUTO_PAY_SATS 限制每笔付款的金额。超出此金额的挑战会以未付款状态返回给 Agent。设为 0 可关闭自动付款：所有收费挑战都会返回给 Agent。
• l402-fetch 的 maxCostSats 会为单次调用进一步降低此限额，因此 l402-fetch-preview 显示的价格具有约束力，绝不会提高限额。
• MAX_SPEND_PER_MINUTE_SATS 和 MAX_SPEND_PER_DAY_SATS 限制滚动时间窗口内的自动支出总额。每日窗口会持久保存，因此重启服务不会重置该限额。任一项设为 0 都会完全阻止自动付款。使用默认值（每分钟 10,000，每天 5,000）时，每日限额较低；每分钟的支出也会计入每日限额，因此除非调低每分钟限额或调高每日限额，否则每分钟限额不会生效。
• 如果付款结果未知，系统会暂停对该服务的自动付款，直到 l402-reconcile 解决问题，避免重复购买同一项内容。

真正的硬性限额是 NWC 连接上的预算。 上述所有限制都是由运行所在机器上的此进程通过软件强制执行的。大多数 NWC 钱包都允许你在创建连接时设置支出预算；请务必设置，因为这是 bug 或行为异常的 Agent 无法提高的限额。对于 Cashu 和 LNURLcash，硬性限额取决于你存放在令牌或票据库中的金额。

隐私

402-mcp 只会在你的机器本地存储凭据（~/.402-mcp/credentials.json，静态数据使用 AES-256-GCM 加密）。如果系统提供密钥链，加密密钥会存放其中（macOS 上通过 security 工具使用 Keychain；其他系统则使用可选的 keytar 模块，但该模块在当前版本的 Node 上通常无法加载）。否则，密钥会回退到文件 ~/.402-mcp/encryption.key，并以 0600 权限创建；如果密钥链不可用，402-mcp 会在启动时发出警告。任何能读取该文件的人都可以解密凭据库。402-mcp 没有账号、跟踪或分析功能，也没有自己的服务。不过，它确实会与所调用 API 之外的其他方通信：

• Nostr 中继。 l402-search 会订阅公共中继（默认包括 relay.damus.io、relay.primal.net 和 nos.lol）以获取服务公告，并且只会发送你提供的主题筛选条件。支付方式筛选条件和查询文本会在本地匹配，因此中继永远不会看到它们。
• Handshake 解析器。 如果普通 DNS 无法找到主机名，系统会向 HNS_GATEWAY_URL（默认为 https://query.hdns.io/）查询，因此该服务会看到该名称。使用 SOCKS_PROXY 时会关闭此功能。
• 钱包服务。 NWC 中继、Cashu 铸币方和 LNURLcash 铸币方会看到你通过它们进行的付款。

付款使用 Lightning 或 ecash，这些方式是化名的，而非匿名的。

在代码中使用模块

该软件包公开了九个子路径导入。每个导入都映射到 build/<path>.js，其声明文件也位于旁边，因此 TypeScript 无需 types 字段即可找到类型：

导入	内容
402-mcp/tools/*	工具处理程序和 register*Tool 函数，例如 402-mcp/tools/fetch
402-mcp/l402/*	parse、detect、bolt11、challenge-cache
402-mcp/x402/*、402-mcp/xcashu/*、402-mcp/xlnurlcash/*、402-mcp/ietf-payment/*	各种支付渠道的挑战解析器和支付辅助函数
402-mcp/store/*	凭据、Cashu 令牌、LNURLcash 票据和待处理支付的存储
402-mcp/fetch/*	弹性 fetch、SSRF 防护、传输选择、SOCKS 和 Handshake 解析
402-mcp/spend-tracker	SpendTracker

这些是服务自身的模块，按原样公开；请阅读 src/ 了解其签名。不要在库代码中导入软件包根路径（402-mcp）：main 和 . 导出都指向服务入口 build/index.js，导入时会从环境加载配置并连接传输。

import { SpendTracker } from '402-mcp/spend-tracker'
import { parseL402Challenge } from '402-mcp/l402/parse'

const tracker = new SpendTracker()
console.log(tracker.tryRecord(50, 10_000)) // true: 50 sats fits under a 10,000 sat per-minute cap

const challenge = parseL402Challenge('L402 macaroon="AgEEbG5kcg==", invoice="lnbc10n1pexample"')
console.log(challenge) // { macaroon: 'AgEEbG5kcg==', invoice: 'lnbc10n1pexample' }

存储服务公告（Wildbloom）

l402-search 还会返回使用 forgesworn-storage-service-v1 配置文件公告的存储服务（kind 31402，由 402-announce/storage 2.3.0 验证）。Wildbloom 就是此类服务之一：它提供付费存储，以及名为 free shelter 的免费层级。该层级会尽力保留经授权镜像推送的副本，可能会驱逐这些副本，并且不接受来自未知用户的直接上传。

这些结果仅用于描述。付费存储结果带有 storage.paymentFlow: "wildbloom-checkout-v1" 和 autoPaySupported: false，402-mcp 无法购买该服务。不要将此支付流程交给 l402-fetch 或 l402-pay：两者都会拒绝它；l402-fetch 还会在进行任何网络、凭据或钱包访问之前，拒绝任何 /checkout/v1 路径。如需购买，请阅读运营方当前的条款（其 /services/v1 列表），并使用 Wildbloom 自有的结账流程；该流程会要求提供使用 NIP-98（Nostr HTTP 身份验证）签名的私密报价，并由你明确付款。将内容镜像到 free shelter 也不是这些工具提供的功能。公告中的条款是运营方自己的声明，不代表推荐，也不能证明服务持续运行；有效签名只能表明发布者身份，绝不授权购买。

结果的筛选方式：搜索只会联系你指定的中继（或默认中继），不会联系存储节点或钱包。对每项服务（发布者相同且 d 标签相同），会先选出最新的有效签名公告（时间戳相同时选择事件 ID 最低者），然后再应用过期、撤回和查询筛选条件。为避免中继重放旧副本而让已撤回或已过期的报价重新生效，每项服务所见的最新记录都会作为水位线保留在内存中：每个搜索处理程序最多保留 2,000 条，并在多次调用间持续保留，直到服务重启；若搜索会超出该上限，则会报错，而不会丢弃任何记录。新启动的服务没有水位线，因此无法知道中继未提供的记录。仍然有效但已满或已暂停的列表仍会出现在结果中；已过期和已撤回的列表会继续作为水位线保留，但不会返回。发现功能不会在磁盘上存储任何内容，也不会打开浏览器。

生态系统

在 402.pub 浏览实时 L402 服务，这是一个用于支付门控 API 的去中心化市场。

项目	角色
toll-booth	与支付后端无关的 HTTP 402 中间件
satgate	按 Token 付费的 AI 推理代理（基于 toll-booth 构建）
402-mcp	MCP 客户端：AI Agent 可发现、付费并调用 L402 API
402-announce	在 Nostr 上发布 L402 服务，实现去中心化发现

402-mcp 是 Lightning Labs lightning-agent-tools 的与钱包提供商无关的替代方案：无需 Lightning 节点，支持多个钱包，并可加密凭证。

完整对比

	402-mcp	Lightning Labs agent tools
付款方式	NWC + Cashu + LNURLcash + 人工回退	仅 Lightning
是否需要节点？	否，可连接任意 NWC 钱包	是，运行 LND
服务兼容性	任意 L402 服务	主要面向 Aperture
支出安全性	单笔付款上限、单次调用最高费用、滚动 60 秒和持久化 24 小时窗口	单次调用最高费用（--max-cost）
凭证存储	静态加密（AES-256-GCM）	文件权限
隐私	无 PII、SSRF 防护、错误信息清理	标准

Lightning Labs 的支出安全单元格信息来自 lightning-agent-tools 中的 lnget 文档：--max-cost 用于设置 lnget 对单个请求自动付款的最高金额（docs/l402-and-lnget.md），该页面未说明跨请求预算。此列中的其他单元格信息并非来自此处。

如果你希望 Agent 运行自己的 Lightning 节点，请使用 Lightning Labs 的工具。如果你希望 Agent 无需基础设施即可使用任意钱包付款，请使用 402-mcp。

开发环境设置和指南请参阅 CONTRIBUTING.md。

---

由 @forgesworn 构建。

• Lightning 打赏：[email protected]
• Nostr：npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2

---

ForgeSworn 工具包的一部分

ForgeSworn 为 Nostr 构建开源加密身份、支付和协作工具。

库	功能
nsec-tree	确定性子身份派生
ring-sig	基于 secp256k1 的 SAG/LSAG 环签名
range-proof	Pedersen 承诺范围证明
canary-kit	抗胁迫口头验证
spoken-token	可口述的验证 Token
toll-booth	L402 支付中间件
geohash-kit	支持多边形覆盖的 Geohash 工具包
nostr-attestations	NIP-VA 可验证证明
dominion	基于 Epoch 的加密访问控制
nostr-veil	保护隐私的信任网络

许可证

MIT