Metadata-Version: 2.4
Name: saturnzap
Version: 1.3.2
Summary: CLI-first, non-custodial Lightning Network wallet for autonomous AI agents
Project-URL: Homepage, https://github.com/lqwdtech/SaturnZap
Project-URL: Repository, https://github.com/lqwdtech/SaturnZap
Project-URL: Issues, https://github.com/lqwdtech/SaturnZap/issues
Project-URL: Documentation, https://github.com/lqwdtech/SaturnZap/tree/main/docs
Project-URL: Changelog, https://github.com/lqwdtech/SaturnZap/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/lqwdtech/SaturnZap/blob/main/SECURITY.md
Author: Shone Anstey
License: MIT
License-File: LICENSE
Keywords: ai-agent,bitcoin,cli,l402,ldk,lightning,mcp,wallet
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: cryptography>=44.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: ldk-node==0.7.0
Requires-Dist: mcp>=1.26
Requires-Dist: mnemonic>=0.21
Requires-Dist: platformdirs>=4.3
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: typer>=0.15
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="logos/SaturnZap%20White%20logo%20Transparent%20bg.svg">
    <source media="(prefers-color-scheme: light)" srcset="logos/SaturnZap%20Main%20Logo%20Transparent%20bg.svg">
    <img alt="SaturnZap" src="logos/SaturnZap%20Main%20Logo%20Transparent%20bg.svg" width="400">
  </picture>
</p>

<p align="center">
  <strong>A lightweight, CLI-first, non-custodial Lightning Network wallet built for autonomous AI agents.</strong><br>
  Self-sovereign. Runs its own Lightning node. No full Bitcoin node required.
</p>

<!-- mcp-name: io.github.lqwdtech/saturnzap -->

<p align="center">
  <a href="https://github.com/lqwdtech/SaturnZap/actions/workflows/ci.yml"><img src="https://github.com/lqwdtech/SaturnZap/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/saturnzap/"><img src="https://img.shields.io/pypi/v/saturnzap.svg" alt="PyPI"></a>
  <a href="https://pypi.org/project/saturnzap/"><img src="https://img.shields.io/pypi/pyversions/saturnzap.svg" alt="Python versions"></a>
  <a href="https://github.com/lqwdtech/SaturnZap/blob/main/LICENSE"><img src="https://img.shields.io/github/license/lqwdtech/SaturnZap.svg" alt="License: MIT"></a>
</p>

```bash
# 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
```

<details>
<summary>Or install with <code>uv tool</code> directly</summary>

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

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

```bash
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/](docs/) folder for detailed guides on
> [getting started](docs/getting-started.md),
> [configuration](docs/configuration.md),
> [MCP server integration](docs/mcp-server.md),
> [architecture](docs/architecture.md), and
> [JSON API reference](docs/json-api-reference.md).

---

## 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](https://lqwd.ai) 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](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

| Component | Library | Notes |
|---|---|---|
| Language | Python 3.12 | Type hints throughout |
| Lightning node | ldk-node 0.7.0 | LDK Node Python bindings, Neutrino built-in |
| CLI framework | typer | Clean API, auto-generated help |
| HTTP client | httpx | Used for L402 interceptor |
| Config storage | platformdirs + TOML | OS-appropriate config paths |
| Key encryption | cryptography | Fernet encryption for seed file |
| BIP39 | mnemonic | Seed phrase generation |
| Package manager | uv | Fast, modern Python tooling |
| MCP server | mcp ≥1.26 | Model Context Protocol for AI agent integration |
| Testing | pytest | Unit + integration, 395+ tests |
| Linting | ruff | Fast Python linter and formatter |

---

## 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`.

| Alias | Region |
|---|---|
| LQWD-Canada | CA |
| LQWD-Sweden | SE |
| LQWD-France | FR |
| LQWD-England | GB |
| LQWD-Japan | JP |
| LQWD-Australia | AU |
| LQWD-Brazil | BR |
| LQWD-Bahrain | BH |
| LQWD-Singapore | SG |
| LQWD-SouthAfrica | ZA |
| LQWD-HongKong | HK |
| LQWD-SouthKorea | KR |
| LQWD-Indonesia | ID |
| LQWD-Ireland | IE |
| LQWD-Italy | IT |
| LQWD-Germany | DE |
| LQWD-India | IN |
| LQWD-US-West | US |

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](docs/json-api-reference.md)

**Binary:** `sz`

All commands output JSON to stdout. Errors exit with code 1, written to stderr.

**Global options:**

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

### Node

```bash
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
```

### Wallet

```bash
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
```

### Peers

```bash
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
```

### Config

```bash
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
```

### Channels

```bash
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
```

### Payments

```bash
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 — Autonomous API Payments

```bash
# 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"
```

### Liquidity

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

### Service Management

```bash
sz service install               # Install + start systemd unit (recommended for persistence)
sz service status                # Check service status
sz 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

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

Or use the standalone entry point:

```bash
sz-mcp                           # Same as sz mcp
```

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

```json
{
  "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
enforce a global per-request spending cap on L402 payments.

---

## JSON Output Format

### `sz balance`

```json
{
  "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`

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

### `sz fetch` (L402 flow)

```json
{
  "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)

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

---

## Exit Codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Node not running — run `sz start` |
| 3 | Insufficient funds |
| 4 | Channel not found |
| 5 | Peer unreachable |
| 6 | Invoice expired or invalid |
| 7 | LSP request failed |

---

## 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-py3-none-any.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

| | |
|---|---|
| **OS** | Ubuntu 24.04 (DigitalOcean Droplet, 2GB RAM / 2 vCPU) |
| **Editor** | VS Code via Remote SSH |
| **Python** | 3.12 |
| **Network** | Bitcoin mainnet (default) / signet / testnet — selectable via `--network` |
| **Chain source** | Esplora REST API with automatic fallback chain |
| **LQWD nodes** | 18 regions, pubkeys embedded in `src/saturnzap/lqwd.py` |

### Droplet Setup

```bash
# 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
```

### Install from PyPI

```bash
# 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.3.2

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

---

## 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](SECURITY.md) for the threat model and disclosure policy.

---

## License

MIT License. See [LICENSE](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