SaturnZap

自律型 AI エージェント向けに構築された、軽量で CLI ファーストな非カストディアル型 Lightning Network ウォレットです。
自己主権型。独自の Lightning ノードを稼働させます。フル 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エージェント向けに、ゼロから設計されたオープンソースのLightningウォレットです。エージェントはSaturnZapをインストールし、独自のLightningノードを初期化して、ネットワーク上の任意のピアとチャネルを開設し、Bitcoinの支払いを送受信し、L402で保護されたAPIの料金を自律的に支払います。

SaturnZapはCLIツールです。ホステッドウォレットでも、カストディアルサービスでも、Webアプリケーションでもありません。鍵はエージェントのマシン上に保存されます。エージェント自身がLightningノードです。

統合方法は2つあります：

• CLI — 任意の言語からszコマンドを呼び出し、標準出力からJSONを解析します
• MCPサーバー — Model Context Protocol（stdio）を介してAIエージェントを直接接続します

ドキュメント： 詳細なガイドについては、docs/フォルダーをご覧ください。 はじめに、 設定、 MCPサーバーの統合、 アーキテクチャ、および JSON APIリファレンスを参照できます。

ビジネスモデル

SaturnZapは2つの層で構成されています。

CLI — オープンソース（MIT）

コマンドラインツールszは、MITライセンスのもとで無料のオープンソースとして提供されています。誰でもインストール、フォーク、監査、拡張できます。ライセンス料はなく、ソフトウェア自体の利用にAPIキーも不要で、テレメトリーもありません。

LQWD（LSP）

SaturnZapは、デフォルトのLightning Service Provider（LSP）としてLQWD Technologiesを使用するよう事前設定されています。LQWDは18か国で18のLightningノードを運用し、世界各地に豊富なチャネル流動性を提供しています。

エージェントがLQWDのインフラを利用すると、LQWDは以下を通じて収益を得ます。

• ルーティング手数料 — 支払いがLQWDのノードを経由する際に得られるsats
• チャネルリース — エージェント向けにチャネルを開設し、インバウンド流動性を提供するための手数料
• マネージド接続 — 必要とするエージェント向けのプレミアムなピアリングと信頼性

LQWDはデフォルトであり、必須ではありません。エージェントはLightning Network上の任意のノードとチャネルを開設できます。SaturnZapがLQWDの利用を強制することはありません。LQWDは、囲い込みではなく、18か国をカバーするネットワーク、豊富な流動性、迅速なチャネル開設といった品質で競争します。

このモデルは、クラウドバックエンドを備えたオープンソースソフトウェアと同様です。ツールは無料で、インフラがビジネスです。

主な特性

• 非カストディアル — BIP39 シードはエージェントのマシン上で暗号化されて保存されます。SaturnZap が秘密鍵を保持、送信、またはアクセスすることはありません。
• フル Bitcoin ノード不要 — Esplora REST API がチェーンデータを提供し、自動フォールバック（LQWD → blockstream.info → mempool.space）にも対応しています。bitcoind は不要です。
• ピアを自由に選択可能 — 任意の Lightning ノードとチャネルを開設できます。LQWD はグローバルな到達範囲を持つ便利なデフォルトですが、ピアとの関係はすべてエージェント自身が管理します。
• JSON ファースト — すべてのコマンドは構造化 JSON を標準出力に書き込みます。エラーは標準エラー出力に送られます。最初から機械による処理を前提に設計されています。
• MCP ネイティブ — 組み込みの MCP サーバーは、stdio 経由で 25 個のツールを公開します。設定ブロックを 1 つ指定するだけで、Claude、Cursor、VS Code、または MCP 対応エージェントに接続できます。
• 自律的 — 通常の操作で対話型プロンプトは表示されません。エージェントのランタイム、シェルスクリプト、オーケストレーションパイプライン内での実行を想定して設計されています。（Mainnet の支出コマンドでは、--yes を指定しない限り確認プロンプトが表示されます。）

アーキテクチャ

アーキテクチャの詳細：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 ノードを管理し、~/.local/share/saturnzap/<network>/sz.sock にある Unix ドメインソケットを介して 23 個のメソッドを公開します。CLI コマンド、MCP サーバー、OpenClaw はデーモンを自動的に検出し、IPC 経由で処理を実行するため、ポートの競合やデータベースのロックは発生しません。デーモンが実行されていない場合、コマンドは一時的なノードを起動して処理します。

フォールバック付き Esplora チェーン同期

LDK Node は Esplora（ブロックエクスプローラー REST API）経由でチェーンデータを同期します。外部の Bitcoin ノードは不要です。SaturnZap にはフォールバック用のチェーン接続先が組み込まれており、プライマリ Esplora サーバーに到達できない場合は、代替先（LQWD、blockstream.info、mempool.space）を自動的に確認し、最初に正常と判断されたエンドポイントに接続します。新規インストール後の初回同期には数分かかりますが、以降の起動はほぼ瞬時です。

デフォルトの LSP としての LQWD

Mainnet では、新規インストール時にデフォルトで LQWD-AI-Grid とピア接続します。これは LSPS1 と LSPS2（JIT チャネル）に対応した、エージェント向けの LQWD の LSP ノードです。最初のピア接続時にノードが自動でチャネルを開設するため、新しいウォレットはオンチェーン資金を事前に用意しなくてもインバウンド流動性を受け取れるようになります。18 地域に展開されたノード群も引き続き組み込まれており、利用できます。タイムゾーンに基づく選択に切り替えるには SZ_REGION=NEAREST を設定します（例：UTC からは LQWD-England、JST からは LQWD-Japan）。特定の地域に固定するには SZ_REGION=CA または --region CA を指定します。

初期化後はピアを自由に選択可能

最初のチャネルを開設した後、エージェントは標準の Lightning チャネル開設フローを使って任意の相手とピア接続できます。SaturnZap には LQWD を人為的に優先するルーティングロジックはなく、Lightning の経路探索が最適なルートを選択します。LQWD のノードは、18 か国に広がる接続性と容量により、自然に魅力的なルートとして表示されます。

JSON ファーストで、デフォルトでは非対話型

すべてのコマンドは非対話型の実行を前提に設計されています。パイプ処理を妨げるスピナーはありません。TTY で人が読みやすい出力にするには --pretty を指定します。デフォルトでは常にクリーンな JSON が出力されます。

安全性を考慮した例外が 1 つあります。Mainnet の支出コマンド（send、pay、keysend、channels open）では [y/N] の確認が表示されます。自動化で確認を省略するには、--yes または SZ_MAINNET_CONFIRM=yes を指定してください。Signet と testnet では確認は表示されません。

自律的なチャネル管理

SaturnZap はチャネルの状態を監視します。設定すると、アウトバウンド流動性がしきい値を下回った際に新しいチャネルを自動で開設し、必要に応じて設定済みの LSP にインバウンド流動性を要求します。エージェントは手動で介入することなく、無期限に実行できます。

技術スタック

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

エージェントの設定（Claude Desktop、Cursor、VS Code など）：

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

MCP サーバーは、ノードのライフサイクル、ウォレット、ピア、チャネル、支払い、L402 フェッチ、流動性管理を網羅する 25 個のツールを公開します。デフォルトのリクエストごとの上限である 1,000 sat を調整するには SZ_MCP_MAX_SPEND_SATS を設定します。永続的な 10,000 sat のローリング日次上限を調整するには SZ_MCP_DAILY_SPEND_SATS を設定します。上限にはルーティング手数料が含まれ、デーモン経由のリクエストにも適用されます。新しい 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 地域、タイムゾーンに基づく自動選択）。ノードがインターネットからアクセス可能な場合、チャネルはデフォルトでパブリックなゴシップグラフにアナウンスされ、エージェントは自動的にパブリックなルーティングノードになります。チャネル一覧表示とクローズ。

フェーズ 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 スキル定義。セキュリティスキャナー（グレード 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 コインは無料で、メインネットウォレットから分離されています。
• 自律型エージェントを実行する場合は、支出上限（--max-sats、SZ_CLI_MAX_SPEND_SATS、SZ_MCP_MAX_SPEND_SATS）を設定してください。

脅威モデルと脆弱性開示ポリシーについては、SECURITY.md をご覧ください。

ライセンス

MIT License。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 上で構築するエージェントや開発者向けに、ルーティングインフラストラクチャ、流動性サービス、LSP 接続を提供しています。

• 企業情報：https://lqwdtech.com
• エージェントエンドポイント：https://lqwd.ai
• ネットワーク：18 ノード、18 か国、1,600 以上のチャネル