Read balances

Who this is for

Engineers who have minted tokens in 3. Issue tokens. By the end of this step you have confirmed that ACC-0001 holds 1,000.00 GBP.

What the three figures mean

GET /api/accounts/{accountRef}/balances returns the account's position in its asset, read from the token contract at the time of the request. The three figures come from a single read and are consistent with one another.

Field	Meaning
`total`	What the account holds, locked or not
`locked`	What the account's active locks withhold. Freed when a lock is released or cancelled
`available`	`total` less `locked`, not below zero. Spends are enforced against this figure
`asOf`	When the figures were read. The balance is only as current as this timestamp

Only settled operations count. An operation that has been accepted but has not reached CONFIRMED does not appear in any of the three figures. If you post a pending entry in your core banking system when you submit an operation, the platform balance will not match it until the operation confirms. See Balances.

All three figures are decimal strings in currency units. They are reported exactly as the contract holds them, without rounding, and can carry more decimal places than the currency allows.

Worked example

GET /api/accounts/ACC-0001/balances HTTP/1.1
Host: api.qfp.quantnetwork.net
Authorization: Bearer eyJraWQiOiJ...
API-Version: 1.0.0

Illustrative example built from the schema.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "accountRef": "ACC-0001",
  "customerRef": "CUST-0001",
  "assetId": "GBP",
  "total": "1000.00",
  "available": "1000.00",
  "locked": "0.00",
  "asOf": "2026-08-06T09:32:05.410Z"
}

An account with an active lock shows the withheld amount in locked:

{
  "accountRef": "ACC-0001",
  "customerRef": "CUST-0001",
  "assetId": "GBP",
  "total": "1250.00",
  "available": "1210.00",
  "locked": "40.00",
  "asOf": "2026-08-13T11:58:04.114Z"
}

View in API Reference

Get an account's balances · GET

Errors and edge cases

Status	When	What to do
`404`	No account has that reference, or the account's asset has no `ACTIVE` contract	Check the reference and the contract
`422`	The account is `PENDING` or `FAILED` and has no wallet address to read	Wait for provisioning to complete. See 2. Create a customer and an account
`500`	The balance could not be read	Retry. A failed read is always an error, never a zero balance, so a `200` with `"0.00"` means the account holds nothing
Account `INACTIVE`	Deactivation stops new operations	Balances are still returned for funds already held

A pending account:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "timestamp": "2026-08-13T11:58:04.114Z",
  "status": 422,
  "error": "Unprocessable Content",
  "message": "Account 'ACC-0002' is PENDING and has no wallet address yet; balances are readable once provisioning completes."
}

Follow a Recipe

Step through the code in JavaScript or Python, inspect illustrative responses, and open the connected endpoint schemas.

Connect and read a balance

API Reference

Open an endpoint for request fields, response examples and the interactive API console.

Operation	Method
Get an account's balances	`GET`

Implementation resources

Balances code recipes.

Use Implement a backend client for request handling, durable idempotency and outcome tracking. The developer integration coverage map links every public operation to its API Reference and contract-derived code recipe. Replace example identifiers with values from your assigned environment.