diff --git a/README.md b/README.md index 29b3914..d24fa32 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,11 @@ # Token Terminal -[![Python 3.6](https://img.shields.io/badge/python-3.6-blue.svg)](https://www.python.org/downloads/release/python-360/) [![Python 3.7](https://img.shields.io/badge/python-3.7-blue.svg)](https://www.python.org/downloads/release/python-370/) [![Python 3.8](https://img.shields.io/badge/python-3.8-blue.svg)](https://www.python.org/downloads/release/python-380/) [![Python 3.9](https://img.shields.io/badge/python-3.9-blue.svg)](https://www.python.org/downloads/release/python-390/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) -[![Build](https://github.com/itzmestar/tokenterminal/actions/workflows/python-package.yml/badge.svg?branch=main)](https://github.com/itzmestar/tokenterminal/actions/workflows/python-package.yml) - ------- ### Unofficial [Token Terminal API](https://www.tokenterminal.com/) client in python @@ -50,4 +47,33 @@ for project_info in projects_data: project_metrics = token_terminal.get_historical_metrics('0x') for metrics in project_metrics: print(metrics) -``` \ No newline at end of file + +# To retrieve the metric availability for a project. +reponse = token_terminal.get_metric_availability(project_id=project_id) + +# To retrieve metric aggregation data for one project. +reponse = token_terminal.get_metric_aggregations(project_id=project_id) + +# Get financial statement for a project +reponse = token_terminal.get_financial_statement( + project_id=project_id, + timestamp_granularity='week', + interval='1m' + ) + +# Get list of all available market sectors that are available +reponse = token_terminal.get_market_sectors() + +# Get list of all metrics +reponse = token_terminal.get_all_metrics() + +# To retrieve metric aggregations for multiple projects. +project_ids = ['aave', 'uniswap'] +reponse = token_terminal.get_projects_metric_aggregations(project_ids=project_ids) +``` +------- +#### Donate & Help maintain the library + +[![Paypal](qrcode.png)](https://www.paypal.com/ncp/payment/KLFNJN7SH39EN) + +------- \ No newline at end of file diff --git a/qrcode.png b/qrcode.png new file mode 100644 index 0000000..e13d221 Binary files /dev/null and b/qrcode.png differ diff --git a/tokenterminal/__version__.py b/tokenterminal/__version__.py index 5ba58a7..dbbb70b 100644 --- a/tokenterminal/__version__.py +++ b/tokenterminal/__version__.py @@ -1,7 +1,7 @@ __title__ = 'tokenterminal' __description__ = 'Unofficial Token Terminal API client.' __url__ = 'https://github.com/itzmestar/tokenterminal' -__version__ = '1.0.1' +__version__ = '2.0.0' __build__ = 0x010001 __author__ = 'Tarique Anwer' __author_email__ = 'itzmetariq@gmail.com' diff --git a/tokenterminal/tokenterminal.py b/tokenterminal/tokenterminal.py index e004a33..6ed0b1a 100644 --- a/tokenterminal/tokenterminal.py +++ b/tokenterminal/tokenterminal.py @@ -38,47 +38,405 @@ def _get(self, endpoint, params=None, stream=False): def get_all_projects(self): """ - Returns an overview of latest data for all projects, ranging from metadata such as - launch dates, logos brand colors and Twitter followers to more fundamental metrics - such as Revenue, GMV, TVL and P/S ratios. - The project_id can be used as a Path parameter in subsequent endpoints. + Use this method to retrieve a list of all projects that are available on the API. + """ + path = '/v2/projects' + + response = self._get(path) + return response + + def get_historical_metrics(self, project_id: str, **kwargs): + """ + Use this method to retrieve historical data for a project. + Fill in the required fields on the modal to the right. + """ + path = f'/v2/projects/{project_id}/metrics' - The data is updated every 10 minutes. + response = self._get(path, params=kwargs) + return response + + def get_metric_availability(self, project_id: str): + """ + Use this method to retrieve the metric availability for a project. + :param project_id: project_id :return: """ - path = '/v1/projects' + path = f'/v2/projects/{project_id}' response = self._get(path) return response - def get_historical_metrics(self, project_id, granularity='project', interval='daily'): + def get_metric_aggregations(self, project_id: str): """ - Returns project's historical metrics. The project_id can be fetched from the v1/projects endpoint. - The datetime granularity can be controlled with interval, omitting it will default to daily. + Use this method to retrieve metric aggregation data for one project. + :param project_id: project_id + :return: + """ + path = f'/v2/projects/{project_id}/metric-aggregations' - The metric data of a given project can be split into components. In Uniswap's case a component is - the trading pair (e.g. USDC-WETH or DAI-WETH), in Compound's case it's the lending market (e.g. ETH, - USDC or WBTC). - By choosing top10 or component for data_granularity, the composition of a given metric can be examined - more thoroughly. Project's that have top10 or component data can be seen from /v1/projects's - metric_availability field. + response = self._get(path) + return response - By default project-level data is shown, ignoring component-level data altogether. + def get_financial_statement( + self, + project_id: str, + timestamp_granularity: str = None, + interval: str = None + ): + """ + Use this method to retrieve the financial statement report for a project. + :param interval: can be '1m', '1y', '2y', '3y', '5y' or 'max' + :param timestamp_granularity: can be 'year', 'quarter', 'month' or 'week' + :param project_id: The project ID to retrieve financial statement for. + :return: + """ + path = f'/v2/projects/{project_id}/financial-statement' - The data is updated once a day. + params = { + 'timestamp_granularity': timestamp_granularity, + 'interval': interval + } + + response = self._get(path, params=params) + return response + + def get_market_sectors(self): + """ + Use this method to retrieve a list of all available market sectors that are available on the API. + :return: + """ + path = f'/v2/market-sectors' + + response = self._get(path) + return response + + def get_market_sector(self, market_sector_id: str): + """ + Use this method to retrieve a market sector metadata and the list of all projects belonging to market sector. + """ + path = f'/v2/market-sectors/{market_sector_id}' - :param project_id: Project's id, can be fetched from v1/projects endpoint. - :param granularity: The granularity of data, options are project, top10 or component. - Defaults to project. - :param interval: The interval historical data is given, options are daily or monthly. - Defaults to daily. + response = self._get(path) + return response + + def get_all_metrics(self): + """ + Use this method to retrieve a list of all metrics available on the API. :return: """ - path = f'/v1/projects/{project_id}/metrics' + path = f'/v2/metrics' + + response = self._get(path) + return response + + def get_projects_metric_data(self, metric_id: str, project_ids: list = None, start: str = None, end: str = None): + """ + Use this method to retrieve metric data for multiple projects. + You can get specific metric for all projects by omiting project_ids or using project_ids=all. + :param metric_id: Allows you to select one of the metrics available. The full list is available on the metrics endpoint + :param project_ids: Allows you to select one or more of the projects available for a specific metric. + When including multiple projects, separate each one with a comma. Example: aave,uniswap + :param start: Allows you to select the start date for the query. If no start is selected, + the query defaults to launch date or the first date for which there is data available for the chosen metric(s). + :param end: Allows you to select the end date for the query. If no end is selected, + the query defaults to the latest date for which there is data available for the chosen metric(s). + :return: + """ + path = f'/v2/metrics/{metric_id}' params = { - 'data_granularity': granularity, - 'interval': interval + 'project_ids': project_ids, + 'start': start, + 'end': end, + } + + response = self._get(path, params=params) + return response + + def get_projects_metric_aggregations(self, project_ids: list[str], metric_ids: list = None): + """ + Use this method to retrieve metric aggregations for multiple projects. + + You can get all aggregations for all projects by omiting project_ids and metric_ids parameters. + Fetching all projects or metrics you can omit the parameter or using parameter value all. + :param project_ids: + :param metric_ids: + :return: + """ + path = f'/v2/metrics/metric-aggregations' + + params = { + 'project_ids': project_ids, + 'metric_ids': metric_ids + } + + response = self._get(path, params=params) + return response + + def get_blockchain_comparison_dataset( + self, + chain_ids: list = None, + order_by: str = None, + order_direction: str = None, + limit: int = None + ): + """ + Use this method to retrieve the Blockchain comparison dataset. + + You can get the whole dataset by omiting all parameters. + :param chain_ids: + :param order_by: + :param order_direction: + :param limit: + :return: + """ + path = f'/v2/datasets/blockchain_comparison' + + params = { + 'chain_ids': chain_ids, + 'order_by': order_by, + 'order_direction': order_direction, + 'limit': limit + } + + response = self._get(path, params=params) + return response + + def get_cohort_analysis_dataset( + self, + project_ids: list = None, + market_sector_ids: list = None, + order_by: str = None, + order_direction: str = None, + limit: int = None + ): + """ + Use this method to retrieve the Cohort analysis dataset. + + You can get the whole dataset by omiting all parameters. + :param project_ids: + :param market_sector_ids: + :param order_by: + :param order_direction: + :param limit: + :return: + """ + path = f'/v2/datasets/cohort_analysis' + + params = { + 'project_ids': project_ids, + 'market_sector_ids': market_sector_ids, + 'order_by': order_by, + 'order_direction': order_direction, + 'limit': limit + } + + response = self._get(path, params=params) + return response + + def get_crypto_screener_dataset( + self, + project_ids: list = None, + market_sector_ids: list = None, + order_by: str = None, + order_direction: str = None, + limit: int = None + ): + """ + Use this method to retrieve the Crypto screener dataset. You can get the whole dataset by omiting all parameters. + + Metrics use the following pattern in the response body: __. + + Metric IDs are the same as the ones used in the /v2/metrics endpoint. + Intervals are 24h, 7d, 30d, 90d, 180d, 365d, max. + Aggregations are trend, change, avg, ath, atl. + :param project_ids: + :param market_sector_ids: + :param order_by: + :param order_direction: + :param limit: + :return: + """ + path = f'/v2/datasets/crypto_screener' + + params = { + 'project_ids': project_ids, + 'market_sector_ids': market_sector_ids, + 'order_by': order_by, + 'order_direction': order_direction, + 'limit': limit + } + + response = self._get(path, params=params) + return response + + def get_insider_transactions_dataset( + self, + project_ids: list = None, + chain_ids: list = None, + order_by: str = None, + order_direction: str = None, + limit: int = None + ): + """ + Use this method to retrieve the Insider transactions dataset. + + You can get the whole dataset by omiting all parameters. + :param project_ids: + :param chain_ids: + :param order_by: + :param order_direction: + :param limit: + :return: + """ + path = f'/v2/datasets/insider_transactions' + + params = { + 'project_ids': project_ids, + 'chain_ids': chain_ids, + 'order_by': order_by, + 'order_direction': order_direction, + 'limit': limit + } + + response = self._get(path, params=params) + return response + + def get_top_tokenholders_dataset( + self, + project_ids: list = None, + chain_ids: list = None, + market_sector_ids: list = None, + order_by: str = None, + order_direction: str = None, + limit: int = None + ): + """ + Use this method to retrieve the Top tokenholders dataset. + + You can get the whole dataset by omiting all parameters. + :param project_ids: + :param chain_ids: + :param market_sector_ids: + :param order_by: + :param order_direction: + :param limit: + :return: + """ + path = f'/v2/datasets/top_tokenholders' + + params = { + 'project_ids': project_ids, + 'chain_ids': chain_ids, + 'market_sector_ids': market_sector_ids, + 'order_by': order_by, + 'order_direction': order_direction, + 'limit': limit + } + + response = self._get(path, params=params) + return response + + def get_project_contracts_dataset( + self, + project_ids: list = None, + chain_ids: list = None, + market_sector_ids: list = None, + order_by: str = None, + order_direction: str = None, + limit: int = None + ): + """ + Use this method to retrieve the Project contracts dataset. + + You can get the whole dataset by omiting all parameters. + :param project_ids: + :param chain_ids: + :param market_sector_ids: + :param order_by: + :param order_direction: + :param limit: + :return: + """ + path = f'/v2/datasets/project_contracts' + + params = { + 'project_ids': project_ids, + 'chain_ids': chain_ids, + 'market_sector_ids': market_sector_ids, + 'order_by': order_by, + 'order_direction': order_direction, + 'limit': limit + } + + response = self._get(path, params=params) + return response + + def get_stablecoins_dataset( + self, + project_ids: list = None, + chain_ids: list = None, + market_sector_ids: list = None, + order_by: str = None, + order_direction: str = None, + limit: int = None + ): + """ + Use this method to retrieve the Stablecoins dataset. + + You can get the whole dataset by omiting all parameters. + :param project_ids: + :param chain_ids: + :param market_sector_ids: + :param order_by: + :param order_direction: + :param limit: + :return: + """ + path = f'/v2/datasets/stablecoins' + + params = { + 'project_ids': project_ids, + 'chain_ids': chain_ids, + 'market_sector_ids': market_sector_ids, + 'order_by': order_by, + 'order_direction': order_direction, + 'limit': limit + } + + response = self._get(path, params=params) + return response + + def get_trending_contracts_dataset( + self, + project_ids: list = None, + chain_ids: list = None, + market_sector_ids: list = None, + order_by: str = None, + order_direction: str = None, + limit: int = None + ): + """ + Use this endpoint to retrieve the Trending contracts dataset. + + You can get the whole dataset by omiting all parameters. + :param project_ids: + :param chain_ids: + :param market_sector_ids: + :param order_by: + :param order_direction: + :param limit: + :return: + """ + path = f'/v2/datasets/trending_contracts' + + params = { + 'project_ids': project_ids, + 'chain_ids': chain_ids, + 'market_sector_ids': market_sector_ids, + 'order_by': order_by, + 'order_direction': order_direction, + 'limit': limit } response = self._get(path, params=params)