> 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/datonomy-overview/asset-taxonomy.md). # Asset Taxonomy ## Overview The asset taxonomy assigns every covered asset to exactly one category in datonomy, the digital asset classification system. It answers a single question: what is this asset for? Each asset receives a class, a sector, and a subsector, described by both a numeric code and a human-readable name, based on what the asset and its underlying protocol are primarily used for. The starting point is the purpose the protocol's creators describe, but where that differs materially from market perception and observed usage, observed usage takes precedence. Portfolio managers, risk teams, and researchers use it to group holdings, measure exposure and performance by category, and screen a universe of assets by economic function rather than by ticker. ## At a Glance
Data typeEntitiesFrequency / cadenceUnitPrimary endpointCoverage
Asset classification (reference data)AssetsReference data, refreshed on an ongoing basis as assets enter, leave, or are reclassifiedCategorical (codes and names)/taxonomy/assets🔗
## Schema The response returns one object per asset classification revision. An asset that has never been reclassified returns a single object. All fields are populated on every row except `classification_end_time`, which appears only once a classification has been superseded or the asset has left the coverage universe. | Field | Type | Description | Notes | | ----------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | | `asset` | string | Coin Metrics name of the asset, lowercased. | Required | | `full_name` | string | Full name of the asset. | Required | | `updated_at_taxonomy_version` | string | Taxonomy version at which the asset was classified or reclassified. See [Versions and carry-forward](#versions-and-carry-forward). | Required | | `taxonomy_version` | string | Obsolete. Retained for backward compatibility and scheduled for removal. Use `updated_at_taxonomy_version` instead. | Required, deprecated | | `classification_start_time` | string (date-time) | Date from which this classification is in effect for the asset. See [Classification revisions and effective dates](#classification-revisions-and-effective-dates). | Required. Served as `YYYY-MM-DD` | | `classification_end_time` | string (date-time) | Date at which this classification stopped being in effect. Absent while the classification is current. | Optional. Served as `YYYY-MM-DD` | | `class_id` | string | Two-digit code for the class. | Required | | `class` | string | First level of the taxonomy, describing the asset's fundamental purpose. | Required | | `sector_id` | string | Four-digit code for the sector. The first two digits are the `class_id`. | Required | | `sector` | string | Second level of the taxonomy, describing the asset's focus area within its class. | Required | | `subsector_id` | string | Six-digit code for the subsector. The first four digits are the `sector_id`. | Required | | `subsector` | string | Third level of the taxonomy, describing the asset's specific product, service, or function. | Required | {% hint style="info" %} **Conventions.** Codes are returned as JSON strings, not integers, so that leading digits are preserved. The classification time fields are served in ISO-8601 calendar-date form (`2022-11-03`) rather than as full UTC timestamps, so they carry no time of day and no zone offset. Classification changes are effective from the start of the stated day. Asset names are lowercased Coin Metrics asset names, so `btc` rather than `BTC`. The code hierarchy is positional: a `subsector_id` of `101010` sits in sector `1010`, which sits in class `10`. Every classified asset belongs to exactly one subsector at any point in time. {% endhint %} ## Methodology ### The three levels The taxonomy has three nested levels, and an asset is placed at the most specific one. Its class and sector follow from the code hierarchy rather than being assigned separately. | Level | Code width | What it describes | Example | | --------- | ---------- | --------------------------------------------------- | ------------------------------ | | Class | 2 digits | The asset's fundamental purpose. | `10`, Digital Currencies | | Sector | 4 digits | The asset's focus area within its class. | `1010`, Value Transfer Coins | | Subsector | 6 digits | The asset's specific product, service, or function. | `101010`, Value Transfer Coins | The full set of classes, sectors, and subsectors for a version is served by [Asset Taxonomy Metadata](/reference-data/datonomy-overview/asset-taxonomy-metadata.md). ### Classification revisions and effective dates A classification is stored as a dated revision rather than as a single mutable value. Each revision carries the version at which it was made (`updated_at_taxonomy_version`), the time from which it applies (`classification_start_time`), and, once superseded, the time at which it stopped applying (`classification_end_time`). An asset that has been reclassified therefore has more than one revision, each covering a distinct, non-overlapping window. This matters for point-in-time work. `classification_start_time` is a property of the asset, not of the taxonomy version. An asset added to the coverage universe after a version was published carries the date it was added, not the version's start date, so two assets in the same version routinely have different start times. ### Versions and carry-forward The taxonomy itself is versioned. Requests resolve to a version as follows: * No `version` and no time parameters: the latest version. * `version=`: that specific version. * `version=*`: every version, which returns the full revision history for each asset. * A `classification_start_time` or `classification_end_time` without an explicit `version`: all versions are considered, then filtered by the time range. When a specific version is requested and an asset has no revision recorded at that version, its most recent earlier revision is carried forward and returned under the requested version. The carry-forward is suppressed when that earlier revision had already ended before the requested version began, in which case the asset is simply absent from that version. This makes a single-version query return the complete classified universe as it stood at that version, rather than only the assets that happened to change. Version windows are validated when the data is loaded. Versions must be strictly ordered and must not overlap. Where a version has no explicit end, it is treated as ending when the next version begins, and the latest version has no end. ### Eligibility and the coverage universe To be eligible for classification, an asset must be widely available to investors globally rather than confined to a single venue. Availability is measured against a screened universe of digital asset exchanges, and the bar to enter is higher than the bar to stay: * **To enter,** an asset must have traded at least once in the past 30 days on at least 25% of eligible exchanges. * **To remain classified,** an already classified asset must have traded at least once in the past 30 days on at least 10% of eligible exchanges, subject to a floor of two exchanges. The gap between the two is deliberate. It keeps assets near the boundary from entering and leaving on small changes in venue coverage. An asset that falls below the lower bar is reviewed for removal rather than dropped automatically. Exchange eligibility is itself screened rather than assumed. A venue counts toward these thresholds only after it is assessed on its data feed reliability, compliance posture, business model, data availability, and volume reporting quality. See the [methodology](/reference-data/methodologies/datonomy-methodology.md) for the full set of guiding principles. ### Classification review Classification decisions sit with MSCI, which administers datonomy. Coin Metrics contributes the market data behind the eligibility screening and serves the resulting classifications through this API. There is no fixed review calendar. New assets, reclassifications, and removals are each reviewed and implemented as needed, so `classification_start_time` can carry any date rather than clustering on scheduled review dates. The structure itself is reviewed at least annually. Because changes are event-driven rather than periodic, treat the API as the source of truth for when a classification took effect rather than assuming a rebalance-style cadence. ### Ordering and pagination Results are ordered by asset name, then by `classification_start_time`, so an asset's revisions appear in chronological order within its own block. `paging_from` reverses the order. Filters on `class_ids`, `sector_ids`, and `subsector_ids` are applied to whichever revisions the version resolution selected, and a filter on `classification_end_time` matches only revisions that have actually ended. ## Accessing the Data Asset taxonomy data is served by the `/taxonomy/assets` endpoint. Requests are filtered by asset or by any level of the hierarchy, using `assets`, `class_ids`, `sector_ids`, or `subsector_ids`, and optionally scoped to a taxonomy version or a classification time range. {% tabs %} {% tab title="Python Client" %} ```python import pandas as pd from coinmetrics.api_client import CoinMetricsClient client = CoinMetricsClient("YOUR_API_KEY") # Classification for specific assets assets = client.get_taxonomy_assets(assets=["btc", "eth", "axs"]).to_list() print(pd.DataFrame(assets)) # Screen a whole class or subsector currencies = client.get_taxonomy_assets(class_ids=["10"]).to_list() gaming = client.get_taxonomy_assets(subsector_ids=["305020"]).to_list() # Full revision history across every taxonomy version history = client.get_taxonomy_assets(assets=["btc"], version="*").to_list() ``` {% endtab %} {% tab title="Shell" %} ```bash curl --compressed "https://api.coinmetrics.io/v4/taxonomy/assets?assets=btc,eth,axs&page_size=10000&api_key=$CM_API_KEY" ``` {% endtab %} {% tab title="Python" %} ```python import os import requests response = requests.get( "https://api.coinmetrics.io/v4/taxonomy/assets", params={ "assets": "btc,eth,axs", "page_size": 10000, "api_key": os.environ["CM_API_KEY"], }, ).json() ``` {% endtab %} {% endtabs %} {% hint style="warning" %} **Use `.to_list()` on this endpoint, not `.to_dataframe()`.** The classification time fields are returned as calendar dates with no zone offset, which the client's dataframe conversion cannot parse. Build the frame with `pd.DataFrame(...)` from the list instead, as shown above. {% endhint %} Responses are paginated. The Python client follows pagination automatically, while direct HTTP callers page through results using `next_page_token`. Full parameter reference: see the API Reference for [`/taxonomy/assets`](https://docs.coinmetrics.io/api/v4/#operation/getTaxonomyAssets). ## Examples ### Example: classification for specific assets The current classification for three assets, one in each of three different classes. Each row carries both the numeric codes and their names, so no lookup against the metadata endpoint is required to read the result. [Run this query](https://api.coinmetrics.io/v4/taxonomy/assets?assets=btc,eth,axs\&api_key=YOUR_API_KEY). ```json { "data": [ { "asset": "axs", "full_name": "Axie Infinity", "taxonomy_version": "1.0", "updated_at_taxonomy_version": "1.0", "classification_start_time": "2022-11-03", "class_id": "30", "class": "Digital Asset Applications", "sector_id": "3050", "sector": "Metaverse", "subsector_id": "305020", "subsector": "Gaming" }, { "asset": "btc", "full_name": "Bitcoin", "taxonomy_version": "1.0", "updated_at_taxonomy_version": "1.0", "classification_start_time": "2022-11-03", "class_id": "10", "class": "Digital Currencies", "sector_id": "1010", "sector": "Value Transfer Coins", "subsector_id": "101010", "subsector": "Value Transfer Coins" }, { "asset": "eth", "full_name": "Ethereum", "taxonomy_version": "1.0", "updated_at_taxonomy_version": "1.0", "classification_start_time": "2022-11-03", "class_id": "20", "class": "Blockchain Infrastructure", "sector_id": "2010", "sector": "Smart Contract Platforms", "subsector_id": "201010", "subsector": "Smart Contract Platforms" } ] } ``` ### Example: screening a class Filtering by `class_ids` returns every asset in that branch of the hierarchy, which is the usual way to build a category universe. Note that `classification_start_time` differs across the rows: each asset carries the date it entered its current classification, not the date the taxonomy version was published. [Run this query](https://api.coinmetrics.io/v4/taxonomy/assets?class_ids=10\&page_size=3\&api_key=YOUR_API_KEY). ```json { "data": [ { "asset": "act", "full_name": "Act I The AI Prophecy", "taxonomy_version": "1.0", "updated_at_taxonomy_version": "1.0", "classification_start_time": "2026-03-26", "class_id": "10", "class": "Digital Currencies", "sector_id": "1020", "sector": "Specialized Coins", "subsector_id": "102010", "subsector": "Meme Coins" }, { "asset": "anime", "full_name": "Animecoin", "taxonomy_version": "1.0", "updated_at_taxonomy_version": "1.0", "classification_start_time": "2026-05-19", "class_id": "10", "class": "Digital Currencies", "sector_id": "1020", "sector": "Specialized Coins", "subsector_id": "102010", "subsector": "Meme Coins" }, { "asset": "arpa", "full_name": "ARPA Chain", "taxonomy_version": "1.0", "updated_at_taxonomy_version": "1.0", "classification_start_time": "2022-11-03", "class_id": "10", "class": "Digital Currencies", "sector_id": "1020", "sector": "Specialized Coins", "subsector_id": "102020", "subsector": "Privacy Coins" } ] } ``` ## Coverage {% embed url="" %} ## Usage The classified universe is the endpoint response itself: querying `/taxonomy/assets` with no filters returns every asset currently classified, which is the authoritative answer to what is covered. 1. **Build a category universe.** Query by `class_ids`, `sector_ids`, or `subsector_ids` to get the asset list for a branch of the hierarchy. 2. **Join to market or network data.** The `asset` field uses standard Coin Metrics asset names, so it joins directly to `/timeseries/asset-metrics`, `/reference-data/markets`, and the rest of the API. 3. **Aggregate by category.** With the classification joined, metrics such as market capitalization or volume can be rolled up by class, sector, or subsector to measure exposure and performance by economic function. For point-in-time analysis, pass `version=*` to retrieve the full revision history and use `classification_start_time` and `classification_end_time` to reconstruct which assets sat in which category on a given date. Without this, backtests inherit the current classification and pick up look-ahead bias. ## Limitations * **One category per asset.** An asset is assigned to exactly one subsector at a time. An asset supporting several use cases is placed in the segment that best represents its dominant usage, or in a segment defined as a platform for varied use cases. The classification is a single label, never a weighting across categories. * **Not a judgment of quality, value, or legitimacy.** The classification says what an asset is used for, nothing more. It is not an endorsement, not a view on an asset's risks or merits, and not investment advice. Categories are deliberately named to avoid terms that carry valuation connotations. * **Not a regulatory classification.** Assets are not classified by regulatory status or standing, so a subsector tells you nothing about how an asset is treated in any jurisdiction. * **Not a technical classification.** Two assets in the same subsector may differ completely in architecture, for example proof of work against proof of stake, or a native chain against a token hosted on another chain. Shared category means shared purpose, not shared design. * **The universe is deliberately narrow.** Only assets meeting the availability thresholds are eligible, so a long tail of thinly traded assets is not classified at all. An asset missing from the response is not necessarily uncategorizable, only ineligible. * **`taxonomy_version` is deprecated.** It is retained for backward compatibility and will be removed. Code reading the version an asset was classified at should use `updated_at_taxonomy_version`. ## FAQ ### How do I get the list of all classes, sectors, and subsectors? Query [Asset Taxonomy Metadata](/reference-data/datonomy-overview/asset-taxonomy-metadata.md) at `/taxonomy-metadata/assets`. It returns the complete hierarchy for a taxonomy version, which is the right way to enumerate the structure rather than deriving it from the assets currently classified. ### What is the difference between `taxonomy_version` and `updated_at_taxonomy_version`? They currently carry the same value, but `taxonomy_version` is obsolete and scheduled for removal. `updated_at_taxonomy_version` is the supported field and records the taxonomy version at which the asset was last classified or reclassified. ### Why does `classification_start_time` differ between assets in the same version? Because it records when that particular asset entered its current classification, not when the taxonomy version was published. An asset added to the universe after the version went live carries its own addition date. ### How do I see an asset's classification history? Pass `version=*`. This returns every revision for the asset, each with its own `classification_start_time` and, where the revision has ended, a `classification_end_time`. ### Why is an asset I track missing? Most likely it has not met the entry threshold, which requires a trade in the past 30 days on at least 25% of eligible exchanges. Assets already classified are held to a lower bar of 10% (minimum two exchanges), so an asset can stay in the taxonomy on coverage that would not have got it in. ### How often do classifications change? There is no fixed schedule. Additions, reclassifications, and removals are reviewed and applied as needed rather than on a rebalance cycle, so changes can land on any date. The structure of classes, sectors, and subsectors is reviewed at least annually, and material changes to it go through a public consultation first. ### Does the classification reflect what a project says it does, or what it is actually used for? It starts from the primary use the protocol's creators describe, but where stated intent differs materially from market perception and observed usage, observed usage takes precedence. ## Related * [datonomy Overview](/reference-data/datonomy-overview.md): what datonomy is, how the hierarchy is structured, and how the pieces fit together. * [Asset Taxonomy Metadata](/reference-data/datonomy-overview/asset-taxonomy-metadata.md): the full class, sector, and subsector structure for a taxonomy version. * [datonomy Methodology](/reference-data/methodologies/datonomy-methodology.md): the published classification methodology. * [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/datonomy-overview/asset-taxonomy.md?ask=&goal= ``` `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.