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.php
use PhpLightning\Config\LightningConfig;

return (new LightningConfig())
    ->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.