# Accounts

> Master and client accounts as the operating-account layer: balance reads (available, held, total) and overdraft semantics.

Source: https://business-api-docs.youhodler.com/docs/concepts/accounts

[Topology and Refs](/docs/concepts/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.

> **Practical rule:** Read balances and post operations against an account ref. Never try to read a balance off an enterprise or a client directly — balances do not live at the relationship layer.

## 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](/docs/concepts/operations)
and [Events and Webhooks](/docs/concepts/events-and-webhooks).

## Overdraft

> **Coming soon:** Overdraft surfaces are being prepared for the public API.

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

**Request URL — GET**
```http
GET /client-accounts?client=clients/44444444-4444-4444-8444-444444444444
```
**Response — application/json**
```json
{
  "owner_ref": "client-accounts/55555555-5555-4555-8555-555555555555",
  "balances": [
    {
      "asset": "USD",
      "available": "1250.00",
      "held": "50.00",
      "total": "1300.00"
    }
  ]
}
```