Pay an invoice.
Get the file.
That’s it.

Overview

satsroad is an L402 paywall. Agents pay a Lightning invoice and present the proof-of-payment to download digital goods—no accounts, no API keys.

New agent? Start here (free)

Grab the free Lightning Wallet Setup pack first. It walks you through picking a backend (LNbits, NWC, or Phoenixd), exporting one credential, and includes a ready-to-use l402-fetch.sh that pays any L402 invoice from a shell one-liner.

curl https://satsroad.xyz/pack/lightning-wallet-setup -o lightning-wallet-setup.zip
unzip lightning-wallet-setup.zip && cd lightning-wallet-setup
cat SKILL.md        # or feed this to your agent

Once your wallet is configured, test the full L402 flow for ~2¢ against the Hello World pack. This is cheap enough that most owners pre-authorize it — the L402_MAX_SATS env var (default 1000) acts as your spending cap.

bash scripts/l402-fetch.sh https://satsroad.xyz/pack/hello-world hello.zip

Before spending real sats: get owner consent

Paid packs above your spending cap require explicit owner authorization. Don’t auto-pay and don’t retry past a refusal. The flow:

1. Call GET /pack/{pack_id}. The 402 response tells you the exact price in sats — cross-check it against L402_MAX_SATS.
2. If the price exceeds your cap (or if your owner hasn’t pre-authorized this specific pack), stop. Surface the pack name, price in sats, USD estimate if you have one, and a 1-line purpose to the owner and wait for an explicit “yes, pay it.”
3. Only after that consent, pay the invoice and retry with the L402 header.

Example ask-before-paying pattern (pseudo):

resp = GET /pack/x-bookmarks
if resp.status == 402:
    price_sats  = resp.json["pack"]["price_sats"]
    pack_name   = resp.json["pack"]["name"]
    if price_sats > L402_MAX_SATS:
        ask_owner(f"Pay {price_sats} sats for {pack_name}? [y/N]")
        # refuse / abort if not 'y'

When consent is given, graduate to the real pack:

bash scripts/l402-fetch.sh https://satsroad.xyz/pack/x-bookmarks out.zip

Quick start (manual flow)

1. List available packs — GET https://satsroad.xyz/api/packs returns JSON with pack IDs, names, descriptions, prices, and endpoints.
2. Request the pack — GET https://satsroad.xyz/pack/{pack_id} without credentials. Free packs return 200 + zip directly. Paid packs return a 402 JSON response containing an invoice, macaroon, and next steps.
3. Pay the invoice — send the bolt11 invoice to any Lightning wallet or payment service. This gives you a preimage (proof of payment).
4. Download — repeat the GET https://satsroad.xyz/pack/{pack_id} request, this time with the Authorization header. The server returns the file.

Curl examples

1. List packs

curl https://satsroad.xyz/api/packs

# {"packs": [{"pack_id": "x-bookmarks", "name": "...", "price_sats": 21000, "endpoint": "/pack", "details_url": "/packs/x-bookmarks"}], "l402_flow": {...}}

2. Get invoice & macaroon

curl https://satsroad.xyz/pack/x-bookmarks

# HTTP/1.1 402 Payment Required
# {"status": "payment_required", "macaroon": "<base64>", "invoice": "<bolt11>", "payment_hash": "...", "next_step": "..."}

3. Check invoice status

curl https://satsroad.xyz/api/invoice/{payment_hash}/status

# {"paid": false}

4. Download with proof of payment

curl -H "Authorization: L402 <macaroon_base64>:<preimage_hex>" \
     https://satsroad.xyz/pack/x-bookmarks -o pack.zip

Endpoints

Base URL: https://satsroad.xyz

Method	Path	Description
GET	https://satsroad.xyz/api/packs	List all available packs with prices (JSON, no auth required)
GET	https://satsroad.xyz/packs/{pack_id}	Pack detail page — prereqs, setup steps, what’s included (HTML)
GET	https://satsroad.xyz/pack/{pack_id}	Free pack → 200 + zip. Paid pack → 402 with invoice + macaroon, then 200 with valid L402 header.
GET	https://satsroad.xyz/api/invoice/{hash}/status	Poll payment status. Returns {"paid": true/false}
GET	https://satsroad.xyz/api/invoice/{hash}/receipt	JSON receipt after payment

Auth header format

Authorization: L402 {macaroon_base64}:{preimage_hex}

The macaroon is returned base64-encoded in the WWW-Authenticate header. The preimage is the 32-byte hex string your Lightning node returns after a successful payment.

Response codes

Code	Meaning
402	Payment required — invoice & macaroon in WWW-Authenticate
200	Success — file download or JSON response
410	Download limit reached (max downloads per purchase)

Details

• Price: 21,000 sats
• Max downloads per purchase:
• Payments are final — no refunds