# Metadata

Metadata endpoints are designed to simplify working with Glassnode data and to facilitate integration with existing systems. Metadata requests do not count towards used API calls; however, they remain subject to the per-account rate limit of 600 requests per minute.

## Assets

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/assets`

Lists all assets and relevant metadata.

The base request returns the complete list of all known assets. With the query parameter, `filter`, the data can also be queried via Common Expression Language (CEL). See [Assets Metadata Usage](https://docs.glassnode.com/basic-api/metadata#assets-metadata-usage) for usage examples and [cel.dev](https://cel.dev/) for more details.

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "data": [
        {
            "id": "USDT",
            "external_ids": {
                "ccdata": "7",
                "coinmarketcap": "825",
                "coingecko": "tether"
            },
            "symbol": "USDT",
            "name": "Tether",
            "asset_type": "TOKEN",
            "blockchains": [
                {
                    "blockchain": "SOL",
                    "address": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
                    "decimals": 6,
                    "on_chain_support": true
                },
                {
                    "blockchain": "ETH",
                    "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
                    "decimals": 6,
                    "on_chain_support": true
                },
                {
                    "blockchain": "TRX",
                    "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
                    "decimals": 6,
                    "on_chain_support": true
                },
                {
                    "blockchain": "TON",
                    "address": "0:b113a994b5024a16719f69139328eb759596c38a25f59028b146fecdc3621dfe",
                    "decimals": 6,
                    "on_chain_support": true
                },
                {
                    "blockchain": "ARB",
                    "address": "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9",
                    "decimals": 18,
                    "on_chain_support": true
                }
            ],
            "logo_url": "https://cdn.glassnode.com/images/crypto-icons/usdt/usdt_small.webp",
            "semantic_tags": [
              "stablecoin"
            ]
        },
        ...
    ]
}
```

{% endtab %}

{% tab title="400 Bad Request - Invalid Argument" %}

```
rpc error: code = InvalidArgument desc = invalid filter: no such attribute(s): doesnotexist
```

{% endtab %}
{% endtabs %}

#### Schema

**Asset**

| Name            | Type              | Description                                                                                                                                                                                                                                                                                                              |
| --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`            | string            | Glassnode ID -- a unique string-based identifier used to specify assets; typically matches with an asset's symbol                                                                                                                                                                                                        |
| `external_ids`  | External IDs      | references to external IDs of third party entities such as CoinMarketCap, Coingecko or CCData                                                                                                                                                                                                                            |
| `symbol`        | string            | asset symbol -- used in Studio when referencing assets                                                                                                                                                                                                                                                                   |
| `name`          | string            | asset name                                                                                                                                                                                                                                                                                                               |
| `asset_type`    | string            | asset type -- one of: BLOCKCHAIN or TOKEN                                                                                                                                                                                                                                                                                |
| `blockchains`   | List\[Blockchain] | list of all token contracts on blockchains supported by Glassnode-- see [Supported Blockchains](https://docs.glassnode.com/data/supported-blockchains) for a full list of supported blockchains                                                                                                                          |
| `logo_url`      | string            | URL of the asset's logo                                                                                                                                                                                                                                                                                                  |
| `semantic_tags` | List\[string]     | list of semantic tags associated with the asset (e.g., "stablecoin", "exchangeToken", "layer1Token", "memeToken", "layer2Token", "aiToken", "nftToken", "depinToken", "tokenizedStock", "rwa", "tokenizedAsset", "stakingGovernanceToken", "stakingToken", "gamingToken", "defiToken", "web3infraToken", "erc20", "spl") |

**Blockchain**

| Name               | Type    | Description                                                        |
| ------------------ | ------- | ------------------------------------------------------------------ |
| `blockchain`       | string  | unique blockchain identifier                                       |
| `address`          | string  | contract address for the asset on the given blockchain             |
| `decimals`         | integer | number of decimals places in the blockchain                        |
| `on_chain_support` | boolean | whether Glassnode offers on-chain metrics for the given blockchain |

**External IDs**

| Name            | Type   | Description      |
| --------------- | ------ | ---------------- |
| `ccdata`        | string | CCData ID        |
| `coinmarketcap` | string | CoinMarketCap ID |
| `coingecko`     | string | CoinGecko ID     |

#### Query Parameters

| Name   | Type   | Description                                       |
| ------ | ------ | ------------------------------------------------- |
| filter | string | CEL (Common Expression Language) compliant filter |

#### Assets Metadata Usage

Examples

Filter asset by id

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/assets?filter=asset.id=='USDT'`

Filter asset with CoinGecko id

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/assets?filter=asset.external_ids.coingecko=='tether'`

Filter assets listed on ETH blockchain

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/assets?filter=asset.blockchains.exists(b,b.blockchain=='ETH')`

Find all supported assets

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/assets?filter=asset.blockchains.exists(b,b.on_chain_support==true)`

Filter assets by semantic tag

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/assets?filter=asset.semantic_tags.exists(tag,tag=='stablecoin')`

## Metrics

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/metrics`

Lists all available metric paths. This should be used as the base list which can then be used to retrieve metadata from the detail view [Metric Metadata](https://docs.glassnode.com/basic-api/metadata#metric).

`Note:` the paths only include the metric portion of the path, and not the full path containing `/v1/metrics`.

{% tabs %}
{% tab title="200 OK" %}

```json
[
    "/addresses/accumulation_balance",
    "/addresses/accumulation_balance_pit",
    "/addresses/accumulation_count",
    "/addresses/accumulation_count_pit",
    "/addresses/active_count",
    "/addresses/count",
    ...
]
```

{% endtab %}
{% endtabs %}

#### Query Parameters

The following query parameters can be used to filter the list of available metrics. Note that these parameters are dynamic and may grow over time. To get the complete list of all available filter parameters, use:

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/metrics?params`

| Name           | Type   | Description                                           |
| -------------- | ------ | ----------------------------------------------------- |
| a              | string | asset id, eg: BTC, ETH                                |
| c              | string | currency for values, eg: native, usd                  |
| e              | string | exchange name, eg: binance, coinbase                  |
| f              | string | response format, eg: json, csv                        |
| i              | string | time interval/resolution, eg: 1h, 24h                 |
| from\_exchange | string | source exchange for inter-exchange metrics            |
| to\_exchange   | string | destination exchange for inter-exchange metrics       |
| miner          | string | miner identifier for mining-related metrics           |
| maturity       | string | maturity period for derivatives metrics               |
| network        | string | network/blockchain identifier for cross-chain metrics |
| period         | string | time period for aggregation                           |
| quote\_symbol  | string | quote currency symbol for trading pairs               |

#### Metrics Metadata Usage

Query parameters examples:

Filter metrics by asset

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/metrics?a=BTC`

Filter metrics by multiple assets

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/metrics?a=BTC&a=ETH`

Filter metrics available for a specific exchange

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/metrics?e=binance`

Filter metrics by asset and exchange

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/metrics?a=BTC&e=coinbase`

Filter metrics available for exchange flow analysis

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/metrics?from_exchange=binance&to_exchange=coinbase`

Filter metrics by time interval

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/metrics?i=1h`

Combine multiple filters

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/metrics?a=BTC&i=1month`

## Metric

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/metric`

Retrieves metadata describing the available parameters and potential drill-down options for a metric.

The base request, where only `path` is queried, returns the union of all possible parameters and their values.

It is possible that certain parameter combinations support different values. The exact set of supported values can be queried by passing them to the metadata request.

See [Metric Metadata Usage](https://docs.glassnode.com/basic-api/metadata#metric-metadata-usage) for a complete example.

#### Schema

| Name          | Type                         | Description                                                                        | Presence       |
| ------------- | ---------------------------- | ---------------------------------------------------------------------------------- | -------------- |
| `path`        | string                       | metric path                                                                        | always         |
| `is_pit`      | boolean                      | indicates if this is a point-in-time metric                                        | when available |
| `parameters`  | Dict\[string, List\[string]] | list of all allowed parameters and their values                                    | always         |
| `queried`     | Dict\[string, string]        | the query which was processed by the server; extraneous values will not be queried | always         |
| `timerange`   | Dict\[string, int]           | the minimum and maximum timerange available for a metric as unix timestamps in UTC |                |
| `modified`    | int                          | the last unix timestamp that the metadata was updated in UTC                       |                |
| `refs`        | Refs                         | links to the metric in studio, its documentation and metric variant                | when available |
| `descriptors` | MetricDescriptors            | detailed information about the metric including name, group, and description       | when available |

**Refs**

| Name             | Type          | Description                                                          | Presence       |
| ---------------- | ------------- | -------------------------------------------------------------------- | -------------- |
| `docs`           | string        | URL to the metric's documentation                                    | when available |
| `studio`         | string        | URL to the metric in Glassnode Studio                                | when available |
| `metric_variant` | MetricVariant | references to related metric variants (e.g., point-in-time versions) | when available |

**MetricVariant**

| Name   | Type   | Description                                     | Presence       |
| ------ | ------ | ----------------------------------------------- | -------------- |
| `base` | string | path to the base version of the metric          | when available |
| `bulk` | string | path to the bulk version of the metric          | when available |
| `pit`  | string | path to the point-in-time version of the metric | when available |

**MetricDescriptors**

| Name          | Type                  | Description                                                                                                                        | Presence       |
| ------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `name`        | string                | full metric name                                                                                                                   | when available |
| `short_name`  | string                | short metric name                                                                                                                  | when available |
| `group`       | string                | metric category or group                                                                                                           | when available |
| `tags`        | List\[string]         | list of tags associated with the metric, possible value is one of the following: on-chain, spot, futures, indicators, options, etf | when available |
| `description` | Dict\[string, string] | detailed descriptions of the metric, where the possible keys are default, use\_case and technical                                  | when available |

#### Query Parameters

The `path` parameter is required. All other parameters are optional and can be used to refine the metadata query. Each metric can support a different set of parameters - the available parameters and their valid values for a specific metric are returned in the `parameters` field of the response when querying with `?path=`.

| Name                                   | Type   | Description                                           |
| -------------------------------------- | ------ | ----------------------------------------------------- |
| path<mark style="color:red;">\*</mark> | string | metric path, eg: /addresses/count                     |
| a                                      | string | asset id, eg: BTC, ETH                                |
| c                                      | string | currency for values, eg: native, usd                  |
| e                                      | string | exchange name, eg: binance, coinbase                  |
| f                                      | string | response format, eg: json, csv                        |
| i                                      | string | time interval/resolution, eg: 1h, 24h                 |
| from\_exchange                         | string | source exchange for inter-exchange metrics            |
| to\_exchange                           | string | destination exchange for inter-exchange metrics       |
| miner                                  | string | miner identifier for mining-related metrics           |
| maturity                               | string | maturity period for derivatives metrics               |
| network                                | string | network/blockchain identifier for cross-chain metrics |
| period                                 | string | time period for aggregation                           |
| quote\_symbol                          | string | quote currency symbol for trading pairs               |

{% tabs %}
{% tab title="200 OK" %}

```json
{
  "path": "/distribution/balance_exchanges",
  "tier": 2,
  "parameters": {
    "a": [
      "1INCH",
      "AAVE",
      "ABT",
      ...
    ],
    "e": [
      "aggregated",
      "bibox",
      "bigone",
      "binance",
      ...
    ],
    "f": [
      "csv",
      "json"
    ],
    "i": [
      "10m",
      "1h",
      "24h"
    ]
  },
  "queried": {
    "path": "/distribution/balance_exchanges"
  },
  "refs": {
    "docs": "https://docs.glassnode.com/basic-api/endpoints/distribution#distribution.balanceexchanges",
    "studio": "https://studio.glassnode.com/charts/distribution.BalanceExchanges",
    "metric_variant": {
      "bulk": "/distribution/balance_exchanges/bulk",
      "pit": "/distribution/balance_exchanges_pit"
    }
  },
  "timerange": {
    "min": 1313591400,
    "max": 1752481200
  },
  "modified": 1730993909,
  "descriptors": {
    "name": "Balance on Exchanges (Total)",
    "short_name": "Exchange Balance (Total)",
    "group": "Exchange Balances",
    "tags": [
      "on-chain"
    ],
    "description": {
      "default": "The total amount of coins held on exchange addresses. Note that exchange metrics are based on our labeled data of exchange addresses that we constantly keep updating, as well as data science techniques and statistical information that changes over time. Therefore these metrics are mutable – the data is stable, but especially most recent data points are subject to slight fluctuations as time progresses."
    }
  }
}
```

{% endtab %}

{% tab title="400 Bad Request - Required Parameter Not Set" %}

```
required parameter not set: path
```

{% endtab %}

{% tab title="400 Bad Request - Invalid Query" %}

```
invalid query parameter: invalid value a=invalid_asset value must be one of [BTC ETH]
```

{% endtab %}

{% tab title="404 Not Found" %}

```
metadata not found: path=/distribution/does_not_exist
```

{% endtab %}
{% endtabs %}

#### Metric Metadata Usage

Request metadata for metric:

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/metric?path=/distribution/balance_exchanges`

```json
{
  "path": "/distribution/balance_exchanges",
  "tier": 2,
  "parameters": {
    "a": [
      "1INCH",
      "AAVE",
      "ABT",
      ...
    ],
    "e": [
      "aggregated",
      "bibox",
      "bigone",
      "binance",
      ...
    ],
    "f": [
      "csv",
      "json"
    ],
    "i": [
      "10m",
      "1h",
      "24h"
    ]
  },
  "queried": {
    "path": "/distribution/balance_exchanges"
  },
  "refs": {
    "docs": "https://docs.glassnode.com/basic-api/endpoints/distribution#distribution.balanceexchanges",
    "studio": "https://studio.glassnode.com/charts/distribution.BalanceExchanges",
    "metric_variant": {
      "bulk": "/distribution/balance_exchanges/bulk",
      "pit": "/distribution/balance_exchanges_pit"
    }
  },
  "timerange": {
    "min": 1313591400,
    "max": 1752481200
  },
  "modified": 1730993909
}
```

Add the asset `a` parameter to the query with a value from the response to refine the query further. Adding additional parameters to the query will further narrow down supported parameter values.

<mark style="color:blue;">`GET`</mark> `https://api.glassnode.com/v1/metadata/metric?path=/distribution/balance_exchanges&a=BTC`

```json
{
  "path": "/distribution/balance_exchanges",
  "tier": 2,
  "parameters": {
    "c": [
      "native",
      "usd"
    ],
    "e": [
      "aggregated",
      "binance",
      "bitfinex",
      "bitget",
      "bithumb",
      "bitmex",
      "bitstamp",
      "bittrex",
      "bybit",
      "coinbase",
      "coincheck",
      "coinex",
      "crypto.com",
      "deribit",
      "ftx",
      "gate.io",
      "gemini",
      "hitbtc",
      "huobi",
      "korbit",
      "kraken",
      "kucoin",
      "luno",
      "okex",
      "poloniex",
      "swissborg"
    ],
    "f": [
      "csv",
      "json"
    ],
    "i": [
      "10m",
      "1h",
      "24h"
    ]
  },
  "queried": {
    "a": "BTC",
    "path": "/distribution/balance_exchanges"
  },
  "refs": {
    "docs": "https://docs.glassnode.com/basic-api/endpoints/distribution#distribution.balanceexchanges",
    "studio": "https://studio.glassnode.com/charts/distribution.BalanceExchanges",
    "metric_variant": {
      "bulk": "/distribution/balance_exchanges/bulk",
      "pit": "/distribution/balance_exchanges_pit"
    }
  },
  "timerange": {
    "min": 1313591400,
    "max": 1752481200
  },
  "modified": 1733829848
}
```

The result displays the set of valid parameters and their values given the query:

```json
{
  "a": "BTC",
  "path": "/distribution/balance_exchanges"
}
```