lnget

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:

• Verify Go is installed
• Run go install github.com/lightninglabs/lnget/cmd/lnget@latest
• Verify lnget is on $PATH

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/<domain>/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 <session-id>

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/<domain>/
7. Retries the request with Authorization: L402 <macaroon>:<preimage>

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/<domain>/	Per-domain token storage
~/.lnget/lnc/sessions/	LNC session persistence
~/.lnget/neutrino/	Embedded wallet data