Balances by account or identity, each kind labelled, from one view.

GET

/v1/balances

const url = 'https://example.com/v1/balances';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/v1/balances \
  --header 'Authorization: Bearer <token>'

Reads the balances of one subject, from one view. Name exactly one subject: account for one account, or identity for every account of that identity the caller reaches. Naming both, or neither, is refused as ERR-QueryUnbounded. asset narrows the answer to one asset; without it, a row comes back for every asset the account has held. A parameter this route does not know, or an account, identity or asset that is not a valid identifier or symbol, is refused as ERR-MalformedCommand (amendment 0032, REQ-ER-3), never ignored.

Authorizations

bearer

Parameters

Query Parameters

account

The subject: one account, as a did:aledgent:acct: identifier.

string | null

asset

One asset, by its symbol; every asset held if absent.

string | null

identity

The subject: one identity, as a did:aledgent:id: identifier. Every account of it the caller reaches is read.

string | null

Responses

200

The answer, from one consistent view (REQ-QR-2).

application/json

balances (SPEC §8.2).

object

rows

required

The rows.

Array<object>

One balance row: each balance kind labelled, and their total (REQ-BA-2).

object

account

required

The account.

string

asset

required

The asset.

string

available

required

Available, minor units.

string

encumbered

required

Encumbered, minor units (zero in V0).

string

reserved

required

Reserved, minor units.

string

total

required

Their sum.

string

view

required

The view it was read at: the posting sequence number (REQ-QR-2).

integer format: uint64

Example^generated

{
  "rows": [
    {
      "account": "example",
      "asset": "example",
      "available": "example",
      "encumbered": "example",
      "reserved": "example",
      "total": "example"
    }
  ],
  "view": 1
}

4XX

Refused, with the named condition. The status is the alternative’s x-http-status.

application/json

One of:

ERR-NotAuthorised

object

description

required

Allowed value: The initiating principal holds no authority that covers this operation, account, asset or bound

error

required

Allowed value: ERR-NotAuthorised

Example

{
  "description": "The initiating principal holds no authority that covers this operation, account, asset or bound",
  "error": "ERR-NotAuthorised"
}

5XX

Refused, with the named condition. The status is the alternative’s x-http-status.

application/json

One of:

ERR-NotAuthorised

object

description

required

Allowed value: The initiating principal holds no authority that covers this operation, account, asset or bound

error

required

Allowed value: ERR-NotAuthorised

Example

{
  "description": "The initiating principal holds no authority that covers this operation, account, asset or bound",
  "error": "ERR-NotAuthorised"
}

Headers

Retry-After

integer

On ERR-DecisionUnavailable (503): seconds to wait before retrying with the same client key (DEC-27 (g)).

Balances by account or identity, each kind labelled, from one view.

Authorizations

Parameters

Query Parameters

Responses

200

Examplegenerated

4XX

Example

5XX

Example

Headers

Example^generated