# Portfolio statistics Source: https://docs.settlemint.com/docs/developers/developer-guides/api-integration/portfolio-statistics Query portfolio value time series and portfolio breakdowns for the active DALP system through the statistics API. Use the portfolio statistics API when an integration needs reporting data for the current user's portfolio in a DALP system. The endpoints return historical value points, a current asset-type breakdown, and the resolved range DALP used for time series queries. Portfolio statistics are scoped to the active system from the request context. If the same wallet has holdings in more than one DALP system, the result for one system does not include portfolio history, hourly fallback deltas, or breakdown rows from another system. ## Endpoints [#endpoints] The portfolio statistics API exposes three read endpoints: | Endpoint | Use it for | | ---------------------------------------------------------------- | ------------------------------------------------------------------------- | | `GET /api/v2/system/stats/portfolio-stat-ranges` | A custom `from` and `to` time window. | | `GET /api/v2/system/stats/portfolio-stat-range-presets/{preset}` | A predefined trailing window. | | `GET /api/v2/system/stats/portfolio-breakdowns` | The current portfolio value and holdings grouped by asset type and class. | All three endpoints return a JSON:API single-resource envelope with `data` and `links.self`. ## Query a custom range [#query-a-custom-range] Use the range endpoint when your dashboard controls the interval and timestamps. `interval` accepts `hour` or `day`. `from` and `to` are timestamps, and `from` must be before or equal to `to`. ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/stats/portfolio-stat-ranges?interval=hour&from=2026-03-24T13:00:00.000Z&to=2026-03-24T16:00:00.000Z" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` ## Query a preset range [#query-a-preset-range] Use the preset endpoint when DALP should resolve the window from the current time. Supported presets are: | Preset | Interval | | ----------------- | -------- | | `trailing24Hours` | `hour` | | `trailing7Days` | `day` | ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/stats/portfolio-stat-range-presets/trailing7Days" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` ## Query the current breakdown [#query-the-current-breakdown] Use the breakdown endpoint when a dashboard needs the current portfolio total and a grouped view of holdings. ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/stats/portfolio-breakdowns" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` The endpoint has no query parameters. DALP returns the current breakdown for the authenticated wallet and active system. Responses can be cached for that wallet and system, so a repeated request after switching organisations can reuse previously returned asset-type or asset-class labels until the statistics cache refreshes. ## Time-series response shape [#time-series-response-shape] The time-series response body contains the resolved range, portfolio value points, and a currency-conversion reliability flag. DALP rounds monetary points at the API boundary after calculating the indexer-backed series, so consumers can display the returned values directly without applying another FX conversion. ```json { "data": { "range": { "interval": "hour", "from": "2026-03-24T13:00:00.000Z", "to": "2026-03-24T16:00:00.000Z", "isPreset": false }, "data": [ { "timestamp": "2026-03-24T13:00:00.000Z", "totalValueInBaseCurrency": 1000 }, { "timestamp": "2026-03-24T14:00:00.000Z", "totalValueInBaseCurrency": 1200 } ], "conversionReliable": true }, "links": { "self": "/v2/system/stats/portfolio-stat-ranges" } } ``` `data.data` is the time series. Each point includes: * `timestamp`: the bucket timestamp for the returned point. * `totalValueInBaseCurrency`: the portfolio value at that point, rounded for the API response. `conversionReliable` is `false` when one or more FX rates needed for the conversion path are unavailable and DALP had to use its fallback conversion behavior. If DALP cannot resolve a wallet for the authenticated participant, the time-series endpoints still return the requested range with zero-value points for each requested bucket instead of provisioning a wallet as a side effect. ## Breakdown response shape [#breakdown-response-shape] The breakdown response returns current totals, grouped values, grouped holdings, and the same conversion reliability flag. The totals and grouped values are base-currency values from the indexer-backed portfolio views, rounded before DALP emits them through the API. ```json { "data": { "totalValue": "5000000.00", "totalAssetTypes": 2, "totalAssetsHeld": 15, "typeBreakdown": [ { "assetType": "bond", "totalValue": "3000000.00", "tokenBalancesCount": 5, "percentage": 60 }, { "assetType": "equity", "totalValue": "2000000.00", "tokenBalancesCount": 10, "percentage": 40 } ], "valueBreakdown": { "bond": "3000000.00", "equity": "2000000.00" }, "holdingsBreakdown": { "bond": 5, "equity": 10 }, "valueBreakdownByClass": { "fixed-income": "3000000.00", "flexible-income": "2000000.00" }, "holdingsBreakdownByClass": { "fixed-income": 5, "flexible-income": 10 }, "conversionReliable": true }, "links": { "self": "/v2/system/stats/portfolio-breakdowns" } } ``` Use `typeBreakdown` when you need a sortable list with percentages. Use the `valueBreakdown` and `holdingsBreakdown` maps when your application already knows which asset-type keys it wants to display. Asset-type keys can be system types such as `bond` or `equity`, or custom template slugs. Asset-class keys can be system class slugs such as `fixed-income`, or custom organisation class slugs. `conversionReliable` is `false` when one or more FX rates needed for the breakdown are unavailable and DALP had to use its fallback conversion behavior. If the authenticated participant has no wallet in the active system, DALP returns zero totals, empty breakdown maps, and an empty `typeBreakdown` list. ## System scoping [#system-scoping] The portfolio time-series result is calculated for the authenticated user's wallet inside the active system. DALP filters portfolio snapshots and hourly fallback deltas by chain, system, wallet account, and requested time range before building the response. When indexed portfolio snapshots exist, DALP uses those snapshots as the primary source for the time series. It starts from the latest matching snapshot before the requested range, when one exists, and returns the latest in-range snapshot per requested bucket. Snapshot values are already in the organisation's base currency, so integrations should not convert them again. If there are no matching snapshots before or inside the requested range, DALP falls back to the current portfolio total plus hourly value deltas for the same chain, system, and wallet. The API response shape stays the same for both paths. The current breakdown response also uses the authenticated wallet and active system. Tenant scope can affect the organisation-specific asset templates and classes used to label grouped rows, but the response should still be treated as wallet-and-system scoped unless your API environment partitions the endpoint by organisation. That means an integration can safely show the time-series output as the user's portfolio history for the selected system. Treat breakdown output as current wallet-and-system reporting, not as independent organisation-level evidence and not as a response your application can reuse across organisations. Do not add results from another system unless your application is intentionally building a cross-system report. ## Related [#related] * [Getting started with API integration](/docs/developers/developer-guides/api-integration/getting-started) * [Developer guides](/docs/developers/developer-guides) * [Token holders and transfers](/docs/developers/developer-guides/api-integration/token-holders-transfers)