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: 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

Data type	Entities	Frequency / cadence	Unit	Primary endpoint	Coverage
Asset group / category membership (reference data)	Assets, groups (categories)	Reference data, refreshed on an ongoing basis as assets are added, removed, or regrouped	Categorical (group and asset names)	/reference-data/asset-groups	🔗

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

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).

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, 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.

Python Client

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()

Shell

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

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()

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.

Full parameter reference: see the Reference Data section 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.

{
  "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.

{
  "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.

{
  "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

Coin Metrics CoverageCoin Metrics Coverage

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, 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 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: what Asset Groups is and how groups relate to each other.
• Asset Taxonomy: the single-classification alternative, with dated history and versioning.
• Asset Profiles: descriptive reference data for the same assets.