# System value and transaction stats API reference

Source: https://docs.settlemint.com/docs/api-reference/reference/system-value-and-transaction-stats
Read the organization-wide total value of indexed assets and the transfer activity for your wallet set through the DALP Platform API, including trailing-window and custom-range time series.



A reporting dashboard for a regulated asset platform needs two headline numbers and the trend behind each: how much value the platform holds right now, and how much it is moving. The system value and transaction stats API answers both. One pair of endpoints reports the organization-wide total value of indexed assets in your base currency, with that total resolved over a time window. A second pair reports transfer activity, scoped to the wallets a caller can see, as both a count and a daily series for charting.

Every endpoint here is read-only. They report values and counts the platform has already indexed. They do not move assets, change holdings, or write any state. For authentication and base URL setup, see [Getting started](/docs/api-reference/reference/getting-started). To read a single participant's portfolio rather than the whole organization, see [Portfolio statistics](/docs/api-reference/tokens/portfolio-statistics).

## Endpoints [#endpoints]

| Endpoint                                                           | Use it for                                                                        |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `GET /api/v2/system/stats/value`                                   | The organization's current total value of indexed assets in the base currency.    |
| `GET /api/v2/system/stats/system-value-histories`                  | Total system value over a custom date range, returned as a timestamped series.    |
| `GET /api/v2/system/stats/system-value-histories/presets/{preset}` | Total system value over a predefined trailing window.                             |
| `GET /api/v2/system/stats/transaction-count`                       | Total and recent transfer counts for the caller's wallet set.                     |
| `GET /api/v2/system/stats/transaction-history`                     | Total and recent transfer counts plus a daily transfer series for the wallet set. |

Each endpoint returns the single-resource envelope with `data` and `links.self`. The active organization and system context bound every read. The conventions are the same across the Platform API, as described in [Organization and system scope](/docs/api-reference/reference/organization-system-scope).

## Read the current system value [#read-the-current-system-value]

`GET /api/v2/system/stats/value` returns the organization-wide total value of every indexed asset, expressed in the organization's base currency.

```bash
curl --globoff "https://your-platform.example.com/api/v2/system/stats/value" \
  -H "x-api-key: YOUR_API_KEY"
```

```json
{
  "data": {
    "totalValue": "1452900.00",
    "conversionReliable": true
  },
  "links": {
    "self": "/v2/system/stats/value"
  }
}
```

| Field                | Type    | Description                                                                                                                   |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `totalValue`         | string  | The total value of indexed assets in the organization's base currency, rounded to two decimals.                               |
| `conversionReliable` | boolean | `true` when every exchange rate used in the conversion is reliable. `false` when at least one rate fell back to a unity rate. |

Read `conversionReliable` before you present `totalValue` as a precise figure. When `conversionReliable` is `false`, one or more assets are denominated in a currency whose exchange rate could not be resolved, so the total mixes reliable and fallback conversions. Surface that state in the interface rather than showing the number as exact.

## Read system value over time [#read-system-value-over-time]

The system value history endpoints return the same total value resolved across a time window, as a timestamped series suitable for a chart. The series starts from a computed baseline at the start of the range and accumulates daily value changes up to the current total.

Use the range endpoint for a custom window and the preset endpoint for a fixed trailing window.

```bash
curl --globoff "https://your-platform.example.com/api/v2/system/stats/system-value-histories/presets/trailing7Days" \
  -H "x-api-key: YOUR_API_KEY"
```

```json
{
  "data": {
    "range": {
      "interval": "day",
      "from": "2026-06-14T00:00:00.000Z",
      "to": "2026-06-21T00:00:00.000Z",
      "isPreset": true
    },
    "data": [
      { "timestamp": "2026-06-14T00:00:00.000Z", "totalValueInBaseCurrency": 1438100.0 },
      { "timestamp": "2026-06-21T00:00:00.000Z", "totalValueInBaseCurrency": 1452900.0 }
    ],
    "conversionReliable": true
  },
  "links": {
    "self": "/v2/system/stats/system-value-histories/presets/trailing7Days"
  }
}
```

### Query controls [#query-controls]

| Parameter                     | Description                                                                                                                                   |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `interval` (range endpoint)   | Required. `hour` or `day`. The bucket size for the returned series.                                                                           |
| `from`, `to` (range endpoint) | Required. The start and end of the window. `from` must be before or equal to `to`.                                                            |
| `{preset}` (preset endpoint)  | Path parameter. `trailing24Hours` returns an hourly series for the last 24 hours; `trailing7Days` returns a daily series for the last 7 days. |

The platform clamps the resolved window to the present: a `to` in the future is pulled back to the current time. The response echoes the window the platform actually used in `range`, so read `range.from`, `range.to`, and `range.interval` rather than assuming your request values were applied unchanged. `range.isPreset` is `true` for the preset endpoint and `false` for the range endpoint.

### Series fields [#series-fields]

| Field                             | Type    | Description                                                                                          |
| --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `range`                           | object  | The resolved window: `interval`, `from`, `to`, and `isPreset`.                                       |
| `data`                            | array   | The value series. Each point carries a `timestamp` and the `totalValueInBaseCurrency` at that point. |
| `data[].timestamp`                | string  | The bucket timestamp.                                                                                |
| `data[].totalValueInBaseCurrency` | number  | The accumulated total value at that point, in the organization's base currency.                      |
| `conversionReliable`              | boolean | `false` when at least one exchange rate used in the conversion fell back to a unity rate.            |

## Read transaction activity [#read-transaction-activity]

The transaction endpoints count completed transfers. `transaction-count` returns the headline totals; `transaction-history` returns the same totals plus a daily series for charting.

```bash
curl --globoff "https://your-platform.example.com/api/v2/system/stats/transaction-history?timeRange=30" \
  -H "x-api-key: YOUR_API_KEY"
```

```json
{
  "data": {
    "totalTransactions": 8421,
    "recentTransactions": 312,
    "transactionHistory": [
      { "timestamp": "2026-05-23T00:00:00.000Z", "transactions": 9 },
      { "timestamp": "2026-05-24T00:00:00.000Z", "transactions": 14 }
    ],
    "timeRangeDays": 30
  },
  "links": {
    "self": "/v2/system/stats/transaction-history"
  }
}
```

### Query controls [#query-controls-1]

| Parameter   | Description                                                                                              |
| ----------- | -------------------------------------------------------------------------------------------------------- |
| `timeRange` | The window in days for the recent count and the daily series. An integer from 1 to 365, defaulting to 7. |

### Response fields [#response-fields]

| Field                               | Type   | Description                                                        |
| ----------------------------------- | ------ | ------------------------------------------------------------------ |
| `totalTransactions`                 | number | The all-time count of completed transfers in scope.                |
| `recentTransactions`                | number | The count of completed transfers within `timeRange` days.          |
| `transactionHistory`                | array  | The daily transfer series. Returned by `transaction-history` only. |
| `transactionHistory[].timestamp`    | string | The day bucket, in UTC.                                            |
| `transactionHistory[].transactions` | number | The number of completed transfers on that day.                     |
| `timeRangeDays`                     | number | The window in days that the recent count and series used.          |

`transaction-count` returns the same `totalTransactions`, `recentTransactions`, and `timeRangeDays` fields without the `transactionHistory` array. Call it when you need the headline numbers without the chart series.

### What counts as a transaction [#what-counts-as-a-transaction]

Both transaction endpoints count completed asset transfers, the moment a transfer settles on-chain. Counts are bucketed by UTC day, so a daily series follows calendar days in UTC rather than the caller's local time zone.

## Who sees which value and which transactions [#who-sees-which-value-and-which-transactions]

The value endpoints are organization-wide. They report the total value of every indexed asset in the active organization, regardless of which wallets the caller holds.

The transaction endpoints are scoped to the caller's wallet set: the caller's signing account and every smart wallet that lists it as a signer. A caller with the organization update permission instead reads the org-wide activity, covering every wallet in the active organization. This lets an operator dashboard report platform-wide transfer volume while a standard integration sees only its own.

A caller whose wallet set is empty, such as an API key with no default wallet, receives zero counts and an empty series rather than an error. Treat unexpected zeros as a possible scope or wallet-resolution gap rather than proof of no activity.

## When to use it [#when-to-use-it]

Use these endpoints when you need to:

* Show the organization's current total value of indexed assets, with a reliability flag for the underlying currency conversion.
* Chart total system value over a trailing window or a custom date range.
* Report total and recent transfer counts for a dashboard headline.
* Plot daily transfer activity for the caller's wallet set, or org-wide for a privileged operator view.

To read value and holdings for a single participant rather than the whole organization, see [Portfolio statistics](/docs/api-reference/tokens/portfolio-statistics). For the conventions every read endpoint shares, see [Organization and system scope](/docs/api-reference/reference/organization-system-scope).