Lightning Network API

API Reference

Programmatic access to Ramper: connect Bitcoin to local economies with the right tool per country. Generate BOLT11 invoices, route M-Pesa in Kenya and Tanzania, and track every step via the ops runbook. All endpoints accept and return JSON over HTTP.

Base URL https://www.usebreezee.xyz

POST

/api/invoice/generate

Generate Lightning Invoice

POST

/api/invoice/status

Check Invoice Status

Authentication

This API is currently open and requires no authentication. Simply send a POST request with a JSON body to any endpoint. All requests should include Content-Type: application/json.

POST/api/invoice/generate

Generate Lightning Invoice

Generate a BOLT11 Lightning Network invoice from a Lightning Address or LNURL. Supports both the human-readable format (user@domain.com) and raw LNURL bech32 strings. The response includes the invoice, an optional verify link for polling payment status, and a preimage if returned by the recipient wallet. Note: expirySeconds is forwarded as a hint in the callback URL, but most Lightning services do not honour it — the LNURL-pay standard (LUD-06) does not require it. The response always includes the actual expiry decoded from the returned BOLT11.

Request Body

Field	Type	Required	Description
address	string	required	Lightning Address (user@domain.com) or LNURL bech32 string
amount	number	required	Payment amount in satoshis (must be greater than 0)
expirySeconds	number	optional	Invoice expiry time in seconds. Defaults to 300 (5 minutes)

Response200 OK

Field	Type	Required	Description
success	boolean	—	Whether the invoice was generated successfully
invoice	string	—	BOLT11 encoded payment request string (lnbc...)
verifyLink	string \| null	—	LNURL-verify URL to poll for payment confirmation
preimage	string \| null	—	Payment preimage returned by the recipient wallet, if available
expirySeconds	number \| null	—	Actual expiry encoded in the returned BOLT11 invoice. May differ from requestedExpirySeconds — most services ignore the expiry hint.
requestedExpirySeconds	number	—	The expiry value you passed in the request (or 300 if omitted)
expiryHonored	boolean	—	Whether the service set an expiry matching what you requested. Most LNURL-pay services ignore the expiry parameter (LUD-06 does not require it).

Error Responses

400Missing or invalid parameters — address and amount are required; amount must be > 0

502The Lightning service returned invalid or empty invoice data

504Gateway timeout — the upstream Lightning service did not respond in time

500Unexpected server error

Code Examples

cURL

curl -X POST https://yourapp.com/api/invoice/generate \
  -H "Content-Type: application/json" \
  -d '{
    "address": "satoshi@walletofsatoshi.com",
    "amount": 1000,
    "expirySeconds": 300
  }'

Try it live

POST/api/invoice/generate

addressrequired·string

amountrequired·number

expirySeconds·number

POST/api/invoice/status

Check Invoice Status

Decode a BOLT11 invoice and return its current status. This is a pure local decoding operation — it reads the timestamp and expiry embedded in the invoice string without making any external network calls, so it is always fast and reliable regardless of the Lightning service state.

Request Body

Field	Type	Required	Description
invoice	string	required	BOLT11 encoded invoice string starting with lnbc...

Response200 OK

Field	Type	Required	Description
status	"active" \| "expired" \| "unknown"	—	Current lifecycle state of the invoice
expiry	number	—	Minutes remaining until expiry. Returns 0 when expired or when status is unknown.
expiresIn	number \| undefined	—	Exact seconds until expiry. Only present when status is active.

Error Responses

400Invoice field is missing from the request body

500Failed to decode the BOLT11 string — may be malformed

Code Examples

cURL

curl -X POST https://yourapp.com/api/invoice/status \
  -H "Content-Type: application/json" \
  -d '{"invoice":"lnbc1000n1p..."}'

Try it live

POST/api/invoice/status

invoicerequired·string

Ramper API · v1.0

Back to app