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 verifies whether a Lightning invoice has been paid by querying Buda.com’s BTC deposit history. It searches all confirmed deposits for one whose deposit_data.invoice.encoded_payment_request matches the invoice string you provide. Because the check happens server-side against the authenticated Buda.com account, no API credentials are needed from you — only the BOLT11 payment request returned by POST /newinvoice. 
POST /status

​
Request

Content-Type: application/json
​
invoice
string
required
The BOLT11 payment request string to check. This is the exact value returned in the invoice field by POST /newinvoice. The string begins with lnbc on mainnet.

​
Response (200 OK)

​
invoice
string
The invoice from the request, echoed back unchanged.
​
status
boolean
true if the invoice has been paid and the corresponding deposit is in the confirmed state in Buda. false in all other cases — unpaid, pending, expired, or not found.
status is a boolean, not a string. Always compare it with === true (JavaScript) or is True (Python). Checking === 'confirmed' or === 'true' will always evaluate to false and silently break your payment flow.

​
Status Logic

The server executes the following steps to determine payment status:
  1. Calls Buda.com’s authenticated endpoint GET /api/v2/currencies/btc/deposits to retrieve the full deposit history for the account.
  2. Searches the resulting list for a deposit where both conditions hold:
    • deposit_data.invoice.encoded_payment_request === invoice (exact string match)
    • state === 'confirmed'
  3. If a matching confirmed deposit is found, returns { status: true }. Otherwise returns { status: false }.
A deposit that exists but has state equal to "pending" or any other non-confirmed value will yield false — the payment has arrived on-chain/off-chain but has not yet been fully settled by Buda.

​
Error Responses

All errors return HTTP 400 Bad Request. Validation error — returned when invoice is missing or not a string: 
{
  "ok": false,
  "errors": {
    "invoice": {
      "value": "",
      "msg": "Ingrese invoice",
      "param": "invoice",
      "location": "body"
    }
  }
}
Buda API error — returned when Buda.com’s deposit endpoint is unreachable or returns an error: 
{
  "ok": false,
  "error": "Buda error 401: ..."
}

​
Examples

curl -X POST https://budaln.fly.dev/status \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": "lnbc10u1p3q9h7zpp5..."
  }'

{ "invoice": "lnbc10u1p3q9h7zpp5...", "status": true }

​
Unpaid / pending response

{ "invoice": "lnbc10u1p3q9h7zpp5...", "status": false }
Use a polling interval of 5–10 seconds to keep your integration responsive without hammering the Buda API. Intervals shorter than 5 seconds offer no practical benefit because Lightning settlements typically complete within a few seconds, and the Buda deposit list only refreshes on a similar cadence.

Build docs developers (and LLMs) love

Get started for freeTalk to us