SaturnZap

A lightweight, CLI-first, non-custodial Lightning Network wallet built for autonomous AI agents.

Self-sovereign. Runs its own Lightning node. No full Bitcoin node required.

# 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

Or install with uv tool directly

uv tool install saturnzap \

--find-links https://github.com/lqwdtech/SaturnZap/releases/expanded_assets/v1.4.1

The --find-links flag is required because ldk-node==0.7.0.post1 is not yet on PyPI; the SaturnZap GitHub Release ships the vendored wheel.

sz pay --invoice lnbc1... --max-sats 500

sz fetch https://api.example.com/data --max-sats 100

---

What is SaturnZap?

SaturnZap is an open-source Lightning wallet designed from the ground up for AI agents operating without human supervision. The agent installs SaturnZap, initializes its own Lightning node, opens channels to any peer on the network, sends and receives Bitcoin payments, and autonomously pays for L402-gated APIs.

SaturnZap is a CLI tool. It is not a hosted wallet, not a custodial service, and not a web application. Keys live on the agent's machine. The agent IS the Lightning node.

Two ways to integrate:

• CLI — call sz commands from any language, parse JSON from stdout
• MCP Server — connect AI agents directly via Model Context Protocol (stdio)

Documentation: See the docs/ folder for detailed guides on

getting started,

configuration,

MCP server integration,

architecture, and

JSON API reference.

---

Business Model

SaturnZap has two layers:

CLI — Open Source (MIT)

The sz command-line tool is free and open source under the MIT license. Anyone can install it, fork it, audit it, and build on it. There is no licensing fee, no API key required to use the software itself, and no telemetry.

LQWD (LSP)

SaturnZap ships pre-configured to use LQWD Technologies as its default Lightning Service Provider (LSP). LQWD operates 18 Lightning nodes across 18 countries with deep global channel liquidity.

When an agent uses LQWD's infrastructure, LQWD earns through:

• Routing fees — sats earned as payments route through LQWD nodes
• Channel leasing — fees for opening and providing inbound liquidity to agents
• Managed connectivity — premium peering and reliability for agents that need it

LQWD is the default, not a requirement. Agents can open channels to any node on the Lightning Network. SaturnZap never enforces LQWD usage. LQWD competes on quality — 18-country coverage, deep liquidity, fast channel opens — not on lock-in.

This model mirrors how open-source software with cloud backends works: the tool is free, the infrastructure is the business.

---

Key Properties

• Non-custodial — BIP39 seed lives encrypted on the agent's machine. SaturnZap never holds, transmits, or has access to private keys.
• No full Bitcoin node — Esplora REST API provides chain data with automatic fallback (LQWD → blockstream.info → mempool.space). No bitcoind required.
• Peer-agnostic — Open channels to any Lightning node. LQWD is a smart default with global reach, but the agent controls its own peer relationships entirely.
• JSON-first — Every command writes structured JSON to stdout. Errors go to stderr. Designed for machine consumption from day one.
• MCP-native — Built-in MCP server exposes 25 tools over stdio. Connect Claude, Cursor, VS Code, or any MCP-compatible agent with a single config block.
• Autonomous — No interactive prompts in normal operation. Designed to run inside agent runtimes, shell scripts, and orchestration pipelines. (Mainnet spending commands prompt for confirmation unless --yes is passed.)

---

Architecture

Full architecture details: docs/architecture.md

Component Map

┌─────────────────────────────────────────────────────────┐

│ 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) │ └─────────────────────────┘ └─────────────────────────────┘

Key Design Decisions

Unix Domain Socket IPC

The daemon (sz start) owns the LDK node and exposes 23 methods over a Unix Domain Socket at ~/.local/share/saturnzap/ /sz.sock. CLI commands, the MCP server, and OpenClaw automatically detect the daemon and route through IPC — no port conflicts, no database locks. If no daemon is running, commands fall back to starting an ephemeral node.

Esplora chain sync with fallback

LDK Node syncs chain data via Esplora (block explorer REST API). No external Bitcoin node is needed. SaturnZap ships with a fallback chain — if the primary Esplora server is unreachable, it automatically probes alternatives (LQWD, blockstream.info, mempool.space) and connects to the first healthy endpoint. First sync takes a few minutes on a fresh install; subsequent starts are near-instant.

LQWD as default LSP

On mainnet, fresh installs peer with LQWD-AI-Grid by default — LQWD's agent-focused LSP node that supports LSPS1 and LSPS2 (JIT channels). The node auto-opens a channel back on first peer contact, so a new wallet can start receiving inbound liquidity without needing on-chain funds first. The 18-region geographic fleet is still embedded and available: set SZ_REGION=NEAREST to fall back to timezone-based selection (e.g. LQWD-England from UTC, LQWD-Japan from JST), or SZ_REGION=CA / --region CA to pin a specific region.

Peer-agnostic after init

After the initial channel, agents use standard Lightning channel open flows to peer with anyone. SaturnZap has no routing logic that artificially prefers LQWD — Lightning pathfinding selects the best route. LQWD nodes appear as attractive routes naturally because of their connectivity and capacity across 18 countries.

JSON-first, non-interactive by default

All commands are designed for non-interactive execution. No spinners that break pipe parsing. Pass --pretty for human-readable output in a TTY. Default is always clean JSON.

One exception for safety: mainnet spending commands (send, pay, keysend, channels open) show a [y/N] confirmation. Skip it with --yes or SZ_MAINNET_CONFIRM=yes in automation. Signet and testnet never prompt.

Autonomous channel management

SaturnZap monitors channel health. When configured, it automatically opens new channels when outbound liquidity drops below a threshold, and requests inbound liquidity from the configured LSP when needed. Agents can run indefinitely without manual intervention.

---

Technology Stack

---

LQWD Node Directory

Embedded in SaturnZap as trusted default peers. On sz init or sz channels open --lsp lqwd, the nearest node is auto-selected by comparing the system's UTC offset against each node's timezone — smallest offset difference wins. Override with SZ_REGION env var or --region flag. Full pubkeys and connection strings are in src/saturnzap/lqwd.py.

Full pubkeys and host:port connection strings are in src/saturnzap/lqwd.py. Signet/testnet node details maintained separately for development.

---

CLI Reference

Full JSON API reference: docs/json-api-reference.md

Binary: sz

All comma