Top Up & Balances
Fund an SMS4Sats send-SMS account with Lightning and check its prepaid satoshi balance.
All amounts are satoshis, not millisatoshis, dollars, or BTC decimals. Use the same secret X-API-Key for funding, balance checks, history, and prepaid sending.
1. Create a top-up invoice
curl -sS -X POST 'https://api.sms4sats.com/fund' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_SECRET_API_KEY' \
--data '{"amount":3000}'amount must be a positive safe integer. A digits-only string is also accepted for compatibility. A successful response has the original shape:
{
"status": "OK",
"orderId": "<order-id>",
"payreq": "<bolt11-invoice>"
}This creates an invoice; it does not credit your balance yet.
2. Pay the invoice
Pay the returned payreq using a Lightning wallet that supports hold invoices. Your prepaid balance becomes available after the payment is confirmed. Check /balance before sending.
Keep the returned orderId. You can poll:
curl -sS 'https://api.sms4sats.com/orderstatus?orderId=ORDER_ID'The returned paid flag describes the order's recorded payment state. Confirm the balance increase before sending against it. Invoice creation, or payment being held, is not by itself proof of available credit.
3. Check your balance
The numeric value above is an example. An account without an existing balance returns zero. Existing legacy keys continue reading their existing balances; no re-registration is required.
Funding history
The legacy response is:
orders contains paid funding/account history for your API key. For compatibility, totalAmount may be a number or string and is not your current spendable balance. Use /balance for available credit.
Common errors
HTTP status
reason
Meaning
400
X-API-Key header is missing.
Supply the header
400
X-API-Key header is invalid.
The key does not meet the legacy key rules
400
amount is required.
Missing or invalid top-up amount
500
backend error
Invoice backend returned an unsuccessful response
500
backend invoice error
Invoice initialization failed
500
unable to save data
Order persistence failed
500
unable to create invoice
No usable invoice was returned
500
server error
Balance lookup failed (/balance)
500
Exception message
Funding history lookup failed (/history)
A network timeout is ambiguous: do not assume the original request was never processed. Preserve any returned order ID and reconcile its payment/balance before creating another top-up.
Last updated