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.

Buda Lightning Invoice wraps the Buda.com REST API using a local client — buda-promise/buda.js — that handles all authentication and request signing on the server side. API consumers (your frontend or integration code) call the simple HTTP endpoints this service exposes and never need to know about Buda credentials or how to construct authenticated requests. The BUDA_API_KEY and BUDA_API_SECRET environment variables stay on the server, invisible to callers.

​
HMAC-SHA384 Authentication

Every private Buda.com API call is signed using HMAC-SHA384. The signing algorithm is implemented in Buda.prototype._authHeader and Buda.prototype._generateNonce inside buda-promise/buda.js. Nonce generation The nonce is a timestamp-plus-counter string that guarantees uniqueness even for multiple calls within the same millisecond: 
// now = current Unix timestamp in ms
// nonceIncr = 0–999, reset each new millisecond
// padding = '000', '00', '0', or '' depending on nonceIncr magnitude
nonce = now + padding + nonceIncr
// e.g. "1704067200000" + "000" + "0" → "17040672000000000"
This supports up to 999 authenticated requests per millisecond without nonce collisions. Message construction The message to sign depends on whether the request includes a body: 
# Without a request body (e.g. GET requests):
METHOD + ' ' + PATH + ' ' + NONCE

# With a request body (e.g. POST requests):
METHOD + ' ' + PATH + ' ' + BASE64(JSON(body)) + ' ' + NONCE
Examples: 
# GET deposits:
GET /api/v2/currencies/btc/deposits 17040672000000000

# POST new invoice (body base64-encoded):
POST /api/v2/lightning_network_invoices eyJhbW91bnRfc2F0b3NoaXMiOjUwMDB9 17040672000000001
Signature computation 
signature = HMAC-SHA384(api_secret, message).digest('hex')
Headers sent with every authenticated request 
X-SBTC-APIKEY:     <your Buda API key>
X-SBTC-NONCE:      <generated nonce>
X-SBTC-SIGNATURE:  <HMAC-SHA384 hex signature>
Never expose BUDA_API_KEY or BUDA_API_SECRET in client-side code, public repositories, or frontend bundles. These credentials grant full access to your Buda.com account — including withdrawals. They must only exist as server-side environment variables.

​
Buda API Calls Made by This Service

Only two Buda endpoints are used in the current service implementation. Both require authentication. 1. Create a Lightning invoice — POST /api/v2/lightning_network_invoices Called by helpers/getInvoice.js whenever POST /newinvoice or GET /callback is invoked. Request payload: 
{
  "amount_satoshis": 5000,
  "currency": "BTC",
  "memo": "Asado contribution",
  "expiry_seconds": false
}
expiry_seconds: false instructs Buda to apply its default invoice expiry. The response includes an invoice object from which the service extracts encoded_payment_request — the BOLT11 string returned to the caller. 2. Fetch BTC deposits — GET /api/v2/currencies/btc/deposits Called by helpers/getPaymentConfirmation.js whenever POST /status is invoked. The response contains a deposits array. The service scans every element looking for one where both conditions are true: 
e.deposit_data.invoice.encoded_payment_request === invoice
  && e.state === 'confirmed'
If a matching confirmed deposit is found, status: true is returned. Otherwise status: false.

​
Error Propagation

Buda API errors are caught inside Buda.prototype._request and re-thrown as a JavaScript Error with a consistent message format: 
// HTTP error (e.g. 401, 422):
message = 'Buda error ' + err.statusCode + ': ' + JSON.stringify(err.response.body);

// HTTP 404 specifically:
message = 'Buda error 404: Not found';

// Network / timeout error:
message = 'Buda error: ' + err.message;
These error messages bubble up through the helpers to the controllers, which catch them and return a 400 response: 
{
  "ok": false,
  "error": "Buda error 422: {\"message\":\"invalid amount\"}"
}
Your integration code should check for ok: false in any 400 response and surface the error string to aid debugging.

​
Available Buda Client Methods

buda-promise/buda.js exposes a full set of Buda.com API methods beyond the two used by this service. If you extend the project, these are available:
MethodAuth requiredDescription
ticker(market)NoLatest ticker data for a market
order_book(market)NoCurrent order book for a market
trades(market, timestamp)NoRecent trades for a market
markets()NoList all available markets
fees(currency, type)NoDeposit/withdrawal fee schedules
get_quotation(market, type, amount, limit)YesGet a price quotation
balance(currency)YesAccount balance for a currency
order_pages(market, per, page, state, minimun_exchanged)YesPaginated order history
new_order(market, type, price_type, limit, amount)YesPlace a new buy/sell order
cancel_order(order_id)YesCancel an open order
single_order(order_id)YesFetch a single order’s status
deposits(currency, per, page, state)YesList deposits for a currency ✦
withdrawals(currency, per, page, state)YesList withdrawals for a currency
withdrawal(currency, amount, target_address, simulate)YesInitiate a crypto withdrawal
lightning_withdrawal(amount, invoice, simulate)YesSend a Lightning payment
lightning_network_invoices(amount, currency, memo, expiry_seconds)YesCreate a Lightning invoice ✦
new_fiat_deposit(currency, amount, simulate)YesInitiate a fiat deposit
new_crypto_address(currency)YesGenerate a new deposit address
get_address(currency, address_id)YesFetch an existing deposit address
✦ These are the two methods actively used by the service today.

Build docs developers (and LLMs) love

Get started for freeTalk to us