var moneta = new MonetaClient(); // one per application
var me = moneta.with(new AccessToken(myToken)); // cheap, keep it or make one per request
var november = me.transactions().between(LocalDate.of(2026, 11, 1), LocalDate.of(2026, 11, 30));
november.list(); // everything
november.incoming().booked().list(); // money that came in, booked
november.transfers().outgoing().list(); // transfers that went out
november.cards().list(); // paid by the account's card
me.balance(); // booked and available, with the instant MONETA computed it
me.tokenExpiry(); // when the token stops working: ask the merchant for a new one before it doesKotlin
val moneta = MonetaClient() // one per application
val me = moneta.with(AccessToken(myToken)) // cheap, keep it or make one per request
val november = me.transactions().between(LocalDate.of(2026, 11, 1), LocalDate.of(2026, 11, 30))
november.list() // everything
november.incoming().booked().list() // money that came in, booked
november.transfers().outgoing().list() // transfers that went out
november.cards().list() // paid by the account's card
me.balance() // booked and available, with the instant MONETA computed it
me.tokenExpiry() // when the token stops working: ask the merchant for a new one before it doesWith the Spring Boot starter, moneta.token gives you the AccessToken bean.
| Step | Keeps |
|---|---|
between(from, to) |
days, both inclusive; required |
transfers(), cards(), method(…) |
how the money moved |
incoming(), outgoing() |
money in, money out |
booked(), pending() |
booked, pending |
- Steps are optional and combine; a later one of the same kind wins.
- A query is immutable, so one base query can branch, as
novemberabove. - Nothing is read until
list(). MONETA filters by date only, so a shorter range is what makes it cheaper.
transactions() and balance() read the only account the token opens, and throw IllegalStateException when
there are more. Name the account then. To read the one you stored, find it by its IBAN, which is what the
merchant gave you; MONETA's own account id is known to nobody outside it:
var account = me.accountByIban(storedIban); // only letters and digits count, in either case
if (account == null) {
return refuse(); // the token no longer sees it: revoked, or another token pasted
}
me.transactions(account.id()).between(from, to).list();
for (var other : me.accounts()) { // or every account the token opens
me.transactions(other.id()).between(from, to).cards().list();
}Kotlin
val account = me.accountByIban(storedIban) ?: return refuse()
me.transactions(account.id).between(from, to).list()
for (other in me.accounts()) {
me.transactions(other.id).between(from, to).cards().list()
}accountByIban reads the accounts on every call, so an account revoked for the token shows on the next one. A
blank IBAN, or one failing its check digits, is an IllegalArgumentException: a typo, not a revoked account.
Two accounts with one IBAN, one per currency, are an IllegalStateException naming both ids.
Several account holders, each with their own token, share one client:
holders.forEach(holder -> moneta.with(holder.token()).transactions().between(from, to).list());Kotlin
holders.forEach { moneta.with(it.token).transactions().between(from, to).list() }entryReferencechanges when a movement is booked: deduplicate by it and a payment counts twice. Act on booked movements, or match by symbols, amount and counterparty account, asexamples/cafedoes.- Dates only, no time of day. The payment's date is
enteredDate()while pending,valueDate()once booked. Need "paid a minute ago"? Store when you first saw it. amount()is signed: negative is money out, so amounts add up.Moneyis aBigDecimalwith a currency.method()isTRANSFER,CARDorOTHER, and gains constants as they are seen live (#66): keep adefaultin aswitch.symbols()readsVS,KSandSS, leading zeros kept.reversed()is a reversal, not a payment.raw()has the whole movement as JSON. It,message()and the counterparty stay out oftoString(), not out of a JSON serialiser: map to your own type before returning one from a controller.- A read is all or nothing, every page or a failure. Read long ranges month by month.
- Records may gain components before 1.0: use accessors, not record patterns.
How MONETA API behaves has the details behind each.
A sealed MonetaException, so a switch over it is exhaustive:
| Subtype | When | Do |
|---|---|---|
InvalidToken |
401, 403 | get a new token |
RateLimited |
429 | wait retryAfter() |
HttpError |
any other status | body() has MONETA's answer |
NoAnswer |
timeout, refused connection | retry |
InvalidResponse |
an unexpected body | report it |
An interrupted thread throws CancellationException instead, interrupt flag kept.
MonetaClient.builder(): baseUri(…), requestTimeout(…), partner(…) (headers MONETA does not ask for yet),
configureHttpClient(…) for a proxy or mTLS, decorateHttpClient(…) for tracing or metrics
(examples). close() releases the HTTP client it made.