SaturnZap

[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.

[CI] [PyPI] [Python versions] [License: MIT]

# 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 peersz service install               # Keep the node running across rebootssz 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 500sz 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/<network>/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 commands output JSON to stdout. Errors exit with code 1, written to stderr.

Global options:

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

Node

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

Wallet

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

Peers

sz peers listsz 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

Config

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

Channels

sz channels list
# Open to any nodesz channels open --peer <pubkey>@<host>:<port> --amount-sats 100000
# Open via LQWD — nearest node automatically selectedsz channels open --lsp lqwd --amount-sats 100000
# Open via LQWD in a specific regionsz 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

Payments

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

L402 — Autonomous API Payments

# Auto-detects HTTP 402, pays invoice, retries request, returns bodysz fetch https://api.example.com/data
# With per-request spending capsz fetch https://api.example.com/data --max-sats 100
# With custom headerssz fetch https://api.example.com/data --header "X-Custom: value"

Liquidity

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

Service Management

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

Once installed, the LDK node stays up across reboots and every sz command routes through the daemon's IPC socket — no per-command startup overhead.

MCP Server

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

Or use the standalone entry point:

sz-mcp                           # Same as sz mcp

Agent configuration (Claude Desktop, Cursor, VS Code, etc.):

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

The MCP server exposes 25 tools covering node lifecycle, wallet, peers, channels, payments, L402 fetch, and liquidity management. Set SZ_MCP_MAX_SPEND_SATS to adjust its default 1,000-sat per-request ceiling; SZ_MCP_DAILY_SPEND_SATS adjusts the persistent 10,000-sat rolling daily ceiling. Caps include routing fees and follow requests through the daemon. New MCP wallets require a private operator-configured mnemonic backup, and sweeps require explicit permission. See spending policy and the 1.4.0 upgrade guide.

JSON Output Format

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 flow)

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

Error (any command)

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

Exit Codes

Project Structure

/├── 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

Development Environment

Droplet Setup

# Install uvcurl -LsSf https://astral.sh/uv/install.sh | shsource $HOME/.local/bin/env
# Clone and installgit clone https://github.com/lqwdtech/SaturnZapcd saturnzapuv venvsource .venv/bin/activateuv sync
# Runsz --help

Install from 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 Releasespip install saturnzap --find-links https://github.com/lqwdtech/SaturnZap/releases/expanded_assets/v1.4.1
# Or with uvuv pip install saturnzap --find-links https://github.com/lqwdtech/SaturnZap/releases/expanded_assets/v1.4.1

Development Phases

Phase 1 — Node Foundation ✅

sz init, sz start, sz stop, sz status

BIP39 seed generation, encrypted storage, LDK Node startup, Esplora chain sync, auto-peer with nearest LQWD node, JSON output infrastructure.

Phase 2 — Channel Management ✅

sz channels, sz peers, sz address, sz balance

Open channels to any node. LQWD LSP-assisted channel opens. LQWD node directory embedded (18 regions, timezone-based auto-selection). Channels are announced to the public gossip graph by default when the node is reachable from the internet, turning agents into public routing nodes automatically. Channel list and close.

Phase 3 — Payments ✅

sz invoice, sz pay, sz keysend, sz transactions

Full BOLT11 send and receive. Variable-amount invoices. Keysend. Transaction history with sorting and pagination.

Phase 4 — L402 ✅

sz fetch

HTTP client with 402 detection, invoice extraction, auto-pay, request retry. Per-request spending caps. Token caching to avoid re-paying the same resource.

Phase 5 — Liquidity Intelligence ✅

sz liquidity

Channel health monitoring with 0-100 scoring. Actionable recommendations. Inbound liquidity requests via LQWD. Geography-aware peer selection across 18 regions.

Phase 6 — Packaging and Integration ✅

pip install saturnzap / uv add saturnzap / sz mcp

MCP server with 25 tools. Esplora fallback chain. GitHub Actions CI/CD. PyPI packaging. OpenClaw skill definition. Security scanner (Grade A+).

Phase 7 — Mainnet Support ✅

sz --network bitcoin

Network selection via CLI flag (--network signet|testnet|bitcoin), config.toml, or default. Network-namespaced data directories isolate wallets per network. Real LQWD mainnet node directory (18 nodes). Mainnet safety confirmation prompt on spending commands, skippable with --yes flag or SZ_MAINNET_CONFIRM=yes. Network field included in all JSON responses.

Upcoming

• PyPI publish (trusted publisher workflow ready)
• Docker image
• OpenClaw ClawHub listing

Responsible Use

SaturnZap is non-custodial software. You hold your own keys, and you are solely responsible for your funds. It is provided under the MIT license on an "as is" basis — the usual open-source terms apply. A few practical suggestions:

• Start with small amounts on mainnet while you get comfortable with the tooling.
• Back up your seed phrase somewhere safe and offline. Without it, there is no recovery path.
• Use --network signet for development and integration testing — signet coins are free and isolated from your mainnet wallet.
• Set spending caps (--max-sats, SZ_CLI_MAX_SPEND_SATS, SZ_MCP_MAX_SPEND_SATS) when running autonomous agents.

See SECURITY.md for the threat model and disclosure policy.

License

MIT License. See LICENSE.

The SaturnZap CLI is free and open source. LQWD infrastructure services are commercial. Using SaturnZap with non-LQWD peers requires no agreement with LQWD Technologies.

About LQWD

LQWD Technologies Corp (TSXV: LQWD | OTCQX: LQWDF) is a publicly traded Lightning Network infrastructure company. LQWD operates 18 Lightning nodes across 18 countries, providing routing infrastructure, liquidity services, and LSP connectivity for agents and developers building on Bitcoin's Lightning Network.

• Corporate: https://lqwdtech.com
• Agent endpoint: https://lqwd.ai
• Network: 18 nodes, 18 countries, 1,600+ channels