# Wallet balances, statements and pagination

Read the balance, walk a statement with cursor pagination, and reconcile a day, with code in Node.js and Python.

## Wallets, balances and statements

A wallet is where your money sits. Collections credit it, payouts debit it, and every movement is a transaction with an id, an externalref and a time. You read the balance with Account Status and the history with List Transactions, which uses cursor pagination so you can read as much as you need without missing or repeating a row.

Statements are the basis of reconciliation: you compare them with your own records, row by row.

| I want to | Use | Credential |
| --- | --- | --- |
| See the balance | Account Status (type 1) | Private key |
| See the history | List Transactions (Account Status type 2) | Private key |
| See one payment or payout | Payment Status or Transfer Status | Public or private key |
| See payments to a Payment ID or bank account | List Payment ID Transactions, List Bank Account Transactions | Public key |

## Step by step: read the balance



1. Call Account Status with type 1 and your accountnumber.
2. Read data: it holds the wallet details and the balance.
3. Compare the balance with what you expect: the starting balance plus collections minus payouts and fees. Treat a surprise as something to investigate, not to ignore.

```curl
curl https://api.moolre.com/open/account/status \
  -H "Content-Type: application/json" \
  -H "X-API-USER: $MOOLRE_USER" \
  -H "X-API-KEY: $MOOLRE_KEY" \
  -d '{
    "type": 1,
    "accountnumber": "1000000000001"
  }'
```

```json
{
  "status": 1,
  "code": "SW01",
  "message": "Wallet Found",
  "data": {
    "accountnumber": "1000000000001",
    "accountname": "Main Business Wallet",
    "balance": "1250.00",
    "currency": "GHS"
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

- [Account Status](https://docs.moolre.com/api/accounts/status)

## Step by step: read a statement



1. Call List Transactions (Account Status with type 2) with your accountnumber and a date range. from and to take YYYY-MM-DD or an ISO 8601 UTC time; a from date without a time starts at the beginning of that day, a to date without a time ends at the end of it. The older startdate and enddate still work and win if you send both.
2. Add status to filter: 0 pending, 1 successful, 2 failed.
3. Set limit. With a cursor the maximum is 100 rows per page.
4. Read data.transactions. Each row has txstatus, txtype, payer, payee, amount, value, fee, networkfee, transactionid, externalref, thirdpartyref, the older ts and an ISO 8601 created_at.
5. If data.has_more is true, call again with starting_after set to data.next_cursor. Repeat until has_more is false.
6. Store the last next_cursor and the time you ran, so tomorrow's run starts where today's ended.

```curl
curl https://api.moolre.com/open/account/status \
  -H "Content-Type: application/json" \
  -H "X-API-USER: $MOOLRE_USER" \
  -H "X-API-KEY: $MOOLRE_KEY" \
  -d '{
    "type": 2,
    "accountnumber": "1000000000001",
    "from": "2026-11-01",
    "to": "2026-11-15",
    "status": 1,
    "limit": 100
  }'
```

```json
{
  "status": 1,
  "code": "ST08",
  "message": "Transactions Found",
  "data": {
    "txcount": "1",
    "transactions": [
      {
        "txstatus": 1,
        "txtype": 1,
        "accountnumber": "1000000000001",
        "payer": "233XXXXXXXXX",
        "payee": "1000000000001",
        "amount": "25.00",
        "value": "24.50",
        "fee": "0.50",
        "networkfee": "0.00",
        "transactionid": "10000001",
        "externalref": "ORDER-1001",
        "thirdpartyref": "3000000001",
        "ts": "2026-11-15 09:30:00",
        "created_at": "2026-11-15T09:30:00Z"
      }
    ],
    "has_more": true,
    "next_cursor": "10000001"
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

- [List Transactions](https://docs.moolre.com/api/accounts/transactions)
- [Pagination](https://docs.moolre.com/guides/pagination)

## Walk every page in code



```nodejs
async function* statement(from, to) {
  let cursor = null;
  do {
    const res = await moolre('/open/account/status', {
      type: 2, accountnumber: process.env.MOOLRE_ACCOUNT, from, to, limit: 100,
      ...(cursor ? { starting_after: cursor } : {}),
    });
    if (res.status !== 1) throw new Error(res.code + ' ' + (res.error?.message ?? res.message));
    for (const row of res.data.transactions) yield row;
    cursor = res.data.has_more ? res.data.next_cursor : null;
  } while (cursor);
}

for await (const row of statement('2026-11-01', '2026-11-15')) console.log(row.created_at, row.externalref, row.amount);
```

```python
def statement(start, end):
    cursor = None
    while True:
        body = {"type": 2, "accountnumber": os.environ["MOOLRE_ACCOUNT"], "from": start, "to": end, "limit": 100}
        if cursor:
            body["starting_after"] = cursor
        res = moolre("/open/account/status", body)
        if res.get("status") != 1:
            raise RuntimeError(f'{res.get("code")} {res.get("message")}')
        yield from res["data"]["transactions"]
        if not res["data"].get("has_more"):
            return
        cursor = res["data"]["next_cursor"]
```

## Step by step: reconcile a day



1. Pull yesterday's statement with the walk above.
2. Match each row to your own record by externalref. Rows that match and agree on amount are done.
3. List the rows you do not have (money you did not expect) and the records you have that are not in the statement (money you expected). Both need a human look.
4. For each of your records still pending, ask Payment Status or Transfer Status by externalref and update it.
5. Compare your computed balance with Account Status. Any difference is a missing row.

- [Reconciliation playbook](https://docs.moolre.com/use-cases/reconciliation)

## Common errors and fixes



| Code | Meaning | Fix |
| --- | --- | --- |
| PG01 | starting_after is not a cursor from a previous response | Send exactly the next_cursor you were given |
| PG02 | Invalid limit | Use a number from 1 to 100 with a cursor |
| PG03 | Invalid from or to | Use YYYY-MM-DD or ISO 8601, after 2023-12-30 |
| ST01, ST02 | Invalid startdate or enddate | Use YYYY-MM-DD HH:MM:SS |
| ST07 | Invalid status | Use 0, 1 or 2 |
| SW06 | Wallet not found | Check accountnumber |

- [ ] You read statements with a cursor and never assume a single page holds everything.
- [ ] You compare by externalref and amount, not by time alone.
- [ ] You run the reconciliation every day and alert on any difference.
