Accounts & Portfolios

The accounts module provides a unified interface for managing a customer's total financial portfolio, encompassing traditional fiat bank accounts and cryptocurrency assets.

Purpose and use

Accounts are the operational view of where customer money and crypto assets can be held, spent, frozen, reported, or reconciled. They sit between customer onboarding, ledger posting, transfer initiation, card or payment holds, and portfolio reporting.

Who uses this. Operations staff open and review accounts, support teams answer balance questions, finance teams reconcile account balances to subledgers, and product teams decide which account types are available to customers.

How it works. Each fiat account is backed by a customer subledger in the ledger module. Posted balance shows settled value-dated money; available balance reflects holds, pending movements, overdraft policy, and any money reserved for operations. Crypto balances are shown through the same portfolio view so users can scan all customer holdings together.

What users do. Users create an account during onboarding or product activation, review balances by currency, group accounts for portfolio totals, search by customer, IBAN, currency, or subledger code, and deactivate accounts that should no longer be used for new activity.

Outcomes and side effects. Account opening creates or links the relevant ledger container, may issue an IBAN or wallet address, and makes the account eligible for transfers, statements, fees, and audit review. Deactivation removes the account from active balance totals without deleting historical postings.

Related manuals: Ledgers & Balance Management (includes customer subledgers and purpose accounts), Transfers, Customers.

Object Relationships

CoreBanq uses a "Unified Account" model where fiat and crypto entities are normalized into a consistent structure, each backed by the CoreBanq Ledger system.

Key Components

• Account: The high-level entity representing a customer's wallet or IBAN account. It holds metadata (description, status, tags).
• Subledger: The actual accounting container where balances are tracked and entries are posted. Every Account has exactly one Subledger.
• Customer: The legal entity (Individual or Business) that owns the accounts. When account responses hydrate the nested customer object, it includes nullable counterparty_id for the customer's mirror-linked counterparty.

---

Balance Management

Following the V2/V3 Unified API standards, accounts now expose detailed balance states derived directly from their underlying subledgers.

Available, Posted, and Pending Balance

Every balance in an account or portfolio response is expressed as a self-describing amount: a whole-number value in the currency's smallest unit (cents, satoshi, etc.), paired with the currency code and the number of decimal places it represents. This removes any ambiguity about rounding or decimal placement when displaying or reconciling amounts across fiat and crypto. When an account is backed by a Subledger, its posted, available, and pending balances are included the same way.

---

API Reference

Unified Accounts (V2 / V3)

The Unified API is the recommended way to interact with portfolios. It supports complex filtering and provides a consistent schema regardless of the asset type.

GET /v3/accounts

Retrieves all accounts (Fiat + Crypto). Use search.is_crypto=true/false to filter.

What a Unified Account Includes

Each record combines the account's identity (owning customer, currency, current status) with its balance and its business type (fiat or crypto). Fiat accounts additionally carry their IBAN and bank details; crypto accounts carry their network and wallet information. When the account has a Subledger, the record also includes the subledger's posted, available, and pending balances, each expressed as the same self-describing amount used everywhere else in the module.

Portfolio Balances

GET /v2/accounts/balance

Calculates total portfolio value in a target currency (e.g., EUR or USD).

Balance endpoints use active accounts only. Accounts deactivated by delete operations are excluded from portfolio totals and currency-specific totals.

Parameters:

• customer_id: The customer whose portfolio is being valued (Required).
• currency: The target currency for conversion (Required).
• details: Set to true to receive the full breakdown of fiat accounts and crypto assets.

Grouped Portfolio Totals

GET /v3/accounts/balance

Returns the same portfolio total, but split into Total, Fiat, and Crypto groups, each broken down into Posted, Available, and Pending balances. Use this when a dashboard or reconciliation view needs to separate fiat exposure from crypto exposure at a glance, rather than working from the single blended total returned by the grouped-by-currency endpoint above.

Parameters:

• customer_id: The customer whose portfolio is being valued (Required).
• currency: The target currency for conversion (Required).

---

Usage Guidelines

Creating Accounts

When creating a fiat account, the system automatically:

1. Creates the Account metadata.
2. Resolves the correct Control Ledger from the customer type + account currency (see below).
3. Provisions a unique Subledger under that control ledger (e.g., Customer Deposits (Available)).
4. Generates a virtual IBAN if configured for the target currency.

How the control ledger is chosen

The target control ledger is not fixed per account type in code — it is resolved from the pair (customer type, account currency). Each leaf control ledger declares which customer types it serves through its own Customer Types list (Corebanq Configurator → Ledger Browser → open the control ledger → "Customer Types"), and a given type + currency pair maps to exactly one control ledger. See Routing by customer type in the Ledgers manual for how to set this.

If no control ledger claims the account's customer type + currency, account creation fails and no account or subledger is created — assign that type + currency on the correct leaf control ledger's Customer Types list to resolve it (see the Error Codes table below).

Search and Filtering

The Unified API supports advanced query syntax:

• search.balance.gte=1000: Minimum balance filter.
• search.subledger_code=2211-*: Search by accounting code (2211 is the Type A / CHF customer-deposit control leaf in the standard chart).
• stack=currency: Group results by currency for a summarized dashboard view.

Deleting Accounts

DELETE /v1/accounts/{id} deactivates the account by setting active=false; it does not physically remove the accounts.accounts row. Public v1 reads by ID or IBAN, customer account balance sources, and currency-specific balance sources return active accounts only, so a deactivated account is treated as not found or excluded from totals.

---

Error Codes