OpenChainGraph · Explainer

Multicurrency JE Balance Check

How a journal-entry batch is tested for balance on a basis the caller declares , every currency on its own, or one declared functional currency , entirely in integer minor units, with a tolerance that is declared, never inferred, and a named refusal for every malformed input. Every number on this page is hand-computed and comes from the node's golden fixtures.

Presenter mode shows one step per screen. Arrow keys move, A toggles autoplay, Esc exits.
1
Step 1

The caller declares the basis for every run

The same entry can balance on one basis and fail on another, so the node refuses to guess. The balance_basis must be per_currency or functional, and an undeclared basis stops the run with BASIS_NOT_DECLARED.

USD +10800debit, minor units EUR −10000credit, minor units per_currency: imbalancedUSD +10800, EUR −10000 both open functional: balancedEUR line declared at USD 10800 identical amounts,opposite verdicts

A currency-conversion entry (dollars out, euros in) never sums to zero in either currency on its own, so a per-currency rule would flag every legitimate FX entry as broken. ERP and IFRS practice records foreign-currency items in the functional currency at a rate. That is why the basis is the caller's decision: the node's golden fixtures carry this exact pair , identical amounts, only the declared basis differing , one verdict imbalanced, the other balanced. The functional basis requires functional_currency (a USD, an EUR, whatever the ledger declares); omitting it is also BASIS_NOT_DECLARED.

Who asks at this stepno agent yet
An auditor asks: does this journal extract balance before I run my JE tests? First question back: balance on which basis?
2
Step 2

The integer rule for amounts

Every amount is a signed JSON integer in minor units , cents for USD at exponent 2, nothing for JPY at exponent 0, milli-units for KWD at exponent 3, all with debit positive. One sign convention, never two.

amount_minor: 10.5not an integer → AMOUNT_NOT_INTEGER amount_minor: 2ⁿ53beyond the safe bound → AMOUNT_UNSAFE_INTEGER refused, whole entry refused, whole entry 2ⁿ53−1 runsboundary fixture

No float ever touches an amount path: the node checks the safe-integer bound explicitly and refuses amounts beyond it rather than truncating them. The golden fixtures include the boundary value accepted and the value one past the bound refused at the compute level; the browser/worker transport refuses it one step earlier, at I-JSON canonicalisation, which the fixture notes state. Currency exponents are declared by the caller and only membership is checked. The node cites ISO 4217 minor units as published by SIX, the maintenance agency, as the source to consult, but it performs no run-time fetch and does not claim the declared exponents are authoritative.

Who asks at this stepno agent yet
A developer building a journal import asks: what happens if my feed sends 10.5 cents, or a value past JavaScript's safe range? Both land as named refusals, never as silent coercion.
3
Step 3

Declared tolerances are echoed back in the output

Default is exact zero. A caller may declare an integer tolerance per currency, and the node echoes the tolerance it actually used next to every verdict so the output never depends on an unspoken allowance.

residual 1, declared tolerance 11 ≤ 1 → within_tolerance residual 2, same tolerance 12 > 1 → imbalanced within_tolerance imbalanced tolerance_usedechoed in the output

This is deliberately the opposite of the inferred-tolerance pattern some text-ledger tools use: integer minor units make the tolerance a plain declared number, so nothing is inferred from formatting or precision. A negative tolerance is refused outright (NEGATIVE_TOLERANCE) before any entry is evaluated. A zero-amount line never blocks an entry; it carries a ZERO_AMOUNT_LINE warning, and an entry whose lines are all zero balances at exactly zero with the warnings attached.

Who asks at this stepno agent yet
A controller asks: our ERP allows a two-cent rounding difference on payment entries , declare tolerance_minor {"USD": 2} and the verdicts reflect exactly that, stated back in the output.
4
Step 4

Every malformed input lands a named refusal

Nothing is silently dropped or coerced. Each refusal is a named code, reachable by a documented input, and each one has a golden fixture proving it fires.

BASIS_NOT_DECLARED ENTRY_TOO_FEW_LINES AMOUNT_NOT_INTEGER AMOUNT_UNSAFE_INTEGER UNKNOWN_CURRENCY MISSING_FUNCTIONAL_AMOUNT NEGATIVE_TOLERANCE DUPLICATE_ENTRY_ID / LINE_ID ENTRY_CAP_EXCEEDED

The cap is a named constant (500 entries) and the run refuses above it rather than processing an unbounded batch. Batch-level problems (an undeclared basis, a negative tolerance, a cap breach) stop the whole run with execution_state: did_not_run and a reason; entry-level problems refuse just that entry and the others still get verdicts, so one malformed row cannot erase the evidence for the clean ones.

Who asks at this stepno agent yet
An agent drafting a multi-line entry asks the node to pre-check its own work before posting; a refused entry comes back with the exact reason, not a shrug.
5
Step 5

What this node does not claim

A balanced entry is not a correct entry. The node reports arithmetic and says so everywhere it speaks.

Not claimed: an entry is correct, approved or compliant , only that its arithmetic closes, or by how much it does not Not claimed: the functional amounts or rates are right , functional_minor is caller-declared, taken as given (no FX recompute in v1) Not claimed: the declared currency exponents are authoritative , declared by the caller, membership-checked only

Sibling relationship, stated plainly: art-653 is the plain-text, single-currency, two-decimal journal-entry verifier (a parser with a Merkle evidence envelope). This node is the structured, multi-currency, declared-basis check. It shares no code with art-653 and does not extend or alter it , a sealed kernel stays sealed.

Who asks at this stepno agent yet
Any reader asks: does balanced mean booked right? No. It means the arithmetic closes on the basis the caller declared, and the residuals say by how much anything does not.
6
Step 6

Worked example, run and exportable

The golden example below is the fixture pos-eur-conversion-functional-balanced: EUR 100.00 declared at USD 108.00 against a USD 108.00 credit, on the functional basis , balanced, residual USD 0.

Press "Run the worked example" to render the fixture's output payload.

The export carries the declared basis and tolerances from the rendered run. The button stays disabled until a run exists , an export of nothing would be a fabricated mandate.

Who asks at this stepagent-ready
Run the AINumbers MCP tool `check_je_multicurrency_balance` with the worked example from this panel and verify the returned execution hash before trusting the verdict.
🔒 All inputs are processed locally in your browser. No data is transmitted. Do not enter real personal data , use synthetic or anonymised inputs only.

Ask your agent

Copy this paragraph into Claude, OpenClaw, or any MCP-aware agent to run this exact tool, with this sample, and verify the artifact.

Run the AINumbers MCP tool `check_je_multicurrency_balance`. Task: Check whether structured multi-currency journal entries balance on a caller-declared basis (functional or per_currency) in integer minor units, with a declared per-currency tolerance.
Call it with arguments: {"policy_parameters":{"policy_version":"1.0.0","balance_basis":"per_currency","currency_exponents":{"USD":2,"EUR":2,"JPY":0,"KWD":3},"entries":[{"entry_id":"E1","lines":[{"line_id":"L1","account":"cash","currency":"USD","amount_minor":10000},{"line_id":"L2","account":"revenue","currency":"USD","amount_minor":-10000}]}]}}
Verify before trusting: call `verify_execution_hash` on mcp.ainumbers.co (https://mcp.ainumbers.co/mcp) with the parameter `claimed_hash` set to the returned `execution_hash`, passing the full artifact the run returned (the object containing `policy_parameters` + `output_payload` + `execution_hash`; equivalently `policy_parameters` + `output_payload` with `claimed_hash`), not the bare hash string.
Return the ledger link https://ledger.ainumbers.co/ so a human can re-verify without contacting us.
PII rule: All inputs are processed locally in your browser. No data is transmitted. Do not enter real personal data — use synthetic or anonymised inputs only.
Over MCP, the run happens on the AINumbers worker. No AINumbers server stores your inputs.
Open the tool with the sample prefilled: https://ainumbers.co/chaingraph/art-791-check-je-multicurrency-balance.html#p=v1.H4sIAAAAAAAA_wEsAdP-eyJwb2xpY3lfdmVyc2lvbiI6IjEuMC4wIiwiYmFsYW5jZV9iYXNpcyI6InBlcl9jdXJyZW5jeSIsImN1cnJlbmN5X2V4cG9uZW50cyI6eyJVU0QiOjIsIkVVUiI6MiwiSlBZIjowLCJLV0QiOjN9LCJlbnRyaWVzIjpbeyJlbnRyeV9pZCI6IkUxIiwibGluZXMiOlt7ImxpbmVfaWQiOiJMMSIsImFjY291bnQiOiJjYXNoIiwiY3VycmVuY3kiOiJVU0QiLCJhbW91bnRfbWlub3IiOjEwMDAwfSx7ImxpbmVfaWQiOiJMMiIsImFjY291bnQiOiJyZXZlbnVlIiwiY3VycmVuY3kiOiJVU0QiLCJhbW91bnRfbWlub3IiOi0xMDAwMH1dfV19oN6OrywBAAA