Bulk metrics

Bulk endpoints are a specialized extension of our classical metric endpoints, designed for scenarios where fetching data for multiple assets or parameter combinations in a single request is essential. While our classical endpoints are ideal for most use cases, fetching data systematically for a large number of assets or combinations will require an impractical number of API calls. Bulk endpoints address this need by providing metric values for all parameter combinations (some parameters excepted, see request format section) in a single response, accessible under /v1/metrics/<metric path>/bulk.

To find out if a metric has a bulk variant, view the bulk_supported response field from the metadata/metric endpoint (set path query parameter to the regular metric's path).

Bulk Endpoints and API Credits

Please note that bulk endpoints consume more API credits than usual API calls. Each request to a bulk endpoint will cost as many API credits as the individual calls to the API would have. For instance, calling the /v1/metrics/market/mvrv/bulk endpoint with 5 assets will consume 5 API credits. This also applies to parameters such as network and exchanges. If for instance a bulk request has 5 assets and 5 exchanges then this will consume 25 API credits (1 for each combination's metric value).

We therefore recommend always specifying parameters like assets (a), exchanges (e), and networks (network) to control the credits used. Available assets and networks per endpoint can be found in the API documentation or the Metadata endpoints. The history of data does not incur additional credits but is limited by default depending on the resolution (i).

Request format

Bulk metric requests support the same parameters as the regular metric. However, the semantics of parameters are different besides the following set of unchanged parameters:

• since parameter s

• until parameter u

• resolution parameter i (defaults to 24h)

• currency parameter c (defaults to NATIVE)

• format parameter f (defaults to json, note: for now only JSON responses are supported)

Remaining parameters can be set to multiple values by specifying the parameter multiple times in the query parameters. For example/v1/metrics/addresses/active?a=BTC&a=ETH applies the [BTC, ETH] whitelist to a, resulting in a response with bulk entries filtered on either of these assets.\

All values can be requested by setting a wildcard (*) as the parameter filter value, eg. a=*.

If no filter is set for a parameter then its respective default value will be applied—mimicking the behavior of the non-bulk metric variant.

To view what parameters are supported and what values these may be filtered on, view the metadata/metric endpoint with path set to the regular metric's path.

Response format

Bulk metric responses contain the values for every parameter combination at each timestamp in the timeseries. To accommodate this the response format replaces the v and o components of the regular metric's response with a bulk component. If the regular metric is of v response format, bulk is of the following format:[{<parameter_i>: <parameter_value_i>, "v": <value>}]. If the regular metric is of o response format, bulk is of the following format:[{<parameter_i>: <parameter_value_i>, "category": <o_key>, "v": <o_value>}].

Aggregations are not excluded and special aggregated values of <parameter_value_i> and <o_key> are included by default.\

Bulk timeseries are placed under a root level data key, to reserve space for any possible metadata we may add to the response in a later release.

Response example: v metric

If a metric with v response format has parameters:

• asset parameter a

• exchange parameter e

then the bulk metric variant will have the following response format (with example values):

{
    'data': [{
        't': 1738657600,
        'bulk': [{
            'a': 'BTC',
            'e': 'bitfinex',
            'v': 123
        },
        {
            'a': 'BTC',
            'e': 'binance',
            'v': 12
        },
        {
            'a': 'ETH',
            'e': 'bitfinex',
            'v': 456
        }]
    }]
}

Response example: o metric

If a metric with o response format has parameters:

• asset parameter a

And has following keys in the o response:

• 1d_1w

• more_10y

Then the bulk metric variant will have the following response format (with example values):

{
    'data': [{
        't': 1738657600,
        'bulk': [{
            'a': 'BTC',
            'category': '1d_1w',
            'v': 123
        },
        {
            'a': 'BTC',
            'category': 'more_10y',
            'v': 12
        },
        {
            'a': 'ETH',
            'category': '1d_1w',
            'v': 45
        },
        {
            'a': 'ETH',
            'category': 'more_10y',
            'v': 456
        }]
    }]
}

Timerange constraints

The maximum queryable timerange within 1 bulk request is restricted:

• for 10m and 1h resolutions: 10 days

• for 1d resolution: 31 days

• for 1w and 1month resolutions: 93 days

Closing remarks

• There are a few metrics where missing values are not filled in the bulk response (even though the regular metric does apply a fill), this is intentional as otherwise the bulk response size for these few metrics would become excessively large with a majority of datapoints representing filled missing values.