This server application allows mobile apps that use the Breez SDK to register webhooks and exposes an LNURL pay endpoint for that app. It also acts as a bridge between the mobile app and payer.
- lnurlpay Registration: A mobile app registers a webhook to be reached by the server. The webhook is registered under a specific node pubkey. The server stores the pubkey and the webhook details in a database.
- LNURL Pay Endpoint: The server exposes an LNURL pay endpoint for the mobile app (lnurlp/pubkey).
- Bridge: When a payer starts the lnurl pay flow, the server receives the request and forwards it to the mobile app's webhook, providing a callback. The mobile app processes the request and responds via the callback. The server matches the response to the request and returns it to the payer.
-
Clone the repository:
git clone https://github.com/breez/breez-lnurl.git -
Navigate to the project directory:
cd breez-lnurl -
Install dependencies:
go mod tidy
- Create a database user for your application.
- For the initial setup and each time you pull this repo, check the
persist/migrationsdirectory for any additional migrations. - In sequence, run each of the SQL statements in the *.up.sql files in your prefered SQL query tool.
There are two optional environment variables that can be set:
- SERVER_EXTERNAL_URL: The url this server can be reached from the outside world.
- SERVER_INTERNAL_URL: The internal url the server listens to.
- DATABASE_URL: The database url. For DNS management of BIP353 records
- NAME_SERVER: The name server to connect to.
- DNS_PROTOCOL: The DNS protocol to use (one of "tcp", "tcp-tls" or "udp". Default "udp").
- TSIG_KEY: The TSIG key used to authenticate updates.
- TSIG_SECRET: The TSIG secret used to authenticate updates.
Execute the command below to start the server:
go run .
-
Register BOLT12 Offer:
- Endpoint:
/bolt12offer/{pubkey} - Method: POST
- Params:
pubkeyused to sign the request signature
- Payload (JSON):
timein seconds since epochusernamefor the BIP353 addressofferfor the username's BIP353 recordsignatureof "--"
- Description: Registers a new BOLT12 Offer.
- Endpoint:
-
Unregister BOLT12 Offer:
- Endpoint:
/bolt12offer/{pubkey} - Method: DELETE
- Params:
pubkeyused to sign the request signature
- Payload (JSON):
timein seconds since epochofferfor the pubkey's BIP353 recordsignatureof "-"
- Description: Unregisters a BOLT12 Offer.
- Endpoint:
-
Recover Registered Lightning Address:
- Endpoint:
/bolt12offer/{pubkey}/recover - Method: POST
- Params:
pubkeyused to sign the request signature
- Payload (JSON):
timein seconds since epochofferfor the pubkey's BIP353 recordsignatureof "-"
- Description: Recovers the lightning address registered.
- Endpoint:
-
Register LNURL Webhook:
- Endpoint:
/lnurlpay/{pubkey} - Method: POST
- Params:
pubkeyused to sign the request signature
- Payload (JSON):
timein seconds since epochwebhook_urlto receive requests tousernamefor the lightning and BIP353 addresses (optional)offerfor the username's BIP353 record (optional)signatureof "-<webhook_url>" or "-<webhook_url>-" or "-<webhook_url>--"
- Description: Registers a new webhook for the mobile app.
- Endpoint:
-
Unregister LNURL Webhook:
- Endpoint:
/lnurlpay/{pubkey} - Method: DELETE
- Params:
pubkeyused to sign the request signature
- Payload (JSON):
timein seconds since epochwebhook_urlto receive requests tosignatureof "-<webhook_url>"
- Description: Unregisters a webhook from the LNURL service.
- Endpoint:
-
Recover Registered LNURL and Lightning Address:
- Endpoint:
/lnurlpay/{pubkey}/recover - Method: POST
- Params:
pubkeyused to sign the request signature
- Payload (JSON):
timein seconds since epochwebhook_urlto receive requests tosignatureof "-<webhook_url>"
- Description: Recovers the LNURL and lightning address registered.
- Endpoint:
-
LNURL Pay Info Endpoint:
- Endpoint:
lnurlp/{identifier} - Method: GET
- Params:
identifierrepresents the pubkey or username registered
- Description: Handles LNURL pay requests, forwarding them to the corresponding mobile app webhook.
- Endpoint:
-
LNURL Pay Invoice Endpoint:
- Endpoint:
lnurlpay/{identifier}/invoice?amount=<amount> - Method: GET
- Params:
identifier: represents the pubkey or username registeredamount: invoice amount in millisatoshi
- Description: Handles LNURL pay invoice requests, forwarding them to the corresponding mobile app webhook.
- Endpoint:
-
Webhook Callback Endpoint:
- Endpoint:
/response/{responseID} - Method: POST
- Description: Handles webhook callback responses from the node.
- Endpoint: