Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nicosaporiti/buda-lightning-invoice/llms.txt

Use this file to discover all available pages before exploring further.

A Lightning Address is an internet identifier that looks exactly like an email address — for example, nicolas@yourdomain.com — but instead of routing to a mailbox, it routes to a Lightning Network payment endpoint. When a compatible wallet pays to a Lightning Address, it silently resolves the address to a BOLT11 invoice using a well-defined HTTP flow. Buda Lightning Invoice implements the two HTTP endpoints this flow requires, so once you deploy the service under your own domain, anyone can pay you using your Lightning Address without needing to know anything about LNURL or Buda internals.

​
What Is a Lightning Address?

The Lightning Address format is username@domain.com. It is a human-readable alias built on top of the LNURL-pay protocol (LUD-06). When a wallet encounters a Lightning Address, it performs the following sequence automatically:
1

Fetch payment metadata

The wallet constructs the metadata URL from the address and fetches it:
GET https://domain.com/.well-known/lnurlp/username
2

Read the callback URL

The wallet parses the JSON response and extracts the callback URL, along with the minSendable and maxSendable limits (in millisatoshis).
3

Request an invoice

The wallet calls the callback URL with the desired amount in millisatoshis:
GET {callback}?amount={msats}
4

Pay the invoice

The wallet receives a BOLT11 invoice in the pr field of the response and pays it over the Lightning Network.
All Lightning Address usernames at your domain resolve to the same Buda.com account. The username segment in /.well-known/lnurlp/:username is only used to personalise the metadata description ("Pago Lightning a {username}"). Any string before the @ will work — alice@yourdomain.com, donations@yourdomain.com, and bob@yourdomain.com all create invoices on the single configured Buda account.

​
The Two Endpoints

​
GET /.well-known/lnurlp/:username — Payment metadata

This is the first endpoint a wallet hits. It returns static metadata describing the payment endpoint. Example request: 
curl https://yourdomain.com/.well-known/lnurlp/nicolas
Response: 
{
  "callback": "https://yourdomain.com/callback",
  "maxSendable": 100000000,
  "minSendable": 1000,
  "metadata": "[[\"text/plain\",\"Pago Lightning a nicolas\"]]",
  "tag": "payRequest",
  "commentAllowed": 140
}
Key fields:
FieldValueNotes
callbackhttps://{DOMAIN}/callbackBuilt from the DOMAIN env var, or falls back to the request’s Host header
minSendable1000Minimum sendable amount in millisatoshis (= 1 sat)
maxSendable100000000Maximum sendable amount in millisatoshis (= 100,000 sat)
metadataJSON-encoded arrayContains the plain-text description for the invoice
tag"payRequest"Required LNURL-pay discriminator
commentAllowed140Maximum comment length in characters (LUD-09)

​
GET /callback — Invoice generation

After reading the metadata, the wallet calls this endpoint with the payment amount. Query parameters:
ParameterRequiredDescription
amountYesAmount in millisatoshis (integer ≥ 1000)
commentNoOptional memo; defaults to "Pago desde Lightning Address"
Example request: 
curl "https://yourdomain.com/callback?amount=5000000&comment=Gracias"
Response: 
{
  "pr": "lnbc50u1p3q9h8app5...",
  "successAction": {
    "tag": "message",
    "message": "Gracias por tu pago"
  },
  "routes": []
}
The amount is converted from millisatoshis to satoshis internally (amount / 1000) before the invoice is created through Buda. The successAction message is displayed by the wallet after the payment settles.

​
Setting Up Your Lightning Address

1

Configure the DOMAIN environment variable

Set DOMAIN to your public hostname when deploying. This is used to build the callback URL in the metadata response.Locally (.env file):
DOMAIN=yourdomain.com
On Fly.io:
fly secrets set DOMAIN=yourdomain.com
If DOMAIN is not set, the service falls back to the Host header of each incoming request.
2

Deploy the service under your domain

Ensure your domain’s DNS and TLS are configured so that https://yourdomain.com reaches the running service. The /.well-known/lnurlp/:username route is handled automatically — no extra web server configuration is needed.
3

Choose your Lightning Address username(s)

Because all usernames resolve to the same account, you can use any identifier you like — your name, a project name, or a generic word like donations. Share it in the format username@yourdomain.com.
4

Test with a compatible wallet

Send a small payment from a Lightning Address-compatible wallet (e.g. Wallet of Satoshi, Phoenix, Zeus, Muun) to verify the full flow end-to-end.

​
Complete Wallet Interaction Example

The following shows the exact JSON exchanged during a wallet-to-Lightning-Address payment flow. Step 1 — Wallet fetches metadata: 
GET https://yourdomain.com/.well-known/lnurlp/nicolas

{
  "callback": "https://yourdomain.com/callback",
  "maxSendable": 100000000,
  "minSendable": 1000,
  "metadata": "[[\"text/plain\",\"Pago Lightning a nicolas\"]]",
  "tag": "payRequest",
  "commentAllowed": 140
}
Step 2 — Wallet calls callback for a 5,000-satoshi invoice (5,000,000 msats): 
GET https://yourdomain.com/callback?amount=5000000&comment=Great+work

{
  "pr": "lnbc50u1p3q9h8app5xkzqlafes8y3akuqr4n...",
  "successAction": {
    "tag": "message",
    "message": "Gracias por tu pago"
  },
  "routes": []
}
The wallet pays the invoice in pr and shows the successAction.message to the user upon settlement.

​
Spec Compliance

This service implements two LNURL specifications from the LNURL Documents (LUDs) repository:
SpecTitleHow it is implemented
LUD-06LNURL-pay/.well-known/lnurlp/:username metadata endpoint + /callback invoice endpoint
LUD-09successAction and commentAllowedcommentAllowed: 140 in metadata; successAction with tag: "message" in callback response
The Lightning Address standard itself (mapping user@domain to /.well-known/lnurlp/user) is defined in the Lightning Address specification and builds on top of LUD-06.

Build docs developers (and LLMs) love

Get started for freeTalk to us