How to Test a Lightning Address (and Fix One That Doesn't Work)

A Lightning Address looks like an email address (you@example.com), but every payment to it depends on the server behind its domain. When that server is down or misconfigured, payments fail, and the sender usually just sees a vague error.

Rizful's Lightning Address Tester checks any user@domain end to end, making the same requests a sender's wallet makes, and tells you which step breaks.

🔍 Try the Lightning Address Tester →

Step by Step

1. Type the address

Open the Lightning Address Tester and type the Lightning Address you want to check into the box. Here we test Rizful's own address, rizful@rizful.com.

Type the Lightning Address into the box

2. Click "Test address"

The tester now makes the same first request a sender's wallet makes, straight from your browser to the address's server.

Click 'Test address'

3. Read the lookup checks

The green headline sums up the result. Each line below it is one check: a green tick passes, a red cross fails and says what to fix, and a blue "i" tells you about extras such as comments and Nostr zaps.

The headline sums up the lookup; each line below is one check

4. Get a test invoice

The lookup proves the server answers, not that it makes a good invoice. To check the invoice a wallet would really pay, click "Get a test invoice". You won't pay anything.

Click 'Get a test invoice' to finish the test

5. Check the invoice

The tester checks the invoice that comes back: mainnet, the right amount, a description hash that matches the metadata, and an expiry that hasn't passed. The invoice is real, so don't pay it. If you see "You can't request another test invoice right now", you've reached the limit of about 10 test invoices a day.

Every invoice check passes, including the description hash

6. Share the result

"Copy Link" copies a link that opens the tester on the same address. Send it to the address's provider when a check fails.

Click 'Copy Link' to share the test

What Is a Lightning Address?

A Lightning Address is for receiving bitcoin over the Lightning Network. Instead of making a new invoice for every payment, you share one address, and the sender's wallet asks your provider for a fresh invoice each time it pays.

It's an open standard, LUD-16, built on LNURL-pay (LUD-06), and most Lightning wallets can pay one.

Unlike an invoice, it's reusable. Put it in your Nostr profile, on your website or in your email signature, and it keeps working for as long as the server behind it does.

How a Payment to a Lightning Address Works

1. The wallet splits the address. alice@example.com becomes the name alice and the domain example.com.
2. It asks the domain. GET https://example.com/.well-known/lnurlp/alice returns a callback URL, the minimum and maximum amounts, and the metadata, which carries the description.
3. It asks for an invoice. callback?amount=<msat> returns a BOLT11 invoice for exactly that amount, in millisatoshis.
4. It checks and pays. The invoice must be for the amount asked for, and its description hash must be the SHA-256 of the metadata from step 2. Then the wallet pays it like any other invoice.

Steps 2 and 3 happen for every payment, so the address only works while its server is online.

What the Tester Checks

1. The LNURL-pay response. The address format, and that https://<domain>/.well-known/lnurlp/<user> answers over HTTPS with valid JSON and "tag": "payRequest".
2. CORS. Whether the server sends an Access-Control-Allow-Origin header. Without it, a web page can't read the answer, so web wallets and browser extensions can't pay the address.
3. The payment details. The callback URL, the minimum and maximum amounts, and the metadata: a text/plain description, plus the text/identifier entry that LUD-16 asks for.
4. Extras. Support for comments (LUD-12), Nostr zaps (NIP-57), payer data (LUD-18) and payment verification (LUD-21).
5. A live test invoice (optional). The tester asks the server for a real invoice and checks that it's a mainnet BOLT11 invoice for exactly the amount requested, with a description hash that matches the metadata, and that it isn't already expired. If the receiving node is in Rizful's copy of the Lightning graph, you'll see which node it is. You can ask for about 10 test invoices a day.

The test invoice is real, so don't pay it: that would send real sats to whoever owns the address. The checks are done as soon as the invoice arrives.

Lightning Address Not Working? The Usual Causes

• No CORS header. Phone wallets can pay, but web and extension wallets fail.
• Description hash mismatch. The invoice's description hash isn't the SHA-256 of the metadata string from the first response. Strict wallets refuse to pay it.
• Wrong amount. The invoice isn't for the amount the wallet asked for, or has no amount at all.
• 404, or the server is down. The name is misspelled, the account was closed, or the provider's server is offline.
• Capital letters. LUD-16 names are lowercase (a-z 0-9 - _ . +). Some wallets lowercase what you type, so a server that only knows Alice breaks when someone pays alice.
• Amount limits. The payment is below the server's minimum or above its maximum.

How to Fix It

If You Run the Server

Each failed check in the tester says what needs fixing. The usual fixes:

• CORS: send Access-Control-Allow-Origin: * on both /.well-known/lnurlp/<name> and the callback. A wallet that can read the first answer but not the second still fails.
• The first response: JSON over HTTPS, with "tag": "payRequest", a callback, minSendable and maxSendable (in millisatoshis) and metadata.
• Metadata: a JSON array, sent as a string, with a text/plain description and a text/identifier entry holding the address itself.
• Description hash: hash the exact metadata string you return in the first response (UTF-8), byte for byte. If you rebuild the JSON before hashing, a different key order or spacing gives a different hash.
• Amount: make the invoice for exactly the amount in the callback request. It's in millisatoshis, not sats.
• Expiry: if the invoice arrives already expired, check the server's clock and the expiry you set.
• Names: store and look up names in lowercase.
• Limits: set minSendable and maxSendable to amounts your node can really receive.

If You Don't

Send the result to the address's provider. A link with the address in it, like https://rizful.com/lightning-address?address=name@domain.com, opens the tester on that address, so they can run the same test.

Privacy First

The test runs in your browser: your browser sends the LNURL and invoice requests straight to the address's own server, not through Rizful's servers. That provider sees the test requests, as it sees every payment request made to the address.

Questions

What's the difference between a Lightning Address and a Lightning invoice?

An invoice (it starts with lnbc) is for one payment: usually a fixed amount, paid once, and it expires, often within an hour. A Lightning Address is reusable: it takes any amount within the server's limits and never expires, but it only works while the server behind it is online. To see what's inside an invoice, paste it into the Lightning invoice decoder.

Is a Lightning Address the same as an email address?

No, it only uses the same format. The address may or may not also receive email. Don't send bitcoin to someone's ordinary email address and expect it to arrive: test it first.

Is it safe to share my Lightning Address?

Yes. It can only receive: people can use it to send you sats, not to take them. It's public, like an email address, and the provider behind it sees every request made to it.

Need a Lightning Address?

Rizful is our free hosted Lightning wallet: it runs in any web browser, gives you a Lightning address and NWC codes, and is always online to receive. Its Lightning Addresses pass every check in the tester. Create a free account, then follow the first steps guide to pick your address.

🔍 Test a Lightning Address Now →