Wallet top-up history

# Instructions — Wallet top-up history

## ⚠️ Date format: full ISO 8601 + timezone recommended

The MCP documentation states that YYYY-MM-DD alone is not accepted and that a full datetime is required.
The input schema enforces the `date-time` format and the server validates formats: `from="2026-06-01"` is rejected at validation.

**Despite this tolerant behavior, always use full ISO 8601 with timezone:**
```
from: "2026-06-01T00:00:00.000Z"
to:   "2026-06-30T23:59:59.999Z"
```

Reason: coercion from YYYY-MM-DD to midnight can produce unexpected results depending on the server's timezone. Using `T00:00:00.000Z` (UTC) is unambiguous.

## ⚠️ Not for exact bank reconciliation

`createdAt` is the **bank provider's booking date** (the value date on GBP accounts).
The `from`/`to` filters do not reliably filter on `createdAt`: on non-GBP `sfs` wallets they filter on when the load record was created, on GBP wallets the bank provider decides which date is used, and on legacy wallets (`bankName: other`) card and SEPA top-ups ignore `from`/`to` entirely.
→ Widen `from`/`to` by a few days, then apply the cutoff yourself on `createdAt`.
→ For exact reconciliation, verify against the bank statement.

## ⚠️ 24h cache (86400 seconds)

The cache applies per identical query (same `page`, `pageSize`, `cursor`, `from`, `to`): a top-up received after an earlier identical call may not appear for up to 24h.
→ For the current balance, use `get_wallet_summary` — it is served from a short cache, so recent but not real-time.

## Step 1 — Call with period and recommended parameters

```json
{
  "companyId": "...",
  "from": "YYYY-MM-DDT00:00:00.000Z",
  "to": "YYYY-MM-DDT23:59:59.999Z",
  "pageSize": 100
}
```

## Step 2 — Interpreting the fields

For each load:
- `amount`: `{ amount, currency, precision }` → amount = `amount / 10^precision` EUR
- `type`: `"wireTransfer"` (only type observed on this account)
- `bankName`: `sfs` | `adyen` | `other`
  - `sfs` = Spendesk Financial Services (main account)
  - `adyen` = Adyen (accounts for certain subsidiaries)
  - `other` = any other banking provider (legacy wallets; card and SEPA top-ups there ignore `from`/`to`)
- `createdAt`: the banking provider's booking date (the value date on GBP accounts) — not the date the record was created in Spendesk

## Step 3 — Pagination

Check `meta.pagination.hasNextPage` — if `true`, paginate with `page=2, 3, ...` and the same filters.

**GBP wallets** (`bankName: sfs` with GBP amounts): `page` is ignored. When more loads exist, the response carries `meta.pagination.cursor`: pass it as `cursor` with the same `from` and `to`, until `hasNextPage` is `false`. `fetchAll` follows the cursor itself and cannot be combined with `cursor`; when truncated it returns `meta.pagination.resumeCursor` in place of `resumePage`.

## Live example (real data, June 2026)

16 loads in June 2026, including:
- 2026-06-23: EUR 500,000.00 (sfs transfer)
- 2026-06-10: EUR 600,000.00 (sfs transfer)
- Total for the month: ~EUR 1,105,721 (including two large test loads)

## Example prompt

- "Show wallet top-ups from last month" → from/to = last month + ISO 8601
- "How much did we load into the wallet in 2026?" → from=2026-01-01T00:00:00.000Z, to=today + pagination
- "What is the current wallet balance?" → use `get_wallet_summary`, not `get_wallet_loads`