Feedback
Sign in./start

Site navigation

Theme

Learn

  • Roadmaps

Build

  • Projects
  • Developer Tools

Contribute

  • Open Source Projects
  • Issues
  • Reviews
  • First Contribution
  • BountiesSoon
  • Feedback

Prove

  • Builders

Ecosystem

  • Partners
  • Get Funded↗
  • HackathonsSoon
Sign in./start-building

Become an Open Source Builder. Learn. Build. Contribute. Prove.

Feedback welcome — open a GitHub issue.

Learn

RoadmapsStart Building

Build

ProjectsDeveloper Tools

Contribute

Open Source ProjectsIssuesReviewsFirst ContributionSupportFeedback

Prove

Builders Directory

Account

Sign in

Legal

PrivacyTermsCredits

© 2026 Pull // code MIT · curriculum CC BY-SA 4.0

PrivacyTermsCredits

lesson // lightning

LNURL

Implement LNURL-withdraw, pay, and auth for better wallet UX.

intermediate4 days

Public lesson — sign in to track progress on this roadmap.

./sign-in

On this page

Learning objectives

  • Explain LNURL as bech32-wrapped HTTP endpoints
  • Implement pay and withdraw flows safely
  • Relate Lightning Addresses to LNURL-pay

study // plan

Lessons are primers. Start with Step 1 (required reading) when present, then follow the numbered steps in the article. Depth comes from primary sources, labs, reflection, and evidence.

Research on Bitcoin Search
LNURLLightning AddressLNURL-payLNURL-withdrawBOLT11

Step 1 // Required reading

Complete these before the numbered steps in the lesson body. Links are listed here once — not repeated below.

  • docsLNURL specifications

Reflection prompts

  1. Explain LNURL to a teammate without jargon - what problem does it solve?
  2. What would break in production if you misunderstood LNURL?
  3. Which BOLT (or implementation doc) is the source of truth for this topic, and what did you verify there?

Lab // LNURL-pay flow sketch

Complete Steps 2–3. Walk one LNURL LUD (pay or withdraw): list the HTTP steps and where the BOLT11 appears. Optionally hit a test LNURL-pay endpoint or Lightning Address resolver.

evidence required

  • ·Step list of the LNURL handshake (decode → HTTPS → invoice → pay)
  • ·Note relating Lightning Address to LNURL-pay
  • ·One security caution (TLS, amount check, or phishing)
  • ·Link to the LUD you read
  1. 01

    Worked mental model

    Re-read the diagrams in this lesson once out loud in plain language. If you cannot explain the flow to a friend without jargon, pause and revisit the Mastering Bitcoin / Mastering Lightning chapters linked in Resources. Chapter references are intentional, not decorative.

  2. 02

    Hands-on habit

    Every protocol idea should be paired with one local experiment. That habit turns reading into builder instinct.

    1. Reproduce the happy path on regtest (or Polar for Lightning)
    2. Break it on purpose (wrong fee, expired invoice, offline peer)
    3. Write down what error you saw and which layer produced it (wallet, node, mempool, peer)
  3. 03

    Glossary check

    Pick three terms from this lesson and define them in one sentence each without opening notes. Weak definitions mean the lesson is not finished yet.

  4. 04

    Resource order

    Use Resources in order: narrative book chapter first, then BIP/BOLT for precision, then implementation docs for commands. Jumping straight to RPC flags without the mental model creates brittle knowledge.

LNURL is a family of bech32-encoded URLs that help wallets interact with services over HTTPS for pay, withdraw, auth, and more. Lightning Addresses (name@domain) typically resolve to LNURL-pay.

Complete Step 1 // Required reading in the study plan above, then continue here. This closes Lightning Basics.

Step 2 — Core idea: short ticket → HTTPS → BOLT11

Users hate pasting huge BOLT11 strings. LNURL and Lightning Addresses make Lightning feel like emailing money — with server-side responsibilities you must secure.

Analogy: LNURL is a short coat-check ticket that maps to a locker (HTTPS API) where the real invoice is minted when you arrive.

Loading diagram…

LNURL-pay mints a fresh BOLT11 through an HTTPS handshake.
// Pseudo-flow
// 1) decode lnurl -> https URL
// 2) fetch JSON
// 3) request invoice for amount
// 4) pay bolt11

You inherit web risks

Phishing, TLS failures, and malicious metadata become Lightning UX risks. Validate domains and amounts carefully.

Done when: You can place Lightning Address on the LNURL-pay path in one sentence.

Step 3 — Sketch the handshake (lab)

Pick LNURL-pay or withdraw from the LUDs. List each HTTP step and where BOLT11 appears. Call out one security check your app must enforce.

Common mistakes

  • Trusting amounts displayed by a service without checking invoice fields
  • Skipping success/error URL handling on withdraw
  • Logging sensitive k1 secrets from auth flows

Done when: Lab evidence (step list + address note + security caution + LUD link) is complete. Complete the chapter quiz when prompted.

Next lesson

Opening Channels (Channels & HTLCs) — move from UX protocols to the capacity that carries payments.

further reading

  • articleLightning Address
  • docsAlby documentation

review // club

Chapter review picks

Practice on real Lightning OSS changes tied to this chapter. Read the diff, use the checklist, and optionally paste your review comment URL in your lab notes.

  • BOLT11 invoice format

    Walk through BOLT11 fields and decode a testnet invoice with your wallet or a CLI tool.

    spec review
    payment hashrouting hintsexpiry
    40 min·intermediateopen on GitHub
  • BOLT12 offers discussion

    Read the BOLT12 offer encoding spec and note how reusable offers differ from one-shot BOLT11 invoices.

    spec review
    interopinvoice UXencoding
    45 min·intermediateopen on GitHub
  • Open BOLT pull requests

    Review an open BOLT PR using the spec checklist: problem, interop, failure modes, tests.

    spec review
    rollouttest vectorsambiguity
    60 min·advancedopen on GitHub
review checklist
  1. Does the change solve the stated problem?
  2. Are edge cases and rollout behavior covered?
  3. Are tests or test vectors included?
  4. Is the diff minimal and clearly explained?

More repos and GFIs on /discover and /issues.

discussion

Discussion

prevBOLT12 OffersnextOpening Channels

On this page

Press Shift + ? for keyboard shortcuts.

Press R to research on Bitcoin Search.

No questions yet — be the first to ask.