Holdings

A holding is a position inside an account at a point in time. On Aleta, holdings are derived: they're reconstructed from the underlying transaction ledger every time new activity is ingested, rather than stored as a static snapshot. Ask the platform "what did this reporting entity hold on 31 December 2025" and get a deterministic, fully-audited answer — the same input ledger always produces the same output positions.

Reconstruction from transactions

Every holding is the result of replaying its underlying accounts' transactions up to a given cut-off date. Transaction types carry the kind of movement (buy, sell, deposit, withdrawal, dividend, fee, capital call, distribution) and their quantity and price impact. Aleta folds them into positions using a configurable accounting method:

  • Name
    FIFO
    Type
    default
    Description

    First-in-first-out. The oldest lots close first when a sale hits. Most jurisdictions default to FIFO for realised-gain calculations.

  • Name
    AVERAGE
    Description

    Weighted average cost. All lots of the same instrument collapse into one with a rolling average cost basis. Common in mutual-fund accounting and some European jurisdictions.

  • Name
    SPECIFIC_ID
    Description

    Specific lot identification. Each sale references the exact lot it closes. Maximum control over realised gains/losses, but requires explicit lot tagging on every sell transaction.

The method is set per client and can be overridden per account where the custodian enforces its own policy.

Two flavours of query

The API returns holdings in two shapes, served by two versioned endpoints:

  • Holding (v2) — aggregate shape. Quantity + market value + cost basis + unrealised P/L. No per-lot detail. Right for dashboards and rollups.
  • Instrument Holding (v3) — the same aggregate plus every open lot expanded underneath. Acquisition date, per-lot quantity, per-lot cost, realised-gain classification. Right for tax reporting, lot analytics, and statement reconciliation.

Pick one per integration and stay with it. Mixing them gives the same numbers in slightly different shapes and invites subtle reconciliation bugs.

Market valuation

Quantity × price = market value. Prices come from three sources, tried in order:

  1. Custodian-reported prices embedded in transactions or position snapshots. Used first when available — they match what the account holder sees on their statement.
  2. Aleta's reference data for listed instruments — end-of-day closes from the primary exchange, converted to the reporting entity's reference currency via the day's FX rate.
  3. Manual valuations for private assets. Uploaded valuation reports become the authoritative price until a newer one lands.

Intraday moves aren't tracked. Market values snap to end-of-day for listed instruments and to valuation-report dates for private assets. Family-office reporting optimises for correctness and reconciliation, not latency — this isn't a trading dashboard.

Historical holdings

Because reconstruction is deterministic, any historical date is queryable. Supply as_of and the response is byte-identical on every call — safe to cache downstream.

Historical holdings

curl -G https://api.aleta.io/v2/holdings/reporting-entities/{id} \
  -H "Authorization: Bearer {token}" \
  -d as_of=2025-12-31T23:59:59Z

This powers year-end statements, performance attribution, and audit-trail reconciliation.

Reporting-entity scoped, always

The query surface is always per reporting entity, not per account or legal entity. If you want "what does the family trust hold," you don't ask against the trust's legal-entity ID — you ask against the reporting entity that the trust's accounts roll up into. This keeps analytical views stable even when the legal structure reshuffles underneath.

What's next