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.

By the end of this guide you will have the Buda Lightning Invoice service running on your local machine, a real BOLT11 Lightning invoice generated through your Buda.com account, and a confirmed payment status check — all in under five minutes.
The production deployment lives at https://budaln.fly.dev. Use that base URL if you want to test against the hosted instance instead of running locally.
1

Clone the repository and install dependencies

Clone the project from GitHub and install its npm dependencies:
git clone https://github.com/nicosaporiti/buda-lightning-invoice.git
cd buda-lightning-invoice
npm install
This installs Express, express-validator, dotenv, cors, and the rest of the runtime dependencies listed in package.json.
2

Configure your environment

Create a .env file at the project root with your Buda.com credentials and optional server settings:
PORT=3001
BUDA_API_KEY=your_key
BUDA_API_SECRET=your_secret
DOMAIN=your-domain.com
PORT and DOMAIN are both optional. If omitted, the server defaults to port 8080 (matching the Fly.io configuration) and derives the domain from the incoming request’s Host header. BUDA_API_KEY and BUDA_API_SECRET are required — without them the service cannot authenticate with Buda.com.See the Configuration page for a full description of every variable.
3

Start the server

Start in development mode with hot reload powered by nodemon:
npm run dev
Or start without hot reload for a production-like environment:
npm start
Either command prints the following when the server is ready:
Listening at port 3001
4

Create your first invoice

With the server running, send a POST request to /newinvoice with an amount in satoshis and a short memo:
curl -X POST http://localhost:3001/newinvoice \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "msg": "Coffee payment"}'
A successful response returns the BOLT11 invoice string along with the values you submitted:
{
  "invoice": "lnbc10u1p...",
  "amount": 1000,
  "msg": "Coffee payment"
}
Copy the invoice value — you will need it in the next step.
5

Check payment status

To verify whether the invoice has been paid, send a POST request to /status with the invoice string:
curl -X POST http://localhost:3001/status \
  -H "Content-Type: application/json" \
  -d '{"invoice": "lnbc10u1p..."}'
The response echoes the invoice and returns a boolean status field:
{
  "invoice": "lnbc10u1p...",
  "status": false
}
status is false until the invoice is paid and the corresponding deposit reaches a confirmed state on Buda.com. Poll this endpoint after sending payment from a Lightning wallet to see it flip to true.

Configuration

Learn about every environment variable and how to obtain your Buda.com API credentials.

API Reference

Explore the full request and response schemas for all four endpoints.

Build docs developers (and LLMs) love

Get started for freeTalk to us