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.

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 vs. Posted Balance

Account responses now include a subledger fragment containing precise minor-unit (cents/satoshi) values and their formatted string equivalents.

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.

Response Sample (V3)

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "customer_id": "987fcdeb-51d2-11ec-9d64-0242ac120002",
      "currency": "EUR",
      "balance": 1250.75,
      "subledger": {
        "id": "550e8400-e29b-11d4-a716-446655440000",
        "code": "2201-abc12345",
        "balance_posted": 125075,
        "balance_available": 100000,
        "balance_posted_fmt": "1250.75",
        "balance_available_fmt": "1000.00"
      },
      "is_crypto": false,
      "status": "active",
      "iban": "CH93 0076 2011 6238 5295 7",
      "created_at": "2023-01-15T10:30:00Z"
    }
  ]
}

Portfolio Balances

GET /v2/accounts/balance

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

Parameters:

• currency: The target currency for conversion (Required).
• details: Set to true to receive the full breakdown of fiat accounts and crypto assets.

Usage Guidelines

Creating Accounts

When creating a fiat account via POST /v1/accounts, the system automatically:

1. Creates the Account metadata.
2. Provisions a unique Subledger in the correct Control Ledger category (e.g., Public Customer Deposits).
3. Generates a virtual IBAN if configured for the target currency.

Search and Filtering

The Unified API supports advanced query syntax:

• search.balance.gte=1000: Minimum balance filter.
• search.subledger_code=2201-*: Search by accounting code.
• stack=currency: Group results by currency for a summarized dashboard view.

Error Codes