drift/utils/glassnode/entities.py

from .utils import *
from .client import GlassnodeClient


class Entities:
    """
        Entities class.

        Methods
        -------
        __init__(glassnode_client):
            Constructs a Entities object.
        sending_entities():
            Returns the number of unique entities that were active as a sender.
        receiving_entities():
            Returns the number of unique entities that were active as a receiver.
        active_entities():
            Returns the number of unique entities that were active either as a sender or receiver.
        new_entities():
            Returns The number of unique entities that appeared for the first time in a transaction.
        entities_net_growth():
            Returns the net growth of unique entities in the network.
        number_of_whales():
            Returns the number of unique entities holding at least 1k coins.
        supply_balance_less_0001():
            Returns the total circulating supply held by entities with a balance lower than 0.001 coins.
        supply_balance_0001_001():
            Returns the total circulating supply held by entities with a balance between 0.001 and 0.01 coins.
        supply_balance_001_01():
            Returns the total circulating supply held by entities with a balance between 0.01 and 0.1 coins.
        supply_balance_01_1():
            Returns the total circulating supply held by entities with a balance between 0.1 and 1 coins.
        supply_balance_1_10():
            Returns the total circulating supply held by entities with a balance between 1 and 10 coins.
        supply_balance_10_100():
            Returns the total circulating supply held by entities with a balance between 10 and 100 coins.
        supply_balance_100_1k():
            Returns the total circulating supply held by entities with a balance between 100 and 1,000 coins.
        supply_balance_1k_10k():
            Returns the total circulating supply held by entities with a balance between 1,000 and 10,000 coins.
        supply_balance_10k_100k():
            Returns the total circulating supply held by entities with a balance between 10,000 and 100,000 coins.
        supply_balance_more_100k():
            Returns the total circulating supply held by entities with a balance of at least 100,000 coins.
        entities_supply_distribution():
            Returns relative distribution of the circulating supply held by entities with specific balance bands.
        percent_entities_in_profit():
            Returns the percentage of entities in the network that are currently in profit.
    """
    def __init__(self, glassnode_client: GlassnodeClient):
        self._gc = glassnode_client

    def sending_entities(self) -> pd.DataFrame:
        """
        The number of unique entities that were active as a sender.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.SendingCount>`_
        """
        endpoint = '/v1/metrics/entities/sending_count'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def receiving_entities(self) -> pd.DataFrame:
        """
        The number of unique entities that were active as a receiver.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.ReceivingCount>`_
        """
        endpoint = '/v1/metrics/entities/receiving_count'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def active_entities(self) -> pd.DataFrame:
        """
        The number of unique entities that were active either as a sender or receiver.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.ActiveCount>`_
        """
        endpoint = '/v1/metrics/entities/active_count'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def new_entities(self) -> pd.DataFrame:
        """
        The number of unique entities that appeared for the first time
        in a transaction of the native coin in the network.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.NewCount>`_
        """
        endpoint = '/v1/metrics/entities/new_count'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def entities_net_growth(self) -> pd.DataFrame:
        """
        The net growth of unique entities in the network.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.NetGrowthCount>`_
        """
        endpoint = '/v1/metrics/entities/net_growth_count'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def number_of_whales(self) -> pd.DataFrame:
        """
        The number of unique entities holding at least 1k coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.Min1KCount>`_
        """
        endpoint = '/v1/metrics/entities/min_1k_count'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def supply_balance_less_0001(self) -> pd.DataFrame:
        """
        The total circulating supply held by entities with a balance lower than 0.001 coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.SupplyBalanceLess0001>`_
        """
        endpoint = '/v1/metrics/entities/supply_balance_less_0001'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def supply_balance_0001_001(self) -> pd.DataFrame:
        """
        The total circulating supply held by entities with a balance between 0.001 and 0.01 coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.SupplyBalance0001001>`_
        """
        endpoint = '/v1/metrics/entities/supply_balance_0001_001'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def supply_balance_001_01(self) -> pd.DataFrame:
        """
        The total circulating supply held by entities with a balance between 0.01 and 0.1 coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.SupplyBalance00101>`_
        """
        endpoint = '/v1/metrics/entities/supply_balance_001_01'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def supply_balance_01_1(self) -> pd.DataFrame:
        """
        The total circulating supply held by entities with a balance between 0.1 and 1 coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.SupplyBalance011>`_
        """
        endpoint = '/v1/metrics/entities/supply_balance_01_1'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def supply_balance_1_10(self) -> pd.DataFrame:
        """
        The total circulating supply held by entities with a balance between 1 and 10 coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.SupplyBalance110>`_
        """
        endpoint = '/v1/metrics/entities/supply_balance_1_10'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def supply_balance_10_100(self) -> pd.DataFrame:
        """
        The total circulating supply held by entities with a balance between 10 and 100 coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.SupplyBalance10100>`_
        """
        endpoint = '/v1/metrics/entities/supply_balance_10_100'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def supply_balance_100_1k(self) -> pd.DataFrame:
        """
        The total circulating supply held by entities with a balance between 100 and 1,000 coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.SupplyBalance1001K>`_
        """
        endpoint = '/v1/metrics/entities/supply_balance_100_1k'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def supply_balance_1k_10k(self) -> pd.DataFrame:
        """
        The total circulating supply held by entities with a balance between 1,000 and 10,000 coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.SupplyBalance1K10K>`_
        """
        endpoint = '/v1/metrics/entities/supply_balance_1k_10k'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def supply_balance_10k_100k(self) -> pd.DataFrame:
        """
        The total circulating supply held by entities with a balance between 10,000 and 100,000 coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.SupplyBalance10K100K>`_
        """
        endpoint = '/v1/metrics/entities/supply_balance_10k_100k'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def supply_balance_more_100k(self) -> pd.DataFrame:
        """
        The total circulating supply held by entities with a balance of at least 100,000 coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.SupplyBalanceMore100K>`_
        """
        endpoint = '/v1/metrics/entities/supply_balance_more_100k'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    @dataframe_with_inner_object
    def entities_supply_distribution(self) -> pd.DataFrame:
        """
        Relative distribution of the circulating supply held by entities with specific balance bands.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.SupplyDistributionRelative>`_
        """
        endpoint = '/v1/metrics/entities/supply_distribution_relative'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def percent_entities_in_profit(self) -> pd.DataFrame:
        """
        The percentage of entities in the network that are currently in profit.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=entities.ProfitRelative>`_
        """
        endpoint = '/v1/metrics/entities/profit_relative'
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))