Skip to main content
GET
Retrieve a Balance

Headers

Content-Type
string

The type of media of the resource. Recommended value is application/json.

X-Request-Id
string<uuid>

A unique identifier used to trace and track each request.

Authorization
string

Bearer JWT token for authentication. Required when PLUGIN_AUTH_ENABLED=true (enforced in multi-tenant deployments). Optional in default OSS single-tenant mode. Format: Bearer <token>

Path Parameters

organization_id
string<uuid>
required

The unique identifier of the Organization associated with the Ledger.

ledger_id
string<uuid>
required

The unique identifier of the associated Ledger.

balance_id
string<uuid>
required

The unique identifier of the balance that you want to retrieve.

Response

Indicates that the request was successful and the response contains the expected data.

id
string

The unique identifier of the Balance.

organizationId
string<uuid>

The unique identifier of the Organization.

ledgerId
string<uuid>

The unique identifier of the Ledger.

accountId
string<uuid>

The unique identifier of the Account.

alias
string

The alias for the account used in the operation.

key
string

The unique identifier for the balance in the context of the account.

assetCode
string

The name of the asset used in the operation.

available
string

Previous available balance.

onHold
string

Amount on hold/reserved.

version
integer

Balance version, which is updated with each transaction.

accountType
string

The type of account.

allowSending
boolean

If true, indicates that the balance can be used to send transactions.

allowReceiving
boolean

If true, indicates that the balance can be used to receive transactions.

direction
enum<string>

The accounting direction of the balance. credit balances grow on credit and shrink on debit; debit balances grow on debit and shrink on credit. Set at creation and immutable.

Available options:
credit,
debit
overdraftUsed
string

The amount of overdraft currently consumed by this balance, as a decimal string. Always non-negative; "0" when the balance has no overdraft active.

settings
object

Optional per-balance configuration (overdraft, scope). null for legacy balances without custom settings.

position
object
read-only

Computed view of the balance state at response time. Always present; never persisted. Re-derived from available, onHold, overdraftUsed, and settings on every read.

createdAt
string<date-time>

Timestamp of creation (UTC).

updatedAt
string<date-time>

Timestamp of last update (UTC).

deletedAt
string<date-time> | null

Timestamp of soft deletion, if applicable (UTC).

metadata
object

An object containing key-value pairs to add as metadata, where the field name is the key and the field value is the value. For example, to add a Cost Center, use 'costCenter': 'BR_11101997'.

Constraints: keys must be at most 100 characters; string values at most 2000 characters. Nested objects are not allowed (values must be string, number, or boolean), the structure may not exceed a maximum depth of 10, and a maximum of 100 keys is permitted.