Balances

An account's net balance, in integer minor units. One number, and one decoding rule that is not optional.

GET/api/v1/accounts/{id}/balanceRead an account balance

Path parameters

idstring: The account id (acc_…). A malformed id is a 400 invalid_account_id; an unknown one is a 404 unknown_account.

Response

accountstring: The account, echoed back exactly as supplied in the path.
balanceinteger: The net balance in minor units — cents, for USD.

Decode it as a big integer

balance is a 128-bit integer, emitted as a bare JSON number. Its range exceeds what an IEEE-754 double represents exactly. A parser that decodes numbers as doubles — JavaScript's JSON.parse, notably — will silently lose precision on large values, and a silently wrong balance is worse than a loud failure.

No standard JSON numeric format expresses this range, which is why the contract spells it out instead of encoding it. The SDKs decode it as a big integer for you: i128 in Rust, bigint in TypeScript, int in Python.

Read a balance

GET/api/v1/accounts/{id}/balance

1use axorum_client::AxorumClient;
2
3// A balance is a party-scoped read: the client presents its attestation.
4let client = AxorumClient::builder("http://127.0.0.1:8080")
5    .attestation(attestation)
6    .build()?;
7
8// `balance` is an i128 — the full range, no precision loss.
9let balance = client.balance(&account).await?;
10
11println!("{} holds {} minor units", balance.account, balance.balance);

1{
2  "account": "acc_2n4kqx21g5bty927z2tj955css",
3  "balance": 50000
4}

1{
2  "error": "unknown_account",
3  "message": "No account with that id has been opened."
4}