Liquidation Metrics

The reported liquidation metrics are a sum of all reported volume in native units or U.S. Dollars of buy or sell orders that were used to close short positions under liquidation for a specific market in our coverage universe.

Metrics

Name	MetricID	Unit	Interval
Reported Liquidation Buy Orders (Units), 5 Min	liquidations_reported_future_buy_units_5m	Native Units	5m
Reported Liquidation Buy Orders (Units), 1 Hour	liquidations_reported_future_buy_units_1h	Native Units	1h
Reported Liquidation Buy Orders (Units), 1 Day	liquidations_reported_future_buy_units_1d	Native Units	1d
Reported Liquidation Buy Orders (USD), 5 Min	liquidations_reported_future_buy_usd_5m	USD	5m
Reported Liquidation Buy Orders (USD), 1 Hour	liquidations_reported_future_buy_usd_1h	USD	1h
Reported Liquidation Buy Orders (USD), 1 Day	liquidations_reported_future_buy_usd_1d	USD	1d
Reported Liquidation Sell Orders (Units), 5 Min	liquidations_reported_future_sell_units_5m	Native Units	5m
Reported Liquidation Sell Orders (Units), 1 Hour	liquidations_reported_future_sell_units_1h	Native Units	1h
Reported Liquidation Sell Orders (Units), 1 Day	liquidations_reported_future_sell_units_1d	Native Units	1d
Reported Liquidation Sell Orders (USD), 5 Min	liquidations_reported_future_sell_usd_5m	USD	5m
Reported Liquidation Sell Orders (USD), 1 Hour	liquidations_reported_future_sell_usd_1h	USD	1h
Reported Liquidation Sell Orders (USD), 1 Day	liquidations_reported_future_sell_usd_1d	USD	1d

API Endpoints

Liquidation metrics can be accessed using these endpoints:

• timeseries/exchange-metrics

• timeseries/exchange-asset-metrics

• timeseries/pair-metrics

and by passing in the liquidation_reported_* metrics in the metrics parameter.

Exchange metrics

get

Returns metrics for specified exchanges. Results are ordered by tuple (exchange, time). To fetch the next page of results use next_page_url JSON response field.

Authorizations

Query parameters

exchangesstring[]Required

Comma separated list of exchange names or asterisk (*) for all supported exchanges.

Example: {"summary":"the list of exchanges","value":"coinbase,binance,etc"}

metricsstring[]Required

Comma separated metrics to request time series data for. Information on all available metrics can be found on page https://coverage.coinmetrics.io/exchange-metrics-v2. Use the /catalog-all/exchange endpoint for the full list of supported metrics per exchange.

Example: ["open_interest_reported_future_usd","volume_reported_spot_usd_1d"]

frequencystringOptional

Frequency of the exchange metrics. Supported values are 1h, 1d.

Default: 1d

start_timestringOptional

Start of the time interval. This field refers to the time field in the response. Multiple formats of ISO 8601 are supported: 2006-01-20T00:00:00Z, 2006-01-20T00:00:00.000Z, 2006-01-20T00:00:00.123456Z, 2006-01-20T00:00:00.123456789Z, 2006-01-20, 20060120. Inclusive by default. UTC timezone by default. Z suffix is optional and timezone parameter has a priority over it. If start_time is omitted, response will include time series from the earliest time available.

end_timestringOptional

End of the time interval. This field refers to the time field in the response. Multiple formats of ISO 8601 are supported: 2006-01-20T00:00:00Z, 2006-01-20T00:00:00.000Z, 2006-01-20T00:00:00.123456Z, 2006-01-20T00:00:00.123456789Z, 2006-01-20, 20060120. Inclusive by default. UTC timezone by default. Z suffix is optional and timezone parameter has a priority over it. If end_time is omitted, response will include time series up to the latest time available.

start_inclusivebooleanOptional

Inclusive or exclusive corresponding start_* parameters.

Default: true

end_inclusivebooleanOptional

Inclusive or exclusive corresponding end_* parameters.

Default: true

timezonestringOptional

Timezone name for start_time and end_time timestamps. This parameter does not modify the output times, which are always UTC. Format is defined by TZ database.

Default: UTCExample: America/New_York

page_sizeinteger · int32 · min: 1 · max: 10000Optional

Number of items per single page of results. The value of this parameter is ignored if the endpoint supports the format parameter and its value is set to json_stream.

Default: 100

paging_fromstring · enumOptional

Where does the first page start, at the start of the interval or at the end. The value of this parameter is ignored if the endpoint supports the format parameter and its value is set to json_stream.

Default: endPossible values:

sortstring · enumOptional

How results will be sorted. Metrics are sorted by (exchange, time) by default. If you want to sort 1d metrics by (time, exchange) you should choose time as value for the sort parameter. Sorting by time is useful if you request metrics for a set of exchanges.

Default: exchangePossible values:

limit_per_exchangeinteger · int32Optional

How many entries per institution result should contain. For example, this combination of parameters exchanges=binance,coinbase&metrics=volume_trusted_spot_usd_1h&limit_per_exchange=1 returns the latest volume_trusted_spot_usd_1h values for binance and coinbase.

prettybooleanOptional

Human-readable formatting of JSON responses.

Default: false

formatstring · enumOptional

Format of the response.

Default: jsonPossible values:

next_page_tokenstringOptional

Token for receiving the results from the next page of a query. Should not be used directly. To iterate through pages just use next_page_url response field.

Responses

200

Time series of exchange metrics.

application/json

400

Exchange not found.

application/json

401

Requested resource requires authorization.

application/json

403

Requested resource is not available with supplied credentials.

application/json

414

Provided URI is too long. It must not be greater than 10000 symbols.

get

HTTPcURLJavaScriptPython

GET /v4/timeseries/exchange-metrics HTTP/1.1
Host: api.coinmetrics.io
Accept: */*

{
  "data": [
    {
      "exchange": "binance",
      "time": "2022-01-01T00:00:00.000000000Z",
      "volume_reported_spot_usd_1d": "8988114373.91716"
    },
    {
      "exchange": "binance",
      "time": "2022-01-02T00:00:00.000000000Z",
      "volume_reported_spot_usd_1d": "9686610104.12659"
    },
    {
      "exchange": "binance",
      "time": "2022-01-03T00:00:00.000000000Z",
      "volume_reported_spot_usd_1d": "13513437237.6032"
    },
    {
      "exchange": "binance",
      "time": "2022-01-04T00:00:00.000000000Z",
      "volume_reported_spot_usd_1d": "15006844836.1782"
    }
  ]
}

Shell

curl --compressed "https://api.coinmetrics.io/v4/timeseries/exchange-metrics?exchanges=binance&metrics=liquidations_reported_future_sell_usd_1d&limit_per_exchange=1&api_key=<your_key>"

Python

import requests
response = requests.get('https://api.coinmetrics.io/v4/timeseries/exchange-metrics?exchanges=binance&metrics=liquidations_reported_future_sell_usd_1d&limit_per_exchange=1&api_key=<your_key>
print(response)

Python Client

from coinmetrics.api_client import CoinMetricsClient

api_key = "<API_KEY>"
client = CoinMetricsClient(api_key)

print(
    client.get_exchange_metrics(
        exchanges=["binance"], metrics=['liquidations_reported_future_sell_usd_1d'], frequency='1d', limit_per_market=1
    ).to_dataframe()
)

Exchange-asset metrics

get

Returns metrics for specified exchange-asset. Results are ordered by tuple (exchange_asset, time). To fetch the next page of results use next_page_url JSON response field.

Authorizations

Query parameters

exchange_assetsstring[]Required

Comma separated list of exchange-asset pairs or patterns like exchange-* or *-asset.

metricsstring[]Required

Comma separated metrics to request time series data for. Information on all available metrics can be found on page https://coverage.coinmetrics.io/exchange-asset-metrics-v2. Use the /catalog-all/exchange-assets endpoint for the full list of supported metrics per exchange-asset combination.

Example: ["open_interest_reported_future_usd","volume_reported_spot_usd_1d"]

frequencystringOptional

Frequency of the exchange-asset metrics. Supported values are 5m, 1h, 1d.

Default: 1d

start_timestringOptional

Start of the time interval. This field refers to the time field in the response. Multiple formats of ISO 8601 are supported: 2006-01-20T00:00:00Z, 2006-01-20T00:00:00.000Z, 2006-01-20T00:00:00.123456Z, 2006-01-20T00:00:00.123456789Z, 2006-01-20, 20060120. Inclusive by default. UTC timezone by default. Z suffix is optional and timezone parameter has a priority over it. If start_time is omitted, response will include time series from the earliest time available.

end_timestringOptional

End of the time interval. This field refers to the time field in the response. Multiple formats of ISO 8601 are supported: 2006-01-20T00:00:00Z, 2006-01-20T00:00:00.000Z, 2006-01-20T00:00:00.123456Z, 2006-01-20T00:00:00.123456789Z, 2006-01-20, 20060120. Inclusive by default. UTC timezone by default. Z suffix is optional and timezone parameter has a priority over it. If end_time is omitted, response will include time series up to the latest time available.

start_inclusivebooleanOptional

Inclusive or exclusive corresponding start_* parameters.

Default: true

end_inclusivebooleanOptional

Inclusive or exclusive corresponding end_* parameters.

Default: true

timezonestringOptional

Timezone name for start_time and end_time timestamps. This parameter does not modify the output times, which are always UTC. Format is defined by TZ database.

Default: UTCExample: America/New_York

page_sizeinteger · int32 · min: 1 · max: 10000Optional

Number of items per single page of results. The value of this parameter is ignored if the endpoint supports the format parameter and its value is set to json_stream.

Default: 100

paging_fromstring · enumOptional

Where does the first page start, at the start of the interval or at the end. The value of this parameter is ignored if the endpoint supports the format parameter and its value is set to json_stream.

Default: endPossible values:

sortstring · enumOptional

How results will be sorted. Metrics are sorted by (exchange_asset, time) by default. If you want to sort 1d metrics by (time, exchange_asset) you should choose time as value for the sort parameter. Sorting by time is useful if you request metrics for a set of exchange-assets.

Default: exchange_assetPossible values:

limit_per_exchange_assetinteger · int32Optional

How many entries per exchange_asset result should contain. For example, this combination of parameters exchange_assets=binance-btc,coinbase-eth&metrics=volume_trusted_spot_usd_1h&limit_per_exchange_asset=1 returns the latest volume_trusted_spot_usd_1h values for binance-btc and coinbase-eth.

prettybooleanOptional

Human-readable formatting of JSON responses.

Default: false

formatstring · enumOptional

Format of the response.

Default: jsonPossible values:

next_page_tokenstringOptional

Token for receiving the results from the next page of a query. Should not be used directly. To iterate through pages just use next_page_url response field.

Responses

200

Time series of exchange-asset metrics.

application/json

400

Exchange-asset pair not found.

application/json

401

Requested resource requires authorization.

application/json

403

Requested resource is not available with supplied credentials.

application/json

414

Provided URI is too long. It must not be greater than 10000 symbols.

get

HTTPcURLJavaScriptPython

GET /v4/timeseries/exchange-asset-metrics HTTP/1.1
Host: api.coinmetrics.io
Accept: */*

{
  "data": [
    {
      "exchange_asset": "binance-btc",
      "time": "2021-10-04T00:00:00.000000000Z",
      "open_interest_reported_future_usd": "3469621227.0258"
    },
    {
      "exchange_asset": "binance-btc",
      "time": "2021-10-05T00:00:00.000000000Z",
      "open_interest_reported_future_usd": "3562791590.02995"
    },
    {
      "exchange_asset": "binance-btc",
      "time": "2021-10-06T00:00:00.000000000Z",
      "open_interest_reported_future_usd": "3970248573.60142"
    },
    {
      "exchange_asset": "binance-btc",
      "time": "2021-10-07T00:00:00.000000000Z",
      "open_interest_reported_future_usd": "4110308192.96416"
    }
  ]
}

Shell

curl --compressed "https://api.coinmetrics.io/v4/timeseries/exchange-asset-metrics?exchange_assets=binance-btc&metrics=liquidations_reported_future_sell_usd_1d&limit_per_exchange_asset=1&api_key=<your_key>"

Python

import requests
response = requests.get('https://api.coinmetrics.io/v4/timeseries/exchange-asset-metrics?exchange_assets=binance-btc&metrics=liquidations_reported_future_sell_usd_1d&limit_per_exchange_asset=1&api_key=<your_key>
print(response)

Python Client

from coinmetrics.api_client import CoinMetricsClient

api_key = "<API_KEY>"
client = CoinMetricsClient(api_key)

print(
    client.get_exchange_asset_metrics(
        exchanges=["binance-btc"], metrics=['liquidations_reported_future_sell_usd_1d'], frequency='1d', limit_per_market=1
    ).to_dataframe()
)

Pair metrics

get

Returns metrics for specified asset pairs. Results are ordered by tuple (pair, time). To fetch the next page of results use next_page_url JSON response field.

Authorizations

Query parameters

pairsstring[]Required

Comma separated list of asset pairs or patterns like btc-*, or *-btc. Use the /catalog-all/pairs endpoint for the full list of supported asset pairs.

metricsstring[]Required

Comma separated metrics to request time series data for. Information on all available metrics can be found on page https://coverage.coinmetrics.io/pair-metrics-v2. Use the /catalog-all/pairs endpoint for the full list of supported metrics per pair.

Example: ["volume_trusted_spot_usd_1h","volume_trusted_spot_usd_1d"]

frequencystringOptional

Frequency of the pair metrics. Supported values are 1h, 1d.

Default: 1d

start_timestringOptional

Start of the time interval. This field refers to the time field in the response. Multiple formats of ISO 8601 are supported: 2006-01-20T00:00:00Z, 2006-01-20T00:00:00.000Z, 2006-01-20T00:00:00.123456Z, 2006-01-20T00:00:00.123456789Z, 2006-01-20, 20060120. Inclusive by default. UTC timezone by default. Z suffix is optional and timezone parameter has a priority over it. If start_time is omitted, response will include time series from the earliest time available.

end_timestringOptional

End of the time interval. This field refers to the time field in the response. Multiple formats of ISO 8601 are supported: 2006-01-20T00:00:00Z, 2006-01-20T00:00:00.000Z, 2006-01-20T00:00:00.123456Z, 2006-01-20T00:00:00.123456789Z, 2006-01-20, 20060120. Inclusive by default. UTC timezone by default. Z suffix is optional and timezone parameter has a priority over it. If end_time is omitted, response will include time series up to the latest time available.

start_inclusivebooleanOptional

Inclusive or exclusive corresponding start_* parameters.

Default: true

end_inclusivebooleanOptional

Inclusive or exclusive corresponding end_* parameters.

Default: true

timezonestringOptional

Timezone name for start_time and end_time timestamps. This parameter does not modify the output times, which are always UTC. Format is defined by TZ database.

Default: UTCExample: America/New_York

page_sizeinteger · int32 · min: 1 · max: 10000Optional

Number of items per single page of results. The value of this parameter is ignored if the endpoint supports the format parameter and its value is set to json_stream.

Default: 100

paging_fromstring · enumOptional

Where does the first page start, at the start of the interval or at the end. The value of this parameter is ignored if the endpoint supports the format parameter and its value is set to json_stream.

Default: endPossible values:

sortstring · enumOptional

How results will be sorted. Metrics are sorted by (pair, time) by default. If you want to sort 1d metrics by (time, pair) you should choose time as value for the sort parameter. Sorting by time is useful if you request metrics for a set of asset pairs.

Default: pairPossible values:

limit_per_pairinteger · int32Optional

How many entries per pair result should contain. For example, this combination of parameters pair=btc-usd,eth-usd&metrics=volume_trusted_spot_usd_1h&limit_per_pair=1 returns the latest volume_trusted_spot_usd_1h values for btc-usd and eth-usd.

prettybooleanOptional

Human-readable formatting of JSON responses.

Default: false

formatstring · enumOptional

Format of the response.

Default: jsonPossible values:

next_page_tokenstringOptional

Token for receiving the results from the next page of a query. Should not be used directly. To iterate through pages just use next_page_url response field.

Responses

200

Time series of pair metrics.

application/json

400

Pair not found.

application/json

401

Requested resource requires authorization.

application/json

403

Requested resource is not available with supplied credentials.

application/json

414

Provided URI is too long. It must not be greater than 10000 symbols.

get

HTTPcURLJavaScriptPython

GET /v4/timeseries/pair-metrics HTTP/1.1
Host: api.coinmetrics.io
Accept: */*

{
  "data": [
    {
      "pair": "btc-usd",
      "time": "2020-09-28T00:00:00.000000000Z",
      "volume_trusted_spot_usd_1d": "317000178.776577"
    },
    {
      "pair": "btc-usd",
      "time": "2020-09-29T00:00:00.000000000Z",
      "volume_trusted_spot_usd_1d": "246153685.485477"
    },
    {
      "pair": "btc-usd",
      "time": "2020-09-30T00:00:00.000000000Z",
      "volume_trusted_spot_usd_1d": "217972373.240482"
    },
    {
      "pair": "btc-usd",
      "time": "2020-10-01T00:00:00.000000000Z",
      "volume_trusted_spot_usd_1d": "492203699.871197"
    }
  ]
}

Shell

curl --compressed "https://api.coinmetrics.io/v4/timeseries/pair-metrics?pairs=btc-usd&metrics=liquidations_reported_future_sell_usd_1d&limit_per_pair=1&api_key=<your_key>"

Python

import requests
response = requests.get('https://api.coinmetrics.io/v4/timeseries/pair-metrics?pairs=btc-usd&metrics=liquidations_reported_future_sell_usd_1d&limit_per_pair=1&api_key=<your_key>
print(response)

Python Client

from coinmetrics.api_client import CoinMetricsClient

api_key = "<API_KEY>"
client = CoinMetricsClient(api_key)

print(
    client.get_pair_metrics(
        pairs=["btc-usd"], metrics=['liquidations_reported_future_sell_usd_1d'], frequency='1d', limit_per_market=1
    ).to_dataframe()
)

Details

Our reported liquidations metric is an aggregation of the reported liquidations from an exchange.

Examples

A sample of the daily reported liquidation buy orders for the Binance BTCUSDT futures market is shown below:

market	time	liquidations_reported_future_buy_units_1d
binance-BTCUSDT-future	2022-01-01 00:00:00	84.918
binance-BTCUSDT-future	2022-01-02 00:00:00	80.595
binance-BTCUSDT-future	2022-01-03 00:00:00	74.007
binance-BTCUSDT-future	2022-01-04 00:00:00	109.399

• market. The IDs of the markets.

• time. The time in ISO 8601 date-time format.

• liquidations_reported_future_buy_units_1d. The reported volume of liquidation buy orders in native units.

Release History

• Release Version. Market Data Feed 2.6 (July 2022)