lnget: like wget but for L402 on the web

lnget - Lightning-Native HTTP Client

lnget is a wget/curl-like CLI that natively handles L402 (Lightning HTTP 402) authentication. When a server responds with HTTP 402 and an L402 challenge, lnget automatically pays the Lightning invoice and retries with the paid token.

Source: github.com/lightninglabs/lnget

Quick Start

# 1. Install lnget
skills/lnget/scripts/install.sh
2. Initialize config (auto-detects local lnd)
lnget config init
3. Fetch an L402-protected resource
lnget --max-cost 1000 https://api.example.com/paid-data

Installation

skills/lnget/scripts/install.sh

This will:

To install manually:

go install github.com/lightninglabs/lnget/cmd/lnget@latest

Or build from source:

git clone https://github.com/lightninglabs/lnget.git
cd lnget
make install

Basic Usage

Downloads

# Fetch URL (output to stdout)
lnget https://api.example.com/data.json
Save to file
lnget -o data.json https://api.example.com/data.json
Quiet mode for piping
lnget -q https://api.example.com/data.json | jq .
Resume partial download
lnget -c -o largefile.zip https://api.example.com/largefile.zip
Custom HTTP method with data
lnget -X POST -d '{"query":"test"}' https://api.example.com/search
Custom headers
lnget -H "Accept: text/plain" https://api.example.com/data

Payment Control

# Set maximum auto-pay amount (satoshis)
lnget --max-cost 5000 https://api.example.com/expensive.json
Set maximum routing fee
lnget --max-fee 50 https://api.example.com/data.json
Preview without paying (shows 402 challenge details)
lnget --no-pay https://api.example.com/data.json
Custom payment timeout
lnget --payment-timeout 120s https://api.example.com/data.json

Output Modes

# JSON output (default, best for programmatic use)
lnget --json https://api.example.com/data.json
Human-readable output
lnget --human https://api.example.com/data.json
Verbose mode (shows L402 flow details)
lnget -v https://api.example.com/data.json
Disable progress bar
lnget --no-progress -o file.zip https://api.example.com/file.zip

Subcommands

Token Management (lnget tokens)

Tokens are cached per-domain at ~/.lnget/tokens//token.json and reused automatically on subsequent requests.

# List all cached tokens
lnget tokens list
Show token for a specific domain
lnget tokens show api.example.com
Remove token for a domain (forces re-authentication)
lnget tokens remove api.example.com
Clear all tokens
lnget tokens clear --force

Configuration (lnget config)

# Initialize config file at ~/.lnget/config.yaml
lnget config init
Show current configuration
lnget config show
Show config file path
lnget config path

Lightning Backend (lnget ln)

# Check backend connection status
lnget ln status
Show detailed node info
lnget ln info

#### LNC (Lightning Node Connect)

# Pair with a node via LNC pairing phrase
lnget ln lnc pair "your-pairing-phrase"
Ephemeral pairing (no session persistence)
lnget ln lnc pair "phrase" --ephemeral
List saved LNC sessions
lnget ln lnc sessions
Revoke a session
lnget ln lnc revoke 

#### Neutrino (Embedded Wallet)

# Initialize embedded neutrino wallet
lnget ln neutrino init
Get address to fund wallet
lnget ln neutrino fund
Check wallet balance
lnget ln neutrino balance
Show sync status
lnget ln neutrino status

Configuration File

Config lives at ~/.lnget/config.yaml. Run lnget config init to create it.

Note: lnget config init may generate incorrect YAML key names (e.g., tlscertpath and macaroonpath instead of tls_cert and macaroon) due to missing yaml struct tags in the lnget source. Use the example below as the reference config format. If your config was generated by lnget config init, verify the ln.lnd keys match the format shown here.

l402:
  max_cost_sats: 1000       # Max invoice to auto-pay
  max_fee_sats: 10           # Max routing fee
  payment_timeout: 60s       # Payment timeout
  auto_pay: true             # Enable auto-payment
http:
  timeout: 30s
  max_redirects: 10
  user_agent: "lnget/0.1.0"
  allow_insecure: false
ln:
  mode: lnd                  # Options: lnd, lnc, neutrino
  lnd:
    host: localhost:10009
    tls_cert: ~/.lnd/tls.cert
    macaroon: ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon
    network: mainnet
output:
  format: json
  progress: true
  verbose: false
tokens:
  dir: ~/.lnget/tokens

Environment variables override config with LNGET_ prefix:

export LNGET_L402_MAX_COST_SATS=5000
export LNGET_LN_MODE=lnc
export LNGET_LN_LND_HOST=localhost:10009

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Payment exceeds max cost | | 3 | Payment failed | | 4 | Network/connection error |

L402 Flow

When lnget encounters a 402 response:

1. Parses WWW-Authenticate: L402 macaroon="...", invoice="..." header 2. Decodes the macaroon and BOLT11 invoice 3. Checks invoice amount against --max-cost 4. Stores a pending token (crash recovery) 5. Pays the invoice via the configured Lightning backend 6. Stores the paid token with preimage at ~/.lnget/tokens// 7. Retries the request with Authorization: L402 :

Subsequent requests to the same domain reuse the cached token without payment.

Agent Integration Patterns

Budget-Aware Fetching

# Check cost before committing
result=$(lnget --no-pay --json https://api.example.com/data.json)
cost=$(echo "$result" | jq -r '.invoice_amount_sat // 0')
if [ "$cost" -le "$BUDGET" ]; then
    lnget --max-cost "$BUDGET" -q https://api.example.com/data.json
fi

Parsing JSON Output

# Extract just the response body
lnget --json -q https://api.example.com/data.json | jq '.body'
Check if payment was required
lnget --json https://api.example.com/data.json | jq '.l402_paid'

Testing with Insecure Connections

# For local development with aperture (no TLS)
lnget -k https://localhost:8081/api/data

File Locations

| Path | Purpose | |------|---------| | ~/.lnget/config.yaml | Configuration file | | ~/.lnget/tokens// | Per-domain token storage | | ~/.lnget/lnc/sessions/ | LNC session persistence | | ~/.lnget/neutrino/ | Embedded wallet data |

# 1. Install lnget
skills/lnget/scripts/install.sh
2. Initialize config (auto-detects local lnd)
lnget config init
3. Fetch an L402-protected resource
lnget --max-cost 1000 https://api.example.com/paid-data