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#

Overdraft is an authorized credit line attached to an account that extends available beyond the funded balance up to the limit. The balance view will surface the limit, the amount used, and the remaining headroom alongside available and held, so an integration can reason about spendable funds in one read.

Two flavors will be supported:

• Master overdraft — a credit line the platform extends to the enterprise on a master account. This is how the platform offers treasury credit at the tenant level.
• Client overdraft — a credit line the enterprise extends to a client out of its own liquidity, attached to a client account. This lets the enterprise pass through credit to its downstream clients on its own terms.

Both flavors share the same balance-read shape and the same headroom mechanics; the difference is who provides the credit and to whom.

How This Appears In The API#

GET /client-accounts?client=clients/44444444-4444-4444-8444-444444444444

{
  "owner_ref": "client-accounts/55555555-5555-4555-8555-555555555555",
  "balances": [
    {
      "asset": "USD",
      "available": "1250.00",
      "held": "50.00",
      "total": "1300.00"
    }
  ]
}