> For the complete documentation index, see [llms.txt](https://docs.sms4sats.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sms4sats.com/send-sms/top-up.md).

# 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

```bash
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:

```json
{
  "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:

```bash
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

```bash
curl -sS 'https://api.sms4sats.com/balance' \
  -H 'X-API-Key: YOUR_SECRET_API_KEY'
```

```json
{"status":"OK","balance":3000}
```

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

```bash
curl -sS 'https://api.sms4sats.com/history' \
  -H 'X-API-Key: YOUR_SECRET_API_KEY'
```

The legacy response is:

```json
{
  "status": "OK",
  "orders": [],
  "totalAmount": 0
}
```

`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.
