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}/balance

Read an account balance

Path parameters

Name
id
Type
string
Description
The account id (acc_…). A malformed id is a 400 invalid_account_id; an unknown one is a 404 unknown_account.

Response

Name
account
Type
string
Description
The account, echoed back exactly as supplied in the path.
Name
balance
Type
integer
Description
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

use axorum_client::AxorumClient;

// A balance is a party-scoped read: the client presents its attestation.
let client = AxorumClient::builder("http://127.0.0.1:8080")
    .attestation(attestation)
    .build()?;

// `balance` is an i128 — the full range, no precision loss.
let balance = client.balance(&account).await?;

println!("{} holds {} minor units", balance.account, balance.balance);

Response

{
  "account": "acc_2n4kqx21g5bty927z2tj955css",
  "balance": 50000
}

Response — unknown (404)

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