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 (quantity, market value, cost basis) and a reference to the instrument it represents, so integrators can join on pricing, classification, or fundamentals data from the instruments endpoints.

Holding vs. Instrument Holding

There are two flavours of holding, served by two versioned endpoints:

  • Holding (v2) — the aggregate shape. Quantity + market value + cost basis, no per-lot detail. The right endpoint for dashboards and rollup reports.
  • Instrument Holding (v3) — the same data but expanded per instrument with the full lot list underneath. Used for tax reporting, lot-level analytics, and reconciliation against custodian statements.

You rarely need both in the same integration — pick the one that matches your use case and stick with it. Mixing them gives the same numbers in slightly different shapes and invites subtle reconciliation bugs.

Data model — Holding

  • Name
    reporting_entity_id
    Type
    string
    Description

    The reporting entity whose holdings these are.

  • Name
    instrument_id
    Type
    string
    Description

    Aleta's canonical instrument reference. Join with the instrument catalogue for metadata like ticker, ISIN, and classification.

  • Name
    quantity
    Type
    decimal
    Description

    Units held. Fractional values supported.

  • Name
    market_value
    Type
    decimal
    Description

    Latest valuation in the reporting entity's reference currency.

  • Name
    cost_basis
    Type
    decimal
    Description

    Aggregate cost basis across all open lots, in the reference currency, computed via the client's configured accounting method.

  • Name
    unrealised_pnl
    Type
    decimal
    Description

    Convenience field — market_value - cost_basis. Exposed so consumers don't all re-derive it.

  • Name
    as_of
    Type
    timestamp
    Description

    The cut-off date used for reconstruction.

GET/v2/holdings/reporting-entities/{id}

List current holdings

Returns the reporting entity's consolidated holdings as of now. Supply as_of to query a historical snapshot — because holdings are reconstructed deterministically from the ledger, byte-identical responses for the same parameters are safe to cache downstream.

Optional query parameters

  • Name
    as_of
    Type
    timestamp
    Description

    Returns the holdings snapshot closest to this timestamp instead of the latest. Useful for reconciliation against custodian statements.

  • Name
    cursor
    Type
    string
    Description

    Pagination cursor. See Pagination.

Request

GET
/v2/holdings/reporting-entities/{id}
curl https://api.aleta.io/v2/holdings/reporting-entities/{id} \
  -H "Authorization: Bearer {token}"
GET/v3/instrument-holdings/reporting-entities/{id}

Retrieve lot-level holdings

The v3 shape — same positions, but with every open lot spelled out underneath. Acquisition date, lot quantity, per-lot cost, and realised-gain classification are all surfaced.

Pick one flavour per integration and stay with it. Mixing the v2 aggregate and v3 lot-level shapes gives the same underlying numbers in slightly different forms and invites subtle reconciliation bugs.

Request

GET
/v3/instrument-holdings/reporting-entities/{id}
curl https://api.aleta.io/v3/instrument-holdings/reporting-entities/{id} \
  -H "Authorization: Bearer {token}"
  • Custodian holdings — raw position snapshots as they arrive from the custodian.
  • Transactions — the ledger that holdings are reconstructed from.
  • Performance — time-weighted returns over the same reporting entity.