The Buda Lightning Invoice API is a REST service that communicates exclusively over HTTPS and exchanges data as JSON. It wraps the Buda.com exchange API to let clients create Bitcoin Lightning Network invoices and verify payment status — without ever handling Buda.com credentials directly. All four endpoints are publicly accessible; no API key or token is required from consumers.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.
Base URL
During local development the base URL is
http://localhost:3001, assuming PORT=3001 is set in your .env file. If PORT is not defined, the server defaults to 8080.Authentication
API consumers do not need to authenticate. All Buda.com credentials (BUDA_API_KEY and BUDA_API_SECRET) are stored as server-side environment variables and are never exposed to clients. The server signs every outbound request to Buda.com using HMAC-SHA384 internally.
The only header you need to set on POST requests is Content-Type: application/json.
Content Type
POST endpoints read a JSON body. Always include theContent-Type: application/json header on those requests.
GET endpoints (/.well-known/lnurlp/:username and /callback) receive their parameters via URL query string — no request body or content-type header is needed.
Endpoints
Create Lightning Invoice
POST /newinvoice — Generate a new BOLT11 Lightning invoice for a given amount in satoshis.Check Invoice Status
POST /status — Verify whether a Lightning invoice has been paid and confirmed on Buda.com.LNURL-pay Metadata
GET /.well-known/lnurlp/:username — Return the LNURL-pay metadata document for a Lightning Address.LNURL-pay Callback
GET /callback — LNURL-pay callback that converts a millisatoshi amount into a BOLT11 invoice.HTTP Status Codes
| Code | Meaning |
|---|---|
200 OK | Request processed successfully. The response body contains the requested data. |
400 Bad Request | Validation error or Buda.com API error. The response body contains an errors object or an error string describing the problem. |
500 Internal Server Error | Unexpected server-side error not caught by application logic. |
Rate Limits
No explicit rate limiting is implemented at the API level. All requests are subject to:- Buda.com API rate limits — enforced upstream on every invoice creation and deposit lookup call.
- Fly.io infrastructure limits — platform-level request throttling on the
budalnapplication. - 5-second request timeout — the internal Buda.com HTTP client enforces a hard 5 000 ms timeout per outbound request. Requests that exceed this will return a
400application error.