Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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