View as Markdown

Holdings

Holdings are the positions a reporting entity holds at a point in time — reconstructed from the transaction ledger, not cached. Each holding carries both its aggregate shape (units, market value, accrued interest) and a reference to the instrument it represents, so integrators can join on classification or time-series data from the instrument endpoints. v3 exposes both the consolidated shape and the lot-level shape. The v2 prefix still ships the raw custodian snapshot at custodian holdings for reconciliation, but the consolidated and instrument-level views moved to v3 alongside the instrument-family rename in early 2026.

Two shapes

There are two flavours of holding endpoint. Pick one per integration and stay with it — mixing them gives the same numbers in slightly different shapes and invites subtle reconciliation bugs.

  • Holdings (/api/v3/holdings/...) — the aggregate shape. One row per (reporting entity, instrument, date) with the rolled-up market value and unit count. The right endpoint for dashboards and rollup reports.
  • Instrument holdings (/api/v3/instrument-holdings/...) — the same data exposed per instrument, giving the integrator a richer surface for tax reporting, lot-level analytics, and reconciliation against custodian statements. Renamed from the v2 asset-holdings endpoint in early 2026.

Common attributes

Both shapes carry the same per-row attributes:

  • Name
    date
    Type
    ISO 8601 date
    Description

    The cut-off date the position was reconstructed for.

  • Name
    units
    Type
    decimal
    Description

    Quantity held. Fractional values supported for funds and accrued cash.

  • Name
    marketValue
    Type
    decimal
    Description

    Position value in the reporting currency, post FX conversion.

  • Name
    accruedInterest
    Type
    decimal
    Description

    Coupon interest accrued since the last payment date for fixed-income instruments. Zero for non-bond holdings.

  • Name
    currencyExchangeRate
    Type
    decimal
    Description

    The FX rate applied to convert from the instrument's quote currency into the reporting currency.

  • Name
    reportingCurrencyCode
    Type
    ISO-4217 code
    Description

    The currency marketValue is denominated in.

Expand parameters

Both endpoints accept an expand query parameter that breaks the response down by an additional axis. Pass it more than once to expand multiple axes simultaneously.

  • Name
    portfolios
    Type
    expand axis
    Description

    Break holdings out per portfolio inside the reporting entity.

  • Name
    depositories
    Type
    expand axis
    Description

    Break holdings out per depository.

  • Name
    instruments
    Type
    expand axis
    Description

    Break holdings out per instrument.

  • Name
    instrumentClasses
    Type
    expand axis
    Description

    Break holdings out per top-level instrument class (C1).

  • Name
    instrumentClassesDetailed
    Type
    expand axis
    Description

    Break holdings out per detailed instrument class (C2).

GET/api/v3/holdings/reporting-entities/{id}

Consolidated holdings

Returns aggregated holdings for a reporting entity over a date range. Best for dashboards: one row per (instrument, date), no per-lot detail.

Query parameters

  • Name
    fromDate
    Type
    ISO 8601 date
    Description

    Inclusive lower bound on the snapshot date.

  • Name
    toDate
    Type
    ISO 8601 date
    Description

    Inclusive upper bound on the snapshot date.

  • Name
    expand
    Type
    repeated
    Description

    Optional. Pass once per axis to break the rollup down further — see the list above.

Request

GET/api/v3/holdings/reporting-entities/{id}
curl -G https://platform.aleta.io/api/v3/holdings/reporting-entities/{id} \
  -H "Authorization: Bearer {access_token}" \
  -d fromDate=2026-01-01 \
  -d toDate=2026-04-30 \
  -d expand=instrumentClasses
GET/api/v3/instrument-holdings/reporting-entities/{id}

Lot-level instrument holdings

Returns the same positions but with the per-instrument detail expanded — one row per (reporting entity, instrument, date) carrying the full instrument relationship for joining onto classification and time-series data. The right endpoint for tax reporting, lot-level analytics, and statement-level reconciliation.

Same query parameters as the consolidated endpoint above.

Request

GET/api/v3/instrument-holdings/reporting-entities/{id}
curl -G https://platform.aleta.io/api/v3/instrument-holdings/reporting-entities/{id} \
  -H "Authorization: Bearer {access_token}" \
  -d fromDate=2026-01-01 \
  -d toDate=2026-04-30 \
  -d expand=instruments \
  -d expand=portfolios