@lightninglabs/lightning-mcp-server 0.2.0

package/docs/commerce.md

@@ -0,0 +1,357 @@
+# Agent Commerce
+
+> Setting up buyer and seller agents for autonomous Lightning payments.
+
+Lightning Agent Tools enables a payment pattern where agents buy and sell
+resources from each other over the Lightning Network without any pre-arranged
+billing relationship. A buyer agent uses `lnget` to fetch paid content. A
+seller agent uses `aperture` to gate access behind Lightning invoices. Both run
+their own `lnd` nodes for payment infrastructure. The three components compose
+into a self-contained commerce loop.
+
+This document walks through setting up both sides and running them together.
+
+## The Commerce Loop
+
+When a buyer agent fetches a resource from a seller, the following exchange
+happens automatically:
+
+```mermaid
+sequenceDiagram
+    participant BA as Buyer Agent
+    participant BL as Buyer lnd
+    participant LN as Lightning Network
+    participant SL as Seller lnd
+    participant AP as Aperture
+    participant BE as Backend Service
+
+    BA->>AP: GET /api/data (via lnget)
+    AP->>SL: Generate invoice (100 sats)
+    SL-->>AP: BOLT11 invoice
+    AP-->>BA: 402 + L402 challenge
+
+    BA->>BL: Pay invoice (100 sats)
+    BL->>LN: Route payment
+    LN->>SL: Deliver payment
+    SL-->>LN: Preimage
+    LN-->>BL: Preimage
+    BL-->>BA: Payment settled
+
+    BA->>AP: GET /api/data + L402 token
+    AP->>AP: Validate token
+    AP->>BE: Proxy request
+    BE-->>AP: Response data
+    AP-->>BA: 200 OK + data
+```
+
+From the buyer agent's perspective, this is a single command:
+
+```bash
+lnget --max-cost 100 -q https://seller-host:8081/api/data | jq .
+```
+
+From the seller's perspective, aperture handles everything: invoice
+generation, challenge issuance, token validation, and request proxying. The
+backend service just serves HTTP requests.
+
+## Buyer Agent Setup
+
+A buyer agent needs two components: an `lnd` node for payments and `lnget` for
+HTTP requests with automatic L402 handling.
+
+### Install
+
+```bash
+# Pulls Docker images by default; add --source to build from source.
+skills/lnd/scripts/install.sh
+skills/lnget/scripts/install.sh
+```
+
+### Create and Start the Node
+
+All commands below auto-detect Docker and launch containers. Pass `--native` to
+any script to use a locally built binary instead.
+
+```bash
+# Create a wallet (standalone mode for testing, watch-only for production)
+skills/lnd/scripts/create-wallet.sh --mode standalone
+
+# Start lnd (launches a litd Docker container)
+skills/lnd/scripts/start-lnd.sh
+
+# Verify it's running
+skills/lnd/scripts/lncli.sh getinfo
+```
+
+For production deployments, use watch-only mode with a remote signer. See
+[Security](security.md#tier-1-watch-only-with-remote-signer).
+
+### Fund the Wallet
+
+The node needs on-chain bitcoin to open payment channels.
+
+```bash
+# Generate a funding address
+skills/lnd/scripts/lncli.sh newaddress p2tr
+
+# Send BTC to this address from an exchange or another wallet
+
+# Check balance (wait for confirmations)
+skills/lnd/scripts/lncli.sh walletbalance
+```
+
+### Open a Channel
+
+Lightning payments travel through channels. The buyer needs at least one channel
+with outbound capacity to reach the seller (or a path to the seller through the
+network).
+
+```bash
+# Connect to a well-connected node
+skills/lnd/scripts/lncli.sh connect <pubkey>@<host>:9735
+
+# Open a channel (amount in satoshis)
+skills/lnd/scripts/lncli.sh openchannel --node_key=<pubkey> --local_amt=1000000
+
+# Wait for the funding transaction to confirm (typically 3-6 blocks)
+skills/lnd/scripts/lncli.sh pendingchannels
+skills/lnd/scripts/lncli.sh listchannels
+```
+
+### Configure lnget
+
+```bash
+# Initialize config (auto-detects local lnd)
+lnget config init
+
+# Verify backend connection
+lnget ln status
+```
+
+### Fetch Paid Resources
+
+```bash
+# Fetch with a spending cap
+lnget --max-cost 500 https://api.example.com/paid-data.json
+
+# Preview cost without paying
+lnget --no-pay --json https://api.example.com/paid-data.json | jq '.invoice_amount_sat'
+
+# Pipe to other tools
+lnget -q https://api.example.com/market-data.json | jq '.price'
+```
+
+## Seller Agent Setup
+
+A seller agent needs three components: an `lnd` node for invoice generation,
+`aperture` as the L402 reverse proxy, and a backend HTTP service to serve the
+actual content.
+
+### Install
+
+```bash
+skills/lnd/scripts/install.sh
+skills/aperture/scripts/install.sh
+```
+
+### Create and Start the Node
+
+```bash
+skills/lnd/scripts/create-wallet.sh --mode standalone
+skills/lnd/scripts/start-lnd.sh                            # Docker container by default
+skills/lnd/scripts/lncli.sh getinfo
+```
+
+The seller's lnd node generates invoices for aperture. It needs inbound channel
+capacity to receive payments. Other nodes must have channels open _to_ the
+seller, not just from the seller.
+
+### Start a Backend Service
+
+Aperture proxies authenticated requests to a backend HTTP service. For testing,
+a simple file server works:
+
+```bash
+mkdir -p /tmp/api-data
+echo '{"market_data": {"btc_usd": 104250, "timestamp": "2025-02-09T12:00:00Z"}}' \
+    > /tmp/api-data/data.json
+cd /tmp/api-data && python3 -m http.server 8080 &
+```
+
+In production, the backend is whatever service you want to monetize: a REST
+API, a data feed, an inference endpoint.
+
+### Configure and Start Aperture
+
+```bash
+# Generate aperture config connected to local lnd
+skills/aperture/scripts/setup.sh --insecure --port 8081
+
+# Start the L402 proxy
+skills/aperture/scripts/start.sh
+```
+
+The `--insecure` flag disables TLS (suitable for development). For production,
+configure TLS with Let's Encrypt (`--autocert`) or your own certificates.
+
+For regtest testing, a Docker Compose file at
+`skills/aperture/templates/docker-compose-aperture.yml` runs aperture alongside
+a busybox backend on the same Docker network as the litd regtest stack.
+
+Aperture's config (`~/.aperture/aperture.yaml`) defines which paths are
+protected and how much they cost:
+
+```yaml
+services:
+  - name: "market-data"
+    hostregexp: ".*"
+    pathregexp: "^/api/.*$"
+    address: "127.0.0.1:8080"
+    protocol: http
+    price: 100                    # satoshis per request
+    authwhitelistpaths:
+      - "^/health$"              # free health check endpoint
+```
+
+Each request to a path matching `^/api/.*$` costs 100 satoshis. Requests to
+`/health` pass through without payment. The `address` field points to the
+backend service.
+
+### Verify
+
+```bash
+# Should return 402 with L402 challenge
+lnget -k --no-pay https://localhost:8081/api/data.json
+```
+
+## Running Both Sides
+
+With both agents running, the buyer fetches data from the seller:
+
+```bash
+# Buyer fetches paid data
+lnget --max-cost 100 -q https://seller-host:8081/api/data.json | jq .
+```
+
+Verify the payment went through:
+
+```bash
+# On the buyer
+lnget tokens list                                    # shows cached token
+skills/lnd/scripts/lncli.sh channelbalance           # outbound decreased
+
+# On the seller
+skills/lnd/scripts/lncli.sh listinvoices             # shows settled invoice
+skills/lnd/scripts/lncli.sh channelbalance           # inbound converted to local
+```
+
+Subsequent requests from the buyer to the same domain reuse the cached token
+without additional payment (until the token expires).
+
+## Deployment Diagram
+
+A production deployment separates the signing infrastructure from the
+agent-facing components:
+
+```mermaid
+graph TB
+    subgraph Buyer["Buyer Agent"]
+        B_Agent["Agent Process"]
+        B_lnget["lnget"]
+        B_lnd["lnd (watch-only)"]
+        B_Signer["lnd signer<br/>(separate machine)"]
+
+        B_Agent --> B_lnget
+        B_lnget --> B_lnd
+        B_lnd <-->|"gRPC :10012"| B_Signer
+    end
+
+    subgraph Seller["Seller Agent"]
+        S_Agent["Agent Process"]
+        S_Aperture["aperture :8081"]
+        S_Backend["Backend :8080"]
+        S_lnd["lnd (watch-only)"]
+        S_Signer["lnd signer<br/>(separate machine)"]
+
+        S_Agent --> S_Aperture
+        S_Aperture --> S_Backend
+        S_Aperture --> S_lnd
+        S_lnd <-->|"gRPC :10012"| S_Signer
+    end
+
+    LN["Lightning Network"]
+    B_lnd <-->|":9735"| LN
+    S_lnd <-->|":9735"| LN
+```
+
+## Cost Management
+
+Agents operating autonomously need spending guardrails at multiple levels:
+
+**Per-request limits.** Set `--max-cost` on every lnget call. If the seller's
+price exceeds the limit, lnget refuses to pay and exits with code 2:
+
+```bash
+lnget --max-cost 500 https://api.example.com/data
+```
+
+**Cost preview.** Before committing to a purchase, preview what the server is
+charging:
+
+```bash
+lnget --no-pay --json https://api.example.com/data | jq '.invoice_amount_sat'
+```
+
+**Spending tracking.** Monitor cumulative spending through the token list:
+
+```bash
+lnget tokens list --json | jq '[.[] | .amount_paid_sat] | add'
+```
+
+**Wallet balance monitoring.** Check channel balance to ensure the agent has
+sufficient capacity:
+
+```bash
+skills/lnd/scripts/lncli.sh channelbalance
+skills/lnd/scripts/lncli.sh walletbalance
+```
+
+**Node-level controls.** Use a `pay-only` macaroon (via `macaroon-bakery`) for
+the buyer agent. This restricts lnget to payment and invoice-decoding operations
+only. The agent cannot open channels, change configuration, or access any
+other node functionality:
+
+```bash
+skills/macaroon-bakery/scripts/bake.sh --role pay-only
+```
+
+For the seller agent, use an `invoice-only` macaroon for aperture. It only needs
+to create and look up invoices.
+
+## Production Considerations
+
+**Remote signer.** Both buyer and seller nodes should run in watch-only mode
+with a remote signer in production. See
+[Security](security.md#tier-1-watch-only-with-remote-signer).
+
+**Inbound liquidity.** The seller's lnd node needs inbound channel capacity to
+receive payments. This means other nodes must open channels _to_ the seller.
+Options include requesting inbound channels from LSPs (Lightning Service
+Providers), or using circular rebalancing to shift local capacity to the remote
+side.
+
+**Channel sizing.** Size channels based on expected payment volume. A 1,000,000
+sat channel can handle many 100-sat L402 payments before rebalancing is needed.
+Monitor channel balances and open new channels proactively.
+
+**TLS for aperture.** Use `--autocert` with a domain name for automatic Let's
+Encrypt TLS, or provide your own certificate. Never run `--insecure` on
+public-facing endpoints.
+
+**Stopping everything.**
+
+```bash
+skills/aperture/scripts/stop.sh
+skills/lnd/scripts/stop-lnd.sh
+skills/lnd/scripts/stop-lnd.sh --clean                     # also remove Docker volumes
+```

package/docs/l402-and-lnget.md

@@ -0,0 +1,267 @@
+# L402 and lnget
+
+> The payment protocol that makes agent commerce work, and the CLI client that
+> automates it.
+
+L402 is an HTTP authentication scheme built on Lightning Network payments. It
+repurposes the HTTP 402 "Payment Required" status code, reserved since the
+early days of the HTTP spec but never widely adopted, to gate access to web
+resources behind Lightning invoices. An agent doesn't need an account, an API
+key, or a pre-existing relationship with the server. It pays a Lightning invoice
+and receives access. That's it.
+
+`lnget` is a command-line HTTP client (in the tradition of `wget` and `curl`)
+that handles L402 payments automatically. When it encounters a 402 response, it
+pays the embedded invoice, caches the resulting token, and retries the request.
+To the agent, the paid resource looks like any other HTTP fetch.
+
+## The L402 Protocol
+
+An L402 exchange has four steps:
+
+```mermaid
+sequenceDiagram
+    participant C as Client (lnget)
+    participant S as Server (aperture)
+    participant LN as Lightning Network
+
+    C->>S: GET /api/resource
+    S-->>C: 402 Payment Required<br/>WWW-Authenticate: L402<br/>macaroon="...", invoice="lnbc..."
+
+    Note over C: Parse macaroon and BOLT11 invoice<br/>Check: amount ≤ max-cost?
+
+    C->>LN: Pay BOLT11 invoice
+    LN-->>C: Preimage (proof of payment)
+
+    Note over C: Construct token: macaroon + preimage<br/>Cache token for this domain
+
+    C->>S: GET /api/resource<br/>Authorization: L402 <macaroon>:<preimage>
+    S-->>C: 200 OK + response body
+```
+
+**Step 1: The challenge.** The client requests a protected resource. The server
+responds with HTTP 402 and a `WWW-Authenticate` header containing two values: a
+macaroon (a bearer token encoding the access grant) and a BOLT11 Lightning
+invoice (the payment request).
+
+**Step 2: Payment.** The client decodes the BOLT11 invoice, verifies the amount
+is acceptable, and pays it through the Lightning Network. Payment settlement
+reveals a preimage, a 32-byte value that serves as cryptographic proof of
+payment.
+
+**Step 3: Token construction.** The client combines the macaroon from the
+challenge with the preimage from the payment to form an L402 token. This token
+is cached locally for future requests to the same domain.
+
+**Step 4: Authenticated retry.** The client retries the original request with an
+`Authorization: L402 <macaroon>:<preimage>` header. The server validates the
+token (verifying that the preimage matches the payment hash embedded in the
+macaroon) and serves the resource.
+
+The key property of L402 is that credentials are **purchased, not provisioned**.
+There is no signup flow, no API key management, no OAuth dance. Any client with
+access to the Lightning Network can authenticate with any L402 server
+instantly. This is what makes L402 native to agent workflows: agents can
+discover and pay for resources on the fly without requiring a human to pre-register
+accounts.
+
+## lnget
+
+`lnget` automates the entire L402 flow in a single command:
+
+```bash
+lnget https://api.example.com/premium-data.json
+```
+
+If the server returns 200, lnget writes the response to stdout (or a file with
+`-o`). If it returns 402, lnget parses the challenge, pays the invoice, caches
+the token, and retries. All of this is transparent. Subsequent requests to the same
+domain reuse the cached token without additional payment.
+
+### Installation
+
+```bash
+skills/lnget/scripts/install.sh
+```
+
+This runs `go install github.com/lightninglabs/lnget/cmd/lnget@latest`.
+
+### Lightning Backends
+
+lnget needs a Lightning backend to pay invoices. It supports three:
+
+```mermaid
+graph TD
+    lnget["lnget"]
+
+    lnget -->|"mode: lnd"| lnd["lnd (direct gRPC)<br/>Requires: host, TLS cert, macaroon<br/>Full payment capabilities"]
+    lnget -->|"mode: lnc"| lnc["LNC (Lightning Node Connect)<br/>Requires: pairing phrase<br/>Encrypted tunnel, no direct access"]
+    lnget -->|"mode: neutrino"| neutrino["Neutrino (embedded wallet)<br/>Self-contained light client<br/>No external node needed"]
+```
+
+**lnd (direct gRPC).** Connects to an lnd node over gRPC using a TLS
+certificate and macaroon. This is the standard mode when the agent runs its own
+lnd node via the `lnd` skill. Configure with:
+
+```bash
+lnget config init  # auto-detects local lnd
+```
+
+Or manually in `~/.lnget/config.yaml`:
+
+```yaml
+ln:
+  mode: lnd
+  lnd:
+    host: localhost:10009
+    tls_cert: ~/.lnd/tls.cert
+    macaroon: ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon
+    network: mainnet
+```
+
+Use a `pay-only` macaroon instead of `admin.macaroon` for agents. See
+[Security](security.md#preset-roles).
+
+**LNC (Lightning Node Connect).** Connects through an encrypted WebSocket
+tunnel using a pairing phrase. No direct network access to the lnd node is
+needed. Pair with:
+
+```bash
+lnget ln lnc pair "your ten word pairing phrase from lightning terminal"
+```
+
+**Neutrino (embedded wallet).** lnget runs its own lightweight Lightning wallet
+internally, using the Neutrino light client. No external lnd node required.
+Initialize with:
+
+```bash
+lnget ln neutrino init
+lnget ln neutrino fund  # generates a funding address
+```
+
+This mode is useful for quick experiments but has limited routing capability
+compared to a full lnd node.
+
+## Spending Controls
+
+Autonomous agents should never have unlimited spending authority. lnget provides
+two mechanisms for cost control:
+
+**Per-request ceiling.** The `--max-cost` flag sets the maximum amount (in
+satoshis) that lnget will auto-pay for a single request. If the invoice exceeds
+this amount, lnget exits with code 2 without paying:
+
+```bash
+lnget --max-cost 500 https://api.example.com/data
+```
+
+**Preview mode.** The `--no-pay` flag sends the request and displays the L402
+challenge (including the invoice amount) without paying. Agents can inspect
+costs before committing:
+
+```bash
+lnget --no-pay --json https://api.example.com/data | jq '.invoice_amount_sat'
+```
+
+For node-level spending limits, use the `macaroon-bakery` to bake a `pay-only`
+macaroon. This restricts the agent to payment operations only and prevents it
+from opening channels, modifying configuration, or performing other
+state-changing operations on the node.
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Request succeeded |
+| 1 | General error |
+| 2 | Invoice amount exceeds `--max-cost` |
+| 3 | Lightning payment failed |
+| 4 | Network or connection error |
+
+## Token Caching
+
+Paid L402 tokens are cached at `~/.lnget/tokens/<domain>/` and reused
+automatically on subsequent requests to the same domain. This means an agent
+pays once per domain (until the token expires) rather than once per request.
+
+Manage cached tokens with:
+
+```bash
+lnget tokens list                        # list all cached tokens
+lnget tokens show api.example.com        # show token for a specific domain
+lnget tokens remove api.example.com      # remove a token (force re-payment)
+lnget tokens clear --force               # clear all tokens
+```
+
+## Configuration
+
+lnget reads its configuration from `~/.lnget/config.yaml`. Initialize it with:
+
+```bash
+lnget config init    # creates config with defaults, auto-detects local lnd
+lnget config show    # display current config
+lnget config path    # print config file path
+```
+
+The config file controls L402 behavior, HTTP settings, Lightning backend
+selection, and output formatting:
+
+```yaml
+l402:
+  max_cost_sats: 1000          # default spending ceiling
+  max_fee_sats: 10             # max routing fee
+  payment_timeout: 60s
+  auto_pay: true               # pay automatically on 402
+
+http:
+  timeout: 30s
+  max_redirects: 10
+  user_agent: "lnget/0.1.0"
+  allow_insecure: false        # set true for self-signed certs (dev only)
+
+ln:
+  mode: lnd                    # lnd | lnc | neutrino
+
+output:
+  format: json
+  progress: true
+  verbose: false
+
+tokens:
+  dir: ~/.lnget/tokens
+```
+
+## Common Usage Patterns
+
+```bash
+# Fetch and pipe to jq
+lnget -q https://api.example.com/data.json | jq .
+
+# Save to file
+lnget -o data.json https://api.example.com/data.json
+
+# POST with body
+lnget -X POST -d '{"query":"test"}' https://api.example.com/search
+
+# Check backend connection
+lnget ln status
+lnget ln info
+
+# Track total spending
+lnget tokens list --json | jq '[.[] | .amount_paid_sat] | add'
+```
+
+## The Server Side: Aperture
+
+lnget handles the client side of L402. On the server side,
+[Aperture](https://github.com/lightninglabs/aperture) is an L402-aware reverse
+proxy that sits in front of a backend HTTP service and gates access behind
+Lightning payments.
+
+Aperture handles invoice generation (through its connected lnd node), L402
+challenge issuance, token validation, and request proxying. The backend service
+doesn't need any awareness of Lightning or L402. It just serves HTTP requests
+that arrive through aperture.
+
+For a complete walkthrough of setting up both the client and server sides, see
+[Commerce](commerce.md).