> For the complete documentation index, see [llms.txt](https://gitbook-docs.coinmetrics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook-docs.coinmetrics.io/reference-data/asset-groups-overview/asset-groups.md).

# Asset Groups

## Overview

Asset Groups is Coin Metrics' system for grouping related assets into named, topical categories, for example every USD-pegged stablecoin, or every tokenized real-world-asset product. It answers a different question than [datonomy](/reference-data/datonomy-overview/asset-taxonomy.md): not what is this asset primarily for, but which named categories does this asset currently belong to, given that an asset can sit in several categories at once and categories themselves can nest inside broader categories. Portfolio and product teams use it to pull the current membership list for a category, or for an entire branch of related categories, without maintaining their own asset lists by hand.

## At a Glance

<table data-full-width="true"><thead><tr><th>Data type</th><th>Entities</th><th width="159">Frequency / cadence</th><th>Unit</th><th>Primary endpoint</th><th>Coverage</th></tr></thead><tbody><tr><td>Asset group / category membership (reference data)</td><td>Assets, groups (categories)</td><td>Reference data, refreshed on an ongoing basis as assets are added, removed, or regrouped</td><td>Categorical (group and asset names)</td><td><code>/reference-data/asset-groups</code></td><td><a href="https://coverage.coinmetrics.io/assets-v2">🔗</a></td></tr></tbody></table>

## Schema

The response returns one object per matched group. Each object names the group and lists its constituents: the assets that belong to it and the child groups nested beneath it.

| Field                 | Type            | Description                                                                                                                                                                                                                     | Notes    |
| --------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `group`               | string          | Name of the asset group (category), lowercased and snake\_cased, for example `stablecoin_usd`.                                                                                                                                  | Required |
| `constituents`        | object          | Container for the group's assets and immediate child groups.                                                                                                                                                                    | Required |
| `constituents.assets` | array of string | Coin Metrics asset names belonging to this group, either tagged directly or rolled up from any descendant group. When the request's `assets` parameter is set, this list is narrowed to only the requested assets that matched. | Required |
| `constituents.groups` | array of string | Names of this group's immediate child groups. Always the complete set of children, regardless of any `assets` or `groups` filter applied to the request. Empty for a group with no children.                                    | Required |

{% hint style="info" %}
**Conventions.** Asset and group names are lowercase, matching the names used across the rest of the API (`usdc`, not `USDC`). The `assets` and `groups` request parameters are case-insensitive. This endpoint has no per-observation timestamp: it returns the current state of group membership and nesting, not a point-in-time snapshot, and it is not paginated (`page_size` is rejected as an unsupported parameter).
{% endhint %}

## Methodology

### Groups as sets, some of which nest

Groups are not one single global tree. Each group is its own named set of assets, and a group may or may not nest other groups beneath it. Where nesting exists, such as `rwa` nesting `stablecoin`, which itself nests `stablecoin_eur` and `stablecoin_usd`, `constituents.groups` on a given group's response lists the groups nested directly beneath it, so walking a nested branch means following that field down one level at a time, or querying a specific `groups` value directly. Just as many groups stand on their own, defined by a shared property rather than membership in a broader category, for example an asset being pegged to the US dollar.

### Direct membership and roll-up

A group's `constituents.assets` is the union of two things: assets tagged to that group directly, and, for any groups nested beneath it, every asset tagged to those groups (and any nested further beneath them). A group's asset list is therefore always at least as large as the combined lists of any groups nested inside it, and can be larger still if assets are tagged to it directly without also being tagged to one of its named nested groups. This is why the asset list on a broad, deeply-nested group like `rwa` can run into the hundreds of assets: it rolls up everything tagged anywhere beneath it.

### Filtering semantics

The endpoint takes two independent filters, `assets` and `groups`, both comma-separated:

* **`groups`** returns exactly the named group(s), each with its full constituents as described above.
* **`assets`** returns every group, however deeply nested, whose rolled-up asset list intersects the requested asset(s). `constituents.assets` on each returned group is narrowed to just the requested assets that matched; `constituents.groups` is not narrowed, and still lists the group's complete set of nested groups.
* Supplying both filters together applies them as a combined (AND) condition: the response is scoped to the intersection of the named groups and the requested assets, rather than the union of two independent queries.
* An asset with no group membership, or a request whose filters share no overlap, returns an empty `data` array rather than an error.

### No historical membership

The endpoint reflects only the current state of group membership and nesting. There is no `version` parameter and no time-range filter (unlike [Asset Taxonomy](/reference-data/datonomy-overview/asset-taxonomy.md), which supports `version=*` for full revision history), so a group's past membership cannot be reconstructed from this endpoint.

## Accessing the Data

Asset group data is served by the `/reference-data/asset-groups` endpoint. Requests are filtered by `assets`, by `groups`, or by both together, with no time range and no pagination.

{% tabs %}
{% tab title="Python Client" %}

```python
import pandas as pd
from coinmetrics.api_client import CoinMetricsClient

client = CoinMetricsClient("YOUR_API_KEY")

# Every group a specific asset belongs to
groups = client.reference_data_asset_groups(assets=["usdc"]).to_list()

# Full constituents of a named group, including its child groups
stablecoins = client.reference_data_asset_groups(groups=["stablecoin"]).to_list()
```

{% endtab %}

{% tab title="Shell" %}

```bash
curl --compressed "https://api.coinmetrics.io/v4/reference-data/asset-groups?assets=usdc&groups=stablecoin&api_key=$CM_API_KEY"
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import requests

response = requests.get(
    "https://api.coinmetrics.io/v4/reference-data/asset-groups",
    params={
        "assets": "usdc",
        "groups": "stablecoin",
        "api_key": os.environ["CM_API_KEY"],
    },
).json()
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Prefer `.to_list()` over `.to_dataframe()` on this endpoint.** Each record nests `constituents.assets` and `constituents.groups` as lists inside a `constituents` object, which does not flatten cleanly into a single row per record. Build any tabular view from the list yourself, for example one row per (group, asset) pair.
{% endhint %}

Full parameter reference: see the [Reference Data section](https://docs.coinmetrics.io/api/v4/#tag/Reference-Data) of the API Reference for `/reference-data/asset-groups`.

## Examples

### Example: groups for a single asset

Filtering by both `assets` and `groups` scopes a single named group down to just the requested asset. [Run this query](https://api.coinmetrics.io/v4/reference-data/asset-groups?assets=usdc\&groups=stablecoin\&api_key=YOUR_API_KEY).

```json
{
  "data": [
    {
      "group": "stablecoin",
      "constituents": {
        "assets": [
          "usdc"
        ],
        "groups": [
          "stablecoin_eur",
          "stablecoin_usd"
        ]
      }
    }
  ]
}
```

### Example: full constituents of a named group

Filtering by `groups` alone returns the group's complete membership. `tokenized_gold` has no child groups, so every asset shown is tagged directly. [Run this query](https://api.coinmetrics.io/v4/reference-data/asset-groups?groups=tokenized_gold\&api_key=YOUR_API_KEY).

```json
{
  "data": [
    {
      "group": "tokenized_gold",
      "constituents": {
        "assets": [
          "cgt",
          "dgx",
          "gld",
          "gldon",
          "gldx",
          "gldx_eth",
          "iauon",
          "paxg",
          "pmgt",
          "upxau",
          "xaut",
          "xaut_1_eth",
          "xaut_2_eth",
          "xaut_eth"
        ],
        "groups": []
      }
    }
  ]
}
```

### Example: roll-up across branches for multiple assets

Filtering by two assets nested under different parts of `rwa` returns every group that includes either asset, whether directly or through nesting. `ousg` and `usdc` share only `rwa` itself, so it is the only group where both appear together. [Run this query](https://api.coinmetrics.io/v4/reference-data/asset-groups?assets=usdc%2Cousg\&api_key=YOUR_API_KEY).

```json
{
  "data": [
    {
      "group": "money_market_fund",
      "constituents": {
        "assets": ["ousg"],
        "groups": []
      }
    },
    {
      "group": "rwa",
      "constituents": {
        "assets": ["ousg", "usdc"],
        "groups": ["stablecoin", "tokenized_commodity", "tokenized_debt", "tokenized_equity"]
      }
    },
    {
      "group": "stablecoin",
      "constituents": {
        "assets": ["usdc"],
        "groups": ["stablecoin_eur", "stablecoin_usd"]
      }
    },
    {
      "group": "stablecoin_usd",
      "constituents": {
        "assets": ["usdc"],
        "groups": ["stablecoin_usd_borrowed", "stablecoin_usd_bridged", "stablecoin_usd_staked", "stablecoin_usd_wrapped"]
      }
    },
    {
      "group": "tokenized_debt",
      "constituents": {
        "assets": ["ousg"],
        "groups": ["clo", "money_market_fund", "tokenized_treasury_fund"]
      }
    }
  ]
}
```

## Coverage

{% embed url="<https://coverage.coinmetrics.io/assets-v2>" %}

## Limitations

* **Current state only.** There is no `version` parameter and no time-range filter, so past category membership cannot be reconstructed from this endpoint. Contrast with [Asset Taxonomy](/reference-data/datonomy-overview/asset-taxonomy.md), which carries a full, dated revision history.
* **A broad group's asset list can be large.** A group that nests many others beneath it, such as `rwa`, rolls up every asset tagged anywhere beneath it. If only the directly nested groups are needed, read `constituents.groups` and query those group names individually rather than parsing the full rolled-up asset list.
* **Not paginated.** `page_size` is rejected as an unsupported parameter, and the full set of matched groups is returned in a single response.

## FAQ

### How is Asset Groups different from Asset Taxonomy?

[Asset Taxonomy](/reference-data/datonomy-overview/asset-taxonomy.md) assigns each asset to exactly one class, sector, and subsector, with a dated history of reclassifications. Asset Groups instead lets an asset belong to several overlapping categories at once (for example `usdc` sits in `stablecoin`, `stablecoin_usd`, and `rwa` simultaneously), and it only exposes the current membership, with no history.

### Can an asset belong to more than one group?

Yes. An asset tagged directly to a group also counts toward any broader group that nests it, so it can show up under several groups at once.

### How do I get every asset in a category and its subcategories?

Query that group by name with the `groups` parameter. `constituents.assets` returns the full roll-up: every asset tagged directly to the group plus every asset tagged to any group nested beneath it.

### How do I see just the direct children of a group?

Read `constituents.groups` on that group's response. It always lists the immediate children only, regardless of any `assets` filter applied to the request.

### What happens if I request a group or asset that doesn't exist?

The request fails with a `bad_parameter` error naming the unsupported value, for example requesting `groups=notreal` returns `Bad parameter 'groups'. Group 'notreal' is not supported.`

## Related

* [Asset Groups Overview](/reference-data/asset-groups-overview.md): what Asset Groups is and how groups relate to each other.
* [Asset Taxonomy](/reference-data/datonomy-overview/asset-taxonomy.md): the single-classification alternative, with dated history and versioning.
* [Asset Profiles](/reference-data/profiles-overview/asset-profiles.md): descriptive reference data for the same assets.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook-docs.coinmetrics.io/reference-data/asset-groups-overview/asset-groups.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.