TOtokenterminal
Assets

Get asset metrics breakdown

Changed on

Use this endpoint to retrieve aggregated breakdown data for asset metrics across different dimensions (projects, chains, market sectors, etc.).

If an empty metric_ids array is provided, it defaults to ['asset_price'].

post/v2/assets/{asset_id}/metrics-breakdown

Request

  • Base URL
    https://api.tokenterminal.com
  • Auth
    HTTP bearer

Path parameters

asset_idstring required

ID of the asset

Allows you to select one of the assets available.

The full list is available on the assets endpoint (see above).

Request body

metric_idsstring[] required

List of metrics to include according to asset metric availability.

Allows you to select one or more of the metrics available for a specific asset.

If an empty array is provided, it defaults to ['asset_price'].

group_by'assets' | 'projects' | 'product' | 'chains' | 'market-sector' | 'reference-asset' | 'chain-asset' | 'chain-project' | 'product+chain' | 'venue' | 'asset+venue' | 'venue+chain' | 'market-sector+venue' required

Dimension to group the breakdown by.

Available options: assets, projects, product, chains, market-sector, reference-asset, chain-asset, chain-project, product+chain, venue, asset+venue, venue+chain, market-sector+venue.

reference-asset groups by the price reference the underlying assets track (for example Credit fund, S&P 500), and returns a reference_asset label on each row. Assets that track no reference asset are excluded from that breakdown.

The venue composites (asset+venue, venue+chain, market-sector+venue) combine venue with a second dimension and are only meaningful for the venue-scoped metrics (asset_tvl, asset_trading_volume, asset_notional_trading_volume).

interval'24h' | '7d' | '30d' | '90d' | '180d' | '365d' | '1095d' | '1825d' | 'ytd' | 'max'

Length of the aggregation window. Defaults to 7d. The window ends at the latest available date, or the day before end if given.

Ignored when both start and end are given; the window is then the date range [start, end).

data_idsstring[]

List of project data IDs to filter by.

Allows you to select one or more projects. When including multiple projects, separate each one with a comma.

product_idsstring[]

List of product IDs to filter by.

Allows you to select one or more products. When including multiple products, separate each one with a comma.

asset_idsstring[]

List of asset IDs to filter by.

Allows you to select one or more assets. When including multiple assets, separate each one with a comma.

chain_idsstring[]

List of chain IDs to filter by.

Allows you to select one or more chains. When including multiple chains, separate each one with a comma.

market_sector_idsstring[]

List of market sector IDs to filter by.

Allows you to select one or more market sectors. When including multiple market sectors, separate each one with a comma.

The full list of available market sectors can be retrieved from the /v2/market-sectors endpoint.

reference_asset_idsstring[]

List of reference asset IDs to filter by (for example creditfund, sp500).

The filter counterpart of group_by: reference-asset: use it to restrict the breakdown to assets tracking a specific price reference. Assets that track no reference asset are excluded.

The full list of available reference assets can be retrieved from the /v2/reference-assets endpoint.

includeSelfboolean

Include the asset itself in the breakdown results.

If not specified, defaults to false.

startstring date

First date of the aggregation window, inclusive (YYYY-MM-DD).

With end, the window is the half-open range [start, end) and interval is ignored. Without end, the window spans interval days starting on start.

endstring date

End of the aggregation window, exclusive (YYYY-MM-DD). Data for this date is not included; must be after start, otherwise the request is rejected with a 400.

For a full calendar month use the first day of the next month, e.g. start=2026-08-01, end=2026-09-01. Without start, the window spans interval days ending the day before end. If omitted entirely, the window ends at the latest date for which data is available. If the day before end has no data yet, the window ends at the latest available date before it.

ignore_thresholdboolean

Ignore metric thresholds when calculating breakdowns.

If not specified, defaults to false.

Example request

{
  "metric_ids": [
    "asset_price",
    "asset_holders"
  ],
  "group_by": "assets",
  "interval": "30d",
  "data_ids": [
    "ethereum"
  ],
  "product_ids": [
    "usdc"
  ],
  "chain_ids": [
    "ethereum",
    "base"
  ],
  "market_sector_ids": [
    "blockchains-l1",
    "lending"
  ],
  "reference_asset_ids": [
    "creditfund"
  ],
  "venues": [
    {
      "data_id": "aave",
      "product_id": "aavev3"
    }
  ]
}

Response

OK

Example response

{
  "errors": [
    {
      "code": "NOT_FOUND",
      "field": "project_ids",
      "value": "invalid-project"
    }
  ]
}

Changes

  • b8a5000df3e2Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new asset+venue enum value to the request property

    • info

      added the new market-sector+venue enum value to the request property

    • info

      added the new reference-asset enum value to the request property

    • info

      added the new venue enum value to the request property

    • info

      added the new venue+chain enum value to the request property

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

  • 4cf6f1da3bf9Revision changes
    • info

      the request property became optional

    • info

      the request property default value 7d was added

    • info

      added the new 1095d enum value to the request property

    • info

      added the new 1825d enum value to the request property

    • info

      added the new ytd enum value to the request property