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.

This endpoint creates a new Bitcoin Lightning Network BOLT11 invoice by forwarding your request to Buda.com’s POST /api/v2/lightning_network_invoices. The server authenticates with Buda.com using server-side HMAC-SHA384 credentials — no API keys are required from you. On success it returns the encoded payment request string, which can be displayed as a QR code or pasted directly into any Lightning-compatible wallet. 
POST /newinvoice

​
Request

Content-Type: application/json
​
amount
integer
required
Amount in satoshis. Must be an integer greater than or equal to 1. Note that the /callback LNURL-pay endpoint uses millisatoshis instead; this endpoint always expects whole satoshis.
​
msg
string
required
Invoice description or memo that appears in the payer’s wallet. Minimum length: 1 character.

​
Response (200 OK)

​
invoice
string
BOLT11-encoded payment request string. Starts with lnbc on mainnet. Pass this value to POST /status to poll for payment confirmation.
​
amount
integer
The amount from the request, echoed back in satoshis.
​
msg
string
The description from the request, echoed back.
The invoice field is a standard BOLT11 payment request that starts with lnbc on the Bitcoin mainnet. It is universally compatible with Lightning wallets such as Phoenix, Wallet of Satoshi, Muun, Zeus, and any other BOLT11-compliant application.

​
Error Responses

All errors return HTTP 400 Bad Request. Validation error — returned when amount or msg fail the input checks: 
{
  "ok": false,
  "errors": {
    "amount": {
      "value": "abc",
      "msg": "Ingrese un número entero mayor a 1",
      "param": "amount",
      "location": "body"
    },
    "msg": {
      "value": "",
      "msg": "Debe ingresar un mensaje",
      "param": "msg",
      "location": "body"
    }
  }
}
Only the fields that failed validation appear inside errors. A request with a valid amount but missing msg will only include the msg key. Buda API error — returned when Buda.com’s API rejects the request (e.g. invalid credentials, service unavailable): 
{
  "ok": false,
  "error": "Buda error 422: ..."
}

​
Examples

curl -X POST https://budaln.fly.dev/newinvoice \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "msg": "Coffee payment"
  }'

​
Success response

{
  "invoice": "lnbc10u1p3q9h7zpp5...",
  "amount": 1000,
  "msg": "Coffee payment"
}

​
Validation error response

{
  "ok": false,
  "errors": {
    "amount": {
      "value": 0,
      "msg": "Ingrese un número entero mayor a 1",
      "param": "amount",
      "location": "body"
    }
  }
}
After creating an invoice, poll POST /status with the returned invoice string every 5–10 seconds to detect when the payer has confirmed their Lightning payment. See the Check Invoice Status page for a ready-made polling example.

Build docs developers (and LLMs) love

Get started for freeTalk to us