Lightning Paywall Http Client L402

---
name: lightning-paywall-http-client-l402
description: "Install and use lnget, a Lightning-native HTTP client with automatic L402 payment support. Use when downloading files behind Lightning paywalls, managing L402 tokens, checking Lightning backend status, or making HTTP requests that may require micropayments."
category: "Finance & Crypto"
author: community
version: "1.0.0"
icon: coins
---

# 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

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

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

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

Or build from source:

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

## Basic Usage

### Downloads

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

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

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

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

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

```bash
# Check backend connection status
lnget ln status

# Show detailed node info
lnget ln info
```

#### LNC (Lightning Node Connect)

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

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

```yaml
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:

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

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

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

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