Accounts

An account holds a balance inside a program. It might represent a customer's wallet, your treasury, or an account you use to collect fees. Every account uses its program's currency.

You never set a balance directly. A balance is computed from the account's postings in the journal, which means it can always be recalculated from the underlying record and can never quietly disagree with it. To change a balance, you move money with a transaction, and the balance follows.

The four balances

An account reports four balances, all in minor units. Keeping them separate lets you answer "how much is really spendable right now" precisely.

Balance	What it represents
posted	Money that has settled.
pending	Money reserved by transactions that have not settled yet.
held	Money reserved by holds.
available	What the account can actually spend now: available = posted - pending - held.

The account object

Field	Type	Description
entity_id	string	Unique identifier.
entity_name	string	A name you choose.
entity_type	string	Your own label for the account, such as customer or fee.
currency_code	string	Taken from the program.
status	string	active or inactive.
balances	object	The four balances above.

Getting money in and out

An account gains money by receiving it from another account in a transaction, or from outside the program entirely. Bringing money in from outside is called funding (a deposit), and sending it back out is defunding (a withdrawal). Both are recorded as balanced transactions against the program's external account, so the ledger stays balanced whenever money enters or leaves.

Operations

Method and path	What it does
POST /entity	Open an account.
GET /entity	Retrieve one account, or list every account in the program.
PUT /entity	Update an account, such as activating or deactivating it.
POST /entity/fund	Bring money into an account.
POST /entity/defund	Send money out of an account.
GET /entity/postings	The account's postings, straight from the journal.
GET /balances/history	How an account's balance changed over time.
GET /flow	The accounts money has moved to and from, for tracing.

The API reference documents the parameters and responses for each of these.