Accounts

Topology and Refs introduces MasterAccount and ClientAccount as the operating-account layer of the tenant graph. This page covers what is special about that layer: how balances behave and how balance reads are shaped for reconciliation.

Three guarantees worth designing around:

  • Authoritative reads. A balance change is visible exactly once, at one well-defined moment. Internal transfers move both sides together — the two ends cannot drift.
  • Stable ownership. Your account ref keeps owning the same funds regardless of what happens to the underlying infrastructure. There is nothing custody-shaped to model in your integration.
  • Free vs reserved is explicit. Operations in flight reserve funds without hiding them. You always know what you can act on right now.

Balance Reads

Balance reads return a composite owner view, asset by asset, with three numbers:

  • available — what the account can act on right now
  • held — what is reserved against in-flight operations or pending settlements
  • total — the sum of available and held

The split is deliberate. Operations in flight reserve funds without removing them from the visible total, so your code can answer two different questions cleanly: "can I move $X right now?" reads available; "what does this account own at rest and in flight?" reads total.

Balance reads are owner-centric, not transaction-centric — they describe an account's state at a moment, not the activity that produced it. For activity, see Operations and Events and Webhooks.

Overdraft

For a master account with a configured limit, balance items expose overdraft_limit, overdraft_used, and overdraft_headroom. Headroom is the configured limit minus the amount used. These fields are separate from available, held, and total; do not treat the credit limit as funded cash.

Read the master-account balances or client-account balances reference for the response shape. Overdraft fields are nullable, and client accounts do not currently receive a client credit line through these APIs.

Changing a limit requires the platform operator's staff workflow. The partner OpenAPI intentionally excludes those administration endpoints.

How This Appears In The API

Request URL

GET
GET /client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/balances

Response

application/json
{
  "items": [
    {
      "asset": "USDC",
      "available": "950.00",
      "held": "50.00",
      "overdraft_headroom": null,
      "overdraft_limit": null,
      "overdraft_used": null,
      "owner_ref": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "owner_subtype": "client_account",
      "total": "1000.00",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ]
}