PHP Lightning Address

Self-host your own Lightning Address in PHP: a human-readable identifier like you@yourdomain.com that any Lightning wallet can pay. It implements LNURL-pay (LUD-06) and is backend-agnostic — LNbits is the backend available today. Built on the Gacela framework.

Quick start

Requires PHP >= 8.3 and an LNbits wallet API key.

composer require php-lightning/lnaddress # or clone this repo + composer install
cp lightning-config.dist.php lightning-config.php # settings
cp backends.dist.json backends.json # per-user invoice backends
composer serve # http://localhost:8080

curl 'http://localhost:8080/bob'# → LNURL-pay params
curl 'http://localhost:8080/bob?amount=2000'# → bolt11 invoice (2000 millisats)

// lightning-config.phpusePhpLightning\Config\LightningConfig;
return (newLightningConfig())
->setDomain('yourdomain.com')
->setReceiver('default-receiver')
->setDescriptionTemplate('Pay to %s') // %s = the lightning address
->setSuccessMessage('Thanks for the payment!')
->setSendableRange(min: 100_000, max: 10_000_000_000) // millisats
->setCallbackUrl('https://yourdomain.com')
->addBackendsFile(getcwd() . '/backends.json');

// backends.json
{
"bob": { "type": "lnbits", "api_key": "abc...123", "api_endpoint": "http://localhost:5000" },
"alice": { "type": "lnbits", "api_key": "def...456", "api_endpoint": "http://localhost:5000" }
}

Wallets resolve bob@yourdomain.com through https://yourdomain.com/.well-known/lnurlp/bob, so route that path to this app's /{username} over HTTPS.

Documentation

Guide	Contents
Getting started	Install, configure, run, deploy
Configuration	Every setter, defaults, backends file
HTTP API	Routes, payloads, CORS, error objects
Architecture	Modules, layers, adding a backend
Development	Scripts, tests, static analysis, releasing

Also: project page · CHANGELOG · wiki · demo template

Development

composer test-all # php-cs-fixer + psalm + phpstan + phpunit + rector (dry-run)
composer fix # apply php-cs-fixer and rector changes

Contributing

Issues and pull requests are welcome — read CONTRIBUTING and the Code of Conduct, and run composer test-all first.

License

MIT — see LICENSE.