Bulk metrics (beta)

Disclaimer: Bulk endpoints are in beta release status, which means that we may introduce breaking changes at any time.

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 in a single response, accessible under <regular metric endpoint>/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 /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 (n) 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)

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

Remaining parameters are optional whitelists. Unlike the regular metric they 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. If not set, no filter is applied and all values of the parameter are included in the response. 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 expected to be computed client-side, therefore the special aggregated values of <parameter_value_i> and <o_key> are by default excluded. If you do want aggregated results it has to be explicitely enabled by including it into the whitelist for the parameter in the query parameters (eg: .../bulk?e=aggregated).

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 we dont fill missing values in the bulk response (even though we do do that in the regular metric), this is intentional as otherwise the bulk response size for these few metrics would become excessively large with majority of datapoints representing filled missing values.