Skip to main content

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 typeEntitiesFrequency / cadenceUnitPrimary endpointCoverage
Asset group / category membership (reference data)Assets, groups (categories)Reference data, refreshed on an ongoing basis as assets are added, removed, or regroupedCategorical (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.

FieldTypeDescriptionNotes
groupstringName of the asset group (category), lowercased and snake_cased, for example stablecoin_usd.Required
constituentsobjectContainer for the group's assets and immediate child groups.Required
constituents.assetsarray of stringCoin 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.groupsarray of stringNames 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
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).

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

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​

Embedded content

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.