Balances

Read the position before acting

A token balance tells your team what an account holds after settled operations. Total is the whole position. Locked is the amount reserved by active locks. Available is the amount free to spend.

For example, an account holding 100.00 GBP with a confirmed 30.00 GBP lock has 70.00 GBP available. A pending payment is still an outstanding instruction and does not yet change the platform's settled balance.

Treasury and operations teams compare token positions with the bank's own deposit records. Check when the balance was read and investigate an unavailable balance instead of treating it as zero. The precise response fields and a request example follow below.

The three figures

An account's balance is its position in its one asset. The response carries three figures, all in currency units as decimal strings.

Figure	Meaning
`total`	What the account holds, locked or not. Only settled operations are included.
`locked`	What the account's active locks withhold. Freed when a lock is released or cancelled.
`available`	What is free to spend: `total` less `locked`, not below zero. Spends are enforced against this figure.

Within one response, available is exactly total less locked.

asOf records when the figures were read. A balance is only as current as that timestamp.

Show positions and pending instructions separately

Consider an account with 100.00 GBP total and no locks. After a confirmed 30.00 GBP lock, its total is still 100.00, its locked balance is 30.00 and its available balance is 70.00. A pending transfer does not reduce the reported figures; the balance endpoint reads settled contract state.

If that lock is cancelled, total stays 100.00 and available returns to 100.00. If a two-party lock is released to another account, the source's total falls to 70.00 and its locked balance falls to zero once confirmed. The destination receives the 30.00 GBP. These are different outcomes even though both complete the lock.

In your application, show settled total, locked and available amounts alongside a separate list of pending instructions. Use available balance for spending decisions, but account for instructions your own backend has already submitted: a balance read does not reserve funds against concurrent requests. Never subtract a pending instruction from a figure and present the result as a platform-reported balance.

See Transfers, locks and releases for requests and Reconciliation for comparison with your bank's records.

Read a consistent balance

%%{init: {"theme": "neutral"}}%%
flowchart TB
    Client["Your backend"] --> Read["GET account balances"]
    Read --> Contract["Read token contract"]
    Contract --> Snapshot["One snapshot / asOf"]
    Snapshot --> Total["total<br/>1250.00 GBP"]
    Snapshot --> Locked["locked<br/>40.00 GBP"]
    Snapshot --> Available["available<br/>1210.00 GBP"]

The values illustrate the worked example below: available equals total minus locked. A failed contract read is an error, not a zero balance. Accepted operations do not affect this snapshot until confirmed.

Balance response and errors · Read an operation

Where the figures come from

The figures are read from the token contract at the time of the request. All three come from a single read, so they are consistent with one another.

Each balance request is a fresh read of the contract.
A failed read is always reported as an error (500), never as a zero balance.
A balance is reported exactly as the contract holds it. It is not rounded, and it can carry more decimal places than the currency allows.

These are token positions. Your core banking system remains the book of record for the deposits the tokens represent. See Reconcile against your core banking.

Accepted is not settled

An accepted operation moves nothing until it confirms. Submitting a token operation returns 202. That means the request was well formed and the accounts it names are usable. It does not mean value has moved.

After acceptance, the operation is subject to your organisation's transaction policy, may wait for an approver, and is then settled on the ledger. The balance endpoint reflects only settled operations. An operation still in flight does not appear in any of the three figures until it reaches CONFIRMED.

This has three practical consequences:

Do not update a customer-facing balance on a 202. Update it when the operation is CONFIRMED. See Operations and their lifecycle.
Balances are not checked at submission. A burn, transfer or lock for more than the account holds is accepted with 202 and then fails during settlement. The failure is reported on the operation, not on the submission.
A lock reduces available only once it confirms. Until then, the funds it names are still counted as available.

Treat the submission and settlement checks as separate stages. A successful pre-submission balance read does not reserve funds or prevent another operation from using them.

Worked example

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

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

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

The account holds 1,250.00 GBP in tokens. 40.00 GBP is withheld by active locks. 1,210.00 GBP can be spent.

View in API Reference

Get an account's balances · GET

Errors and edge cases

Situation	Response	What to do
No account with that reference, or its asset has no `ACTIVE` contract	`404`	Check the reference and the contract status.
Account is `PENDING` or `FAILED` and has no wallet address	`422`	Wait until the account is `ACTIVE`.
The contract could not be read	`500`	Retry. Never treat this as a zero balance. Use a bounded exponential backoff with jitter, honour `Retry-After` when supplied, and report an unknown balance if reads remain unavailable.
Account is `INACTIVE`	`200`	Deactivation stops new operations. It does not stop reporting of funds already held.

There is no endpoint that lists an account's locks. The locked figure is a total. To release or cancel a lock you need its lockId, which is returned when the lock is submitted and on every read of that operation. Store it. Retain the lock ID and originating transaction ID in your own store; use transaction reads to recover a missing ID.

There is no historical balance endpoint. The balance is always the current position. To reconstruct a position at a past time, use the operation log. Retain confirmed operation and balance evidence in your own reconciliation store when you need historical positions.

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`
Get one token operation	`GET`