> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rwa.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Timeseries & Aggregation

> Pull historical data and aggregate metrics across entities

The RWA API provides timeseries endpoints for tracking metrics over time and aggregating data across assets, tokens, networks, and asset classes.

## Timeseries endpoints

| Endpoint                                                                                     | Granularity | Use case                                               |
| -------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------ |
| [`/v4/assets/aggregates/timeseries`](/api/endpoints/assets#get-v4assetsaggregatestimeseries) | Asset-level | Track NAV, supply, or holders for one or many assets   |
| [`/v4/tokens/aggregates/timeseries`](/api/endpoints/tokens#get-v4tokensaggregatestimeseries) | Token-level | Break down metrics by chain (e.g., supply per network) |

Both endpoints use the same query language and response format.

## The aggregate block

Timeseries queries use an `aggregate` block to control grouping, time resolution, and computation mode:

```json theme={null}
{
  "aggregate": {
    "groupBy": "asset",
    "aggregateFunction": "sum",
    "interval": "day",
    "mode": "stock"
  }
}
```

### groupBy

Controls how results are grouped. Each unique group becomes a separate series in the response.

| Value         | Description          | Returns                                                 |
| ------------- | -------------------- | ------------------------------------------------------- |
| `asset`       | Group by asset       | One series per asset                                    |
| `token`       | Group by token       | One series per on-chain token (chain-level granularity) |
| `asset_class` | Group by asset class | One series per asset class                              |
| `network`     | Group by network     | One series per blockchain network                       |
| `date`        | No entity grouping   | A single combined series                                |

### interval

The time resolution of each data point.

| Value   | Description         |
| ------- | ------------------- |
| `day`   | One point per day   |
| `week`  | One point per week  |
| `month` | One point per month |
| `year`  | One point per year  |

### mode

How values are computed within each interval.

| Value   | Description                                         | Use when                                                                     |
| ------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
| `stock` | Point-in-time snapshot (latest value in the period) | Tracking balances, NAV, supply, holders — metrics that represent a **state** |
| `flow`  | Accumulated over the period                         | Tracking mints, burns, transfers — metrics that represent **activity**       |

**Example:** For monthly supply, `stock` returns the supply at the end of each month. For monthly mints, `flow` returns the total minted during each month.

### aggregateFunction

| Value | Description                 |
| ----- | --------------------------- |
| `sum` | Sum values across the group |
| `avg` | Average across the group    |
| `min` | Minimum value in the group  |
| `max` | Maximum value in the group  |

## Discovering available measures

Every timeseries query requires a `measure_slug` filter to specify which metric to retrieve. Use the meta endpoints to discover available measures:

```bash theme={null}
curl -X GET 'https://api.rwa.xyz/v4/assets/aggregates/meta' \
  -H "Authorization: Bearer $RWA_API_KEY"
```

The `measure_slug` field in the response lists all available measures as `selectOptions`. You can also browse measures in the [Data Catalog](https://app.rwa.xyz/catalog).

**Common measures:**

| Slug                              | Description                     |
| --------------------------------- | ------------------------------- |
| `net_asset_value_dollar`          | NAV in USD                      |
| `price_dollar`                    | Price in USD                    |
| `circulating_supply_token`        | Circulating token supply        |
| `circulating_market_value_dollar` | Circulating market value in USD |
| `circulating_asset_value_dollar`  | Circulating asset value in USD  |
| `holding_addresses_count`         | Number of unique holders        |
| `daily_mints_dollar`              | Daily mint volume in USD        |
| `daily_burns_dollar`              | Daily burn volume in USD        |
| `daily_transfer_volume_dollar`    | Daily transfer volume in USD    |
| `apy_7_day`                       | 7-day APY                       |
| `apy_30_day`                      | 30-day APY                      |

## Response format

Timeseries responses differ from list endpoints. Each result contains a **measure** descriptor, a **group** descriptor, and an array of **points**:

```json theme={null}
{
  "results": [
    {
      "measure": {
        "id": 3,
        "slug": "net_asset_value_dollar",
        "name": "Net Asset Value (Dollar)",
        "unit": "dollar"
      },
      "group": {
        "id": 51,
        "type": "asset",
        "name": "Circle USYC",
        "color": "#2A3758"
      },
      "points": [
        ["2023-10-19", 1.01577],
        ["2023-10-20", 1.01590],
        ["2023-10-21", 1.01603]
      ]
    }
  ],
  "pagination": { "page": 1, "perPage": 30, "pageCount": 1, "resultCount": 1 }
}
```

| Field     | Description                                                              |
| --------- | ------------------------------------------------------------------------ |
| `measure` | The metric being returned (slug, name, unit)                             |
| `group`   | What the data is grouped by — a specific asset, token, asset class, etc. |
| `points`  | Array of `[date, value]` pairs in chronological order                    |

## Examples

### Track an asset's NAV over time

```bash theme={null}
curl -G 'https://api.rwa.xyz/v4/assets/aggregates/timeseries' \
  -H "Authorization: Bearer $RWA_API_KEY" \
  --data-urlencode 'query={
    "filter": {
      "operator": "and",
      "filters": [
        { "operator": "equals", "field": "asset_id", "value": "51" },
        { "operator": "equals", "field": "measure_slug", "value": "net_asset_value_dollar" }
      ]
    },
    "pagination": { "page": 1, "perPage": 365 }
  }'
```

When no `aggregate` block is provided, the endpoint defaults to daily granularity grouped by the entity type.

### Compare token supply across chains

Use `groupBy: "token"` to get a separate series for each on-chain deployment:

```bash theme={null}
curl -G 'https://api.rwa.xyz/v4/tokens/aggregates/timeseries' \
  -H "Authorization: Bearer $RWA_API_KEY" \
  --data-urlencode 'query={
    "filter": {
      "operator": "and",
      "filters": [
        { "operator": "equals", "field": "asset_id", "value": "51" },
        { "operator": "equals", "field": "measure_slug", "value": "total_supply_token" }
      ]
    },
    "aggregate": {
      "groupBy": "token",
      "aggregateFunction": "sum",
      "interval": "day",
      "mode": "stock"
    }
  }'
```

This returns one series per chain (e.g., "Ethereum USYC", "Solana USYC", "BNB Chain USYC"), so you can see how supply is distributed across networks.

### Aggregate an entire asset class over time

Use `groupBy: "asset_class"` to sum across all assets in a category:

```bash theme={null}
curl -G 'https://api.rwa.xyz/v4/assets/aggregates/timeseries' \
  -H "Authorization: Bearer $RWA_API_KEY" \
  --data-urlencode 'query={
    "filter": {
      "operator": "and",
      "filters": [
        { "operator": "equals", "field": "asset_class_name", "value": "US Treasury Debt" },
        { "operator": "equals", "field": "measure_slug", "value": "net_asset_value_dollar" }
      ]
    },
    "aggregate": {
      "groupBy": "asset_class",
      "aggregateFunction": "sum",
      "interval": "month",
      "mode": "stock"
    }
  }'
```

This gives you the total market size of tokenized U.S. Treasuries over time, with one data point per month.

## Choosing the right endpoint

| Question                                        | Endpoint                           | groupBy       |
| ----------------------------------------------- | ---------------------------------- | ------------- |
| What is this asset's total NAV over time?       | `/v4/assets/aggregates/timeseries` | `asset`       |
| How is supply distributed across chains?        | `/v4/tokens/aggregates/timeseries` | `token`       |
| What's the total market size of an asset class? | `/v4/assets/aggregates/timeseries` | `asset_class` |
| What are daily mints per network?               | `/v4/tokens/aggregates/timeseries` | `network`     |
| What's the total value of all assets combined?  | `/v4/assets/aggregates/timeseries` | `date`        |