SaturnZap

一款轻量、命令行优先、非托管的闪电网络钱包，专为自主 AI Agent 打造。
自主掌控。运行自己的闪电节点。无需完整的 Bitcoin 节点。

# One-line install (handles uv + the vendored ldk-node wheel)
curl -LsSf https://raw.githubusercontent.com/lqwdtech/SaturnZap/main/install.sh | sh

export SZ_PASSPHRASE="your-secure-passphrase"
sz setup --auto                  # Generate seed + start node + pick LQWD peer
sz service install               # Keep the node running across reboots
sz connect-info --check          # Share the URI with peers/LSPs

uv tool install saturnzap \
  --find-links https://github.com/lqwdtech/SaturnZap/releases/expanded_assets/v1.4.1

sz pay --invoice lnbc1... --max-sats 500
sz fetch https://api.example.com/data --max-sats 100

什么是 SaturnZap？

SaturnZap 是一款开源闪电钱包，从设计之初就面向无需人工监督运行的 AI Agent。 Agent 安装 SaturnZap，初始化自己的闪电节点，与网络上的任意节点建立通道，发送和接收 Bitcoin 付款，并自主支付受 L402 保护的 API 费用。

SaturnZap 是一款命令行工具。它不是托管钱包、托管服务，也不是 Web 应用。密钥保存在 Agent 的设备上。Agent 就是闪电节点。

两种集成方式：

• 命令行 — 从任何语言调用 sz 命令，并解析标准输出中的 JSON
• MCP 服务 — 通过模型上下文协议（stdio）直接连接 AI Agent

文档： 详细指南请参阅 docs/ 文件夹，内容包括 快速入门、 配置、 MCP 服务集成、 架构和 JSON API 参考。

商业模式

SaturnZap 分为两个层次：

命令行工具 — 开源（MIT）

sz 命令行工具免费提供，并基于 MIT 许可证开源。任何人都可以 安装、分叉、审计并基于它构建。软件本身无需支付许可费，也不需要 API 密钥 即可使用，并且没有遥测功能。

LQWD（LSP）

SaturnZap 已预先配置为默认使用 LQWD Technologies，作为其默认 闪电服务提供商（LSP）。LQWD 在 18 个国家/地区运营着 18 个闪电节点，拥有深厚的全球通道流动性。

Agent 使用 LQWD 的基础设施时，LQWD 通过以下方式获利：

• 路由费用 — 付款经由 LQWD 节点路由时赚取的 sats
• 通道租赁 — 为 Agent 开通通道并提供入站流动性所收取的费用
• 托管连接服务 — 为有需要的 Agent 提供高级对等连接和可靠性保障

LQWD 是默认选项，而非使用要求。Agent 可以与闪电网络上的任意节点建立通道。 SaturnZap 从不强制使用 LQWD。LQWD 凭借服务质量竞争——覆盖 18 个国家/地区、流动性充足、通道开通迅速—— 而非依靠用户锁定。

这种模式类似于带云后端的开源软件：工具免费，基础设施才是业务所在。

关键特性

• 非托管 — BIP39 助记词存储在 Agent 的机器上，并经过加密。SaturnZap 绝不会 持有、传输或访问私钥。
• 无需运行完整的 Bitcoin 节点 — Esplora REST API 提供链上数据，并自动回退 （LQWD → blockstream.info → mempool.space）。无需 bitcoind。
• 不依赖特定对等节点 — 可与任意 Lightning 节点建立通道。LQWD 是默认的智能选择，覆盖全球， 但 Agent 完全自主控制对等节点关系。
• JSON 优先 — 每条命令都会将结构化 JSON 写入 stdout。错误会写入 stderr。 从一开始就专为机器读取而设计。
• 原生支持 MCP — 内置 MCP 服务通过 stdio 暴露 25 个工具。只需一个配置块，即可连接 Claude、 Cursor、VS Code 或任何兼容 MCP 的 Agent。
• 自主运行 — 正常运行时不会显示交互式提示。专为在 Agent 运行时、Shell 脚本和编排流水线中运行而设计。（除非传入 --yes， 否则 Mainnet 上的支出命令会要求确认。）

架构

完整架构详情：docs/architecture.md

组件图

┌─────────────────────────────────────────────────────────┐
│                    Integration Layer                    │
│                                                         │
│  sz CLI          MCP Server         OpenClaw Skill      │
│  (typer)         (FastMCP/stdio)    (gateway)           │
│      │               │                  │               │
│      └───────────────┼──────────────────┘               │
│                      │                                  │
│              ┌───────▼───────┐                          │
│              │  IPC Client   │  (auto-detect daemon)    │
│              └───────┬───────┘                          │
└──────────────────────┼──────────────────────────────────┘
                       │ Unix Domain Socket (sz.sock)
┌──────────────────────▼──────────────────────────────────┐
│           Daemon (sz start — foreground, blocks)         │
│                                                         │
│  IPC Server (asyncio) ─── Wallet Core                   │
│  23 JSON methods          node.py, payments.py, l402.py │
│  threading.Lock           liquidity.py, keystore.py     │
│  0600 socket perms        lqwd.py, config.py, output.py │
│                           ipc.py                        │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│                    LDK Node                             │
│  - Full Lightning protocol implementation               │
│  - Esplora chain sync (LQWD → blockstream → mempool)   │
│  - BIP39 key management                                 │
│  - Peer connections and channel state machine           │
└──────────────┬────────────────────────┬─────────────────┘
               │                        │
┌──────────────▼──────────┐  ┌──────────▼──────────────────┐
│   LQWD Global Nodes     │  │   Any Lightning Node        │
│   (default — 18 nodes,  │  │   (agent can peer with      │
│   18 countries, deep    │  │   any public node on the    │
│   liquidity, LSPS)      │  │   Lightning Network)        │
└─────────────────────────┘  └─────────────────────────────┘

关键设计决策

Unix 域套接字 IPC

守护进程（sz start）拥有 LDK 节点，并通过 Unix 域套接字在 ~/.local/share/saturnzap/<network>/sz.sock 上暴露 23 个方法。CLI 命令、MCP 服务和 OpenClaw 会自动检测守护进程并通过 IPC 转发请求，不会发生端口冲突，也不会锁定数据库。如果没有运行中的守护进程，命令会回退到启动 临时节点。

使用 Esplora 同步链数据，并支持回退

LDK Node 通过 Esplora（区块浏览器 REST API）同步链上数据。无需外部 Bitcoin 节点。SaturnZap 内置备用链端点：如果主 Esplora 服务无法访问，会自动探测备用服务（LQWD、blockstream.info、mempool.space） 并连接到第一个可用端点。全新安装后的首次同步需要几分钟，之后启动几乎是即时的。

将 LQWD 设为默认 LSP

在 Mainnet 上，全新安装默认与 LQWD-AI-Grid 建立对等连接——这是 LQWD 面向 Agent 的 LSP 节点，支持 LSPS1 和 LSPS2（JIT 通道）。节点会在首次与对等节点连接时自动回开通道，因此新钱包无需先准备链上资金， 即可开始接收入站流动性。仍内置并提供覆盖 18 个区域的服务节点：设置 SZ_REGION=NEAREST，即可 回退到基于时区的选择方式（例如，从 UTC 时区选择 LQWD-England，从 JST 时区选择 LQWD-Japan）；也可设置 SZ_REGION=CA 或 --region CA 来固定特定区域。

初始化后不依赖特定对等节点

初始通道建立后，Agent 可使用标准 Lightning 通道开启流程与任意对象建立对等连接。SaturnZap 没有会刻意优先选择 LQWD 的路由逻辑——Lightning 寻路会选择最佳路由。由于 LQWD 节点在 18 个国家/地区具有良好的连接性和容量，它们自然会成为吸引人的路由选择。

JSON 优先，默认非交互式运行

所有命令都专为非交互式执行而设计。不会使用影响管道解析的加载动画。在 TTY 中传入 --pretty 可获得便于人阅读的输出。默认始终输出干净的 JSON。

为安全起见，只有一个例外：Mainnet 上的支出命令（send、pay、keysend、 channels open）会显示 [y/N] 确认提示。在自动化场景中，可通过 --yes 或 SZ_MAINNET_CONFIRM=yes 跳过该提示。Signet 和 Testnet 不会提示确认。

自主管理通道

SaturnZap 会监控通道健康状况。完成配置后，当出站流动性低于阈值时，它会自动开启新通道；需要入站流动性时，则会向 配置的 LSP 请求。Agent 可以无限期运行，无需人工干预。

技术栈

LQWD 节点目录

作为可信的默认对等节点嵌入 SaturnZap。在运行 sz init 或 sz channels open --lsp lqwd 时， 系统会比较 UTC 时差与各节点所在时区，自动选择距离最近的节点——时差最小的节点胜出。可通过 SZ_REGION 环境变量或 --region 标志覆盖。完整公钥和连接字符串位于 src/saturnzap/lqwd.py。

完整公钥和 host:port 连接字符串位于 src/saturnzap/lqwd.py。 用于开发的 Signet/testnet 节点详细信息单独维护。

CLI 参考

完整 JSON API 参考：docs/json-api-reference.md

二进制文件： sz

所有命令均将 JSON 输出到 stdout。发生错误时以代码 1 退出，并将错误写入 stderr。

全局选项：

sz --network bitcoin|signet|testnet <command>   # Select Bitcoin network (default: bitcoin)
sz --pretty <command>                             # Pretty-print JSON output

节点

sz init                          # Generate seed, start node, peer with nearest LQWD node
sz init --for-lqwd-faucet        # Mainnet preset: sets a readable alias for LQWDClaw
sz setup                         # Guided first-run: init + address (idempotent)
sz setup --auto                  # Non-interactive: init + address + request inbound from LQWD
sz start                         # Foreground daemon — blocks until SIGTERM/SIGINT (systemd-friendly)
sz start --foreground            # Legacy: print status and exit (non-persistent)
sz stop                          # Stop the node daemon
sz stop --close-all              # Cooperatively close all channels, then stop
sz status                        # Node pubkey, sync state, peer/channel counts
sz connect-info --check          # Connection URI + external reachability probe

钱包

sz address                       # New on-chain receiving address
sz send <address>                # Send all on-chain sats to address
sz send <address> -a 50000       # Send specific amount on-chain
sz send <address> --yes          # Skip mainnet confirmation prompt
sz balance                       # Onchain + lightning balances, per-channel breakdown
sz transactions --limit 20       # Payment history

对等节点

sz peers list
sz peers add <pubkey>@<host>:<port>
sz peers remove <pubkey>

# Anchor-reserve waiver / 0-conf — applied on next node start.
# The LQWD fleet is trusted by default on mainnet.
sz peers trust <pubkey>
sz peers untrust <pubkey>
sz peers trusted-list

配置

sz config list                         # Show current config + known keys
sz config get node.alias
sz config set node.alias "my-agent"    # Persists to ~/.config/saturnzap/config.toml
sz config set node.listen_port 9735
sz config unset esplora_url

通道

sz channels list

# Open to any node
sz channels open --peer <pubkey>@<host>:<port> --amount-sats 100000

# Open via LQWD — nearest node automatically selected
sz channels open --lsp lqwd --amount-sats 100000

# Open via LQWD in a specific region
sz channels open --lsp lqwd --region JP --amount-sats 100000

# Skip mainnet confirmation (for automation)
sz channels open --lsp lqwd --amount-sats 100000 --yes

# Force a private channel (default is auto-announce when reachable)
sz channels open --lsp lqwd --amount-sats 100000 --no-announce

sz channels close --channel-id <id>
sz channels close --channel-id <id> --force

# Wait for a channel to become usable (blocks until ready or timeout)
sz channels wait --channel-id <id> --timeout 300

支付

sz invoice --amount-sats 1000 --memo "for data"
sz invoice --amount-sats 1000 --wait    # Block until paid or expired
sz pay --invoice lnbc1...
sz pay --invoice lnbc1... --max-sats 500    # spending cap for agent safety
sz pay --invoice lnbc1... --yes             # skip mainnet confirmation
sz keysend --pubkey <pubkey> --amount-sats 100
sz keysend --pubkey <pubkey> --amount-sats 100 --yes

L402 — 自主 API 支付

# Auto-detects HTTP 402, pays invoice, retries request, returns body
sz fetch https://api.example.com/data

# With per-request spending cap
sz fetch https://api.example.com/data --max-sats 100

# With custom headers
sz fetch https://api.example.com/data --header "X-Custom: value"

流动性

sz liquidity status
sz liquidity request-inbound --amount-sats 500000

服务管理

sz service install               # Install + start systemd unit (recommended for persistence)
sz service status                # Check service status
sz service uninstall             # Stop and remove systemd service

安装后，LDK 节点会在重启后继续运行，每条 sz 命令都会通过守护进程的 IPC 套接字路由——无需为每条命令单独启动。

MCP 服务

sz mcp                           # Start MCP server on stdio (for AI agent integration)

也可使用独立入口点：

sz-mcp                           # Same as sz mcp

Agent 配置（Claude Desktop、Cursor、VS Code 等）：

{
  "mcpServers": {
    "saturnzap": {
      "command": "sz",
      "args": ["mcp"],
      "env": {
        "SZ_PASSPHRASE": "your-passphrase"
      }
    }
  }
}

MCP 服务提供 25 个工具，涵盖节点生命周期、钱包、对等节点、通道、支付、L402 获取和流动性管理。设置 SZ_MCP_MAX_SPEND_SATS 可调整其默认的每次请求 1,000-sat 上限；SZ_MCP_DAILY_SPEND_SATS 可调整持续生效的滚动每日 10,000-sat 上限。限额包含路由费用，并会通过守护进程跟踪请求。新建 MCP 钱包需要由操作者配置私密助记词备份，扫款则需要明确授权。 请参阅支出策略和 1.4.0 升级指南。

JSON 输出格式

sz balance

{
  "status": "ok",
  "network": "signet",
  "onchain_sats": 0,
  "lightning_sats": 45000,
  "channels": [
    {
      "channel_id": "abc123",
      "peer_pubkey": "036491...",
      "peer_alias": "LQWD-Canada",
      "capacity_sats": 100000,
      "outbound_sats": 45000,
      "inbound_sats": 55000,
      "state": "open"
    }
  ]
}

sz pay

{
  "status": "ok",
  "network": "signet",
  "payment_hash": "def456...",
  "amount_sats": 1000,
  "fee_sats": 1,
  "duration_ms": 342
}

sz fetch（L402 流程）

{
  "status": "ok",
  "network": "signet",
  "url": "https://api.example.com/data",
  "payment_hash": "ghi789...",
  "amount_sats": 10,
  "fee_sats": 1,
  "http_status": 200,
  "body": {}
}

错误（任何命令）

{
  "status": "error",
  "code": "INSUFFICIENT_OUTBOUND_LIQUIDITY",
  "message": "Not enough outbound liquidity. Available: 200 sats, required: 1000 sats."
}

退出代码

项目结构

/
├── README.md
├── LICENSE                        # MIT
├── pyproject.toml                 # Package definition, sz entry point
├── uv.lock
├── .env.example                   # Environment variable template
│
├── docs/
│   ├── getting-started.md         # Installation and first-run guide
│   ├── configuration.md           # Config file and env var reference
│   ├── mcp-server.md              # MCP server setup and tool reference
│   ├── architecture.md            # Design decisions and component map
│   └── json-api-reference.md      # Full JSON shapes for all commands
│
├── src/
│   └── saturnzap/
│       ├── __init__.py
│       ├── cli.py                 # Typer app — all sz commands
│       ├── node.py                # LDK Node lifecycle + channels + peers
│       ├── payments.py            # Send / receive / invoice / keysend
│       ├── l402.py                # L402 HTTP interceptor
│       ├── liquidity.py           # Channel health scoring + recommendations
│       ├── keystore.py            # BIP39 seed, Fernet encryption
│       ├── lqwd.py                # LQWD node directory (18 regions)
│       ├── config.py              # Config paths, Esplora fallback, TOML loader
│       ├── mcp_server.py          # MCP server — 25 tools for AI agents
│       ├── service.py             # Systemd service generator
│       └── output.py              # JSON output, TTY detection, --pretty
│
├── tests/
│   ├── test_cli.py                # CLI smoke tests
│   ├── test_keystore.py           # Seed encryption
│   ├── test_node.py               # Node lifecycle + channel rejection
│   ├── test_ipc.py                # IPC layer
│   ├── test_payments.py           # Payment helpers
│   ├── test_l402.py               # L402 parsing
│   ├── test_liquidity.py          # Health scoring
│   ├── test_config.py             # Config + env vars
│   ├── test_mcp_server.py         # MCP server
│   ├── test_backup.py             # Backup/restore
│   ├── test_service.py            # Systemd service
│   ├── test_lqwd.py               # LQWD directory
│   ├── test_output.py             # JSON output
│   ├── integration/               # Multi-command flows
│   ├── security/                  # Input validation, spending guards
│   ├── reliability/               # Edge cases, concurrency
│   ├── ux/                        # Agent workflow scenarios
│   └── live/                      # Droplet tests (@live marker)
│
├── skills/
│   └── saturnzap/
│       ├── SKILL.md               # OpenClaw skill definition
│       └── references/
│           └── json-contracts.md  # Full JSON output reference
│
├── vendor/
│   └── ldk_node-0.7.0.post1-py3-none-linux_x86_64.whl  # LDK Node Python bindings (Linux x86_64)
│
├── security/
│   ├── security_scan.py
│   └── profiles/
│       └── saturnzap.yaml
│
├── hooks/
│   ├── pre-commit
│   └── pre-push
│
└── .github/
    └── workflows/
        ├── ci.yml                 # Lint + test on push/PR
        └── publish.yml            # PyPI publish on version tags

开发环境

Droplet 设置

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Clone and install
git clone https://github.com/lqwdtech/SaturnZap
cd saturnzap
uv venv
source .venv/bin/activate
uv sync

# Run
sz --help

从 PyPI 安装

# Quick path: one-line installer (handles uv + the vendored ldk-node wheel)
curl -LsSf https://raw.githubusercontent.com/lqwdtech/SaturnZap/main/install.sh | sh

# Manual path: ldk-node is not yet on PyPI — use --find-links to pull it from GitHub Releases
pip install saturnzap --find-links https://github.com/lqwdtech/SaturnZap/releases/expanded_assets/v1.4.1

# Or with uv
uv pip install saturnzap --find-links https://github.com/lqwdtech/SaturnZap/releases/expanded_assets/v1.4.1

开发阶段

阶段 1 — 节点基础 ✅

sz init、sz start、sz stop、sz status

生成 BIP39 种子，加密存储，启动 LDK Node，同步 Esplora 链， 自动连接到最近的 LQWD 节点，提供 JSON 输出基础设施。

阶段 2 — 通道管理 ✅

sz channels、sz peers、sz address、sz balance

与任意节点开启通道。由 LQWD LSP 协助开启通道。内置 LQWD 节点目录（覆盖 18 个地区，按时区自动选择）。当节点可从互联网访问时，默认将通道公布到公开 Gossip 图谱，让 Agent 自动成为公开路由节点。查看通道列表并关闭通道。

阶段 3 — 支付 ✅

sz invoice、sz pay、sz keysend、sz transactions

完整支持 BOLT11 发送和接收。可变金额发票。Keysend。支持排序和分页的交易历史记录。

阶段 4 — L402 ✅

sz fetch

支持检测 402、提取发票、自动支付和重试请求的 HTTP 客户端。支持为每个请求设置支出上限。缓存令牌，避免对同一资源重复付费。

阶段 5 — 流动性智能管理 ✅

sz liquidity

监控通道健康状况并以 0–100 分评分。提供可执行的建议。通过 LQWD 请求入站流动性。可根据地理位置从 18 个地区选择对等节点。

阶段 6 — 打包与集成 ✅

pip install saturnzap / uv add saturnzap / sz mcp

包含 25 个工具的 MCP 服务。Esplora 回退链。GitHub Actions CI/CD。 PyPI 打包。OpenClaw 技能定义。安全扫描器（Grade A+）。

阶段 7 — 主网支持 ✅

sz --network bitcoin

可通过 CLI 标志（--network signet|testnet|bitcoin）、config.toml 或默认值选择网络。按网络命名的数据目录可隔离各网络的钱包。在主网包含真实的 LQWD 节点目录（18 个节点）。执行支出命令时会显示主网安全确认提示，可使用 --yes 标志或 SZ_MAINNET_CONFIRM=yes 跳过。所有 JSON 响应均包含网络字段。

即将推出

• 发布到 PyPI（可信发布者工作流已就绪）
• Docker 镜像
• OpenClaw ClawHub 列表

负责任地使用

SaturnZap 是非托管软件。你持有自己的密钥，并对自己的资金负全部责任。该软件依据 MIT 许可证按“原样”提供，适用通常的开源条款。以下是几点实用建议：

• 熟悉工具期间，在主网上从小额资金开始使用。
• 将种子短语备份到安全的离线位置。没有它就无法恢复。
• 开发和集成测试时使用 --network signet — signet 币免费，且与主网钱包隔离。
• 运行自主 Agent 时设置支出上限（--max-sats、SZ_CLI_MAX_SPEND_SATS、SZ_MCP_MAX_SPEND_SATS）。

有关威胁模型和披露政策，请参阅 SECURITY.md。

许可证

MIT 许可证。请参阅 LICENSE。

SaturnZap CLI 免费且开源。LQWD 基础设施服务为商业服务。 将 SaturnZap 与非 LQWD 对等节点配合使用，无需与 LQWD Technologies 达成任何协议。

关于 LQWD

LQWD Technologies Corp（TSXV: LQWD | OTCQX: LQWDF）是一家上市的 Lightning Network 基础设施公司。LQWD 在 18 个国家运营 18 个 Lightning 节点，为基于 Bitcoin Lightning Network 构建产品的 Agent 和开发者提供路由基础设施、流动性服务和 LSP 连接。

• 公司：https://lqwdtech.com
• Agent 端点：https://lqwd.ai
• 网络：18 个节点、18 个国家、1,600 多个通道