Add remaining Token api methods (#9)

* feat: add remaning Token api methods [#3]

* chore: version bump [#3[

* docs: add usage examples to quickstart docs [#3]

* docs: use stable link instead of latest [#3]

* docs: re-add rtd badge [#3]

README.md

@@ -12,7 +12,7 @@
     <a href="https://www.python.org/downloads/">
         <img alt="Python Versions Shield" src="https://img.shields.io/badge/Python-3.9+-blue?logo=python&logoColor=white">
     </a>
-    <!-- <a href="https://birdeye-py.readthedocs.io/en/stable/"><img alt="Read The Docs Badge" src="https://img.shields.io/readthedocs/birdeye-py"></a> -->
+    <a href="https://birdeye-py.readthedocs.io/en/stable/"><img alt="Read The Docs Badge" src="https://img.shields.io/readthedocs/birdeye-py"></a>
     <a href="https://pypistats.org/packages/birdeye-py">
         <img alt="Download Shield" src="https://img.shields.io/pypi/dm/birdeye-py">
     </a>
@@ -22,7 +22,7 @@
 </p>
 
 ## Features
-- 🪙 **BirdEye** Only supports [standard](https://docs.birdeye.so/docs/data-accessibility-by-packages#1-standard-package) subscription api urls (package is still in active development)
+- 🪙 **BirdEye** Supports all BirdEye data services [apis](https://docs.birdeye.so/docs/overview).
 - ♻️ **Retry Strategy** Sensible defaults to reliably retry/back-off fetching data from the api
 - ✏️ **Code Formatting** Fully typed with [mypy](https://mypy-lang.org/) and code formatters [black](https://github.com/psf/black) / [isort](https://pycqa.github.io/isort/)
 - ⚒️ **Modern tooling** using [uv](https://docs.astral.sh/uv/), [ruff](https://docs.astral.sh/ruff/), and [pre-commit](https://pre-commit.com/)
@@ -49,7 +49,7 @@ client.defi.price(
 ```
 
 ## Documentation
-See ful documentation [here](https://birdeye-py.readthedocs.io/en/latest/), or API [docs](https://docs.birdeye.so/docs/overview)
+See ful documentation [here](https://birdeye-py.readthedocs.io/en/stable/), or API [docs](https://docs.birdeye.so/docs/overview)
 
 ---
 

birdeyepy/birdeye.py

@@ -7,7 +7,7 @@
 )
 
 
-__version__ = "0.0.5"
+__version__ = "0.0.6"
 
 
 class BirdEye:

birdeyepy/resources/token.py

@@ -1,6 +1,6 @@
 from typing import Optional, cast
 
-from birdeyepy.utils import BirdEyeApiUrls, BirdEyeRequestParams, IHttp
+from birdeyepy.utils import BirdEyeApiUrls, BirdEyeRequestParams, IHttp, as_api_args
 
 
 class Token:
@@ -15,7 +15,7 @@ def list_all(
         offset: Optional[int] = 0,
         limit: Optional[int] = 50,
         min_liquidity: Optional[int] = 50,
-    ) -> list:
+    ) -> dict:
         """Get token list of any supported chains.
 
         :param sort_by:         The field to sort by.
@@ -35,4 +35,246 @@ def list_all(
         request: BirdEyeRequestParams = {"params": params}
         response = self.http.send(path=BirdEyeApiUrls.DEFI_TOKEN_LIST, **request)
 
-        return cast(list, response)
+        return cast(dict, response)
+
+    def security(self, address: str) -> dict:
+        """Get token security of any supported chains.
+
+        :param address:     The address of the token.
+        """
+        params = {"address": address}
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(path=BirdEyeApiUrls.TOKEN_SECURITY, **request)
+
+        return cast(dict, response)
+
+    def overview(self, address: str) -> dict:
+        """Get overview of a token.
+
+        :param address:     The address of the token.
+        """
+        params = {"address": address}
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(path=BirdEyeApiUrls.TOKEN_OVERVIEW, **request)
+
+        return cast(dict, response)
+
+    def creation_info(self, address: str) -> dict:
+        """Get creation info of a token.
+
+        :param address:     The address of the token.
+        """
+        params = {"address": address}
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(path=BirdEyeApiUrls.TOKEN_CREATION_INFO, **request)
+
+        return cast(dict, response)
+
+    def trending(
+        self,
+        sort_by: str = "rank",
+        sort_type: str = "asc",
+        offset: int = 0,
+        limit: int = 10,
+    ) -> dict:
+        """Retrieve a dynamic and up-to-date list of trending tokens based on specified sorting criteria.
+
+        :param sort_by:     The field to sort by.
+        :param sort_type:   The type of sorting.
+        :param offset:      The offset.
+        :param limit:       The limit.
+        """
+        params = {
+            "sort_by": sort_by,
+            "sort_type": sort_type,
+            "offset": offset,
+            "limit": limit,
+        }
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(path=BirdEyeApiUrls.TOKEN_TRENDING, **request)
+
+        return cast(dict, response)
+
+    def list_all_v2(self) -> dict:
+        """This endpoint facilitates the retrieval of a list of tokens on a specified blockchain network. This upgraded version is exclusive to business and enterprise packages. By simply including the header for the requested blockchain without any query parameters, business and enterprise users can get the full list of tokens on the specified blockchain in the URL returned in the response. This removes the need for the limit response of the previous version and reduces the workload of making multiple calls."""
+        response = self.http.send(path=BirdEyeApiUrls.TOKEN_LIST_V2, method="POST")
+
+        return cast(dict, response)
+
+    @as_api_args
+    def new_listing(
+        self,
+        time_to: int,
+        limit: Optional[int] = None,
+        meme_platform_enabled: Optional[bool] = None,
+    ) -> dict:
+        """Get newly listed tokens of any supported chains.
+
+        :param time_to:                 Specify the end time using Unix timestamps in seconds
+        :param limit:                   The limit
+        :param meme_platform_enabled:   Enable to receive token new listing from meme platforms (eg: pump.fun). This filter only supports Solana
+        """
+        params = {
+            "time_to": time_to,
+        }
+
+        if limit is not None:
+            params["limit"] = limit
+
+        if meme_platform_enabled is not None:
+            params["meme_platform_enabled"] = meme_platform_enabled
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(path=BirdEyeApiUrls.TOKEN_NEW_LISTING, **request)
+
+        return cast(dict, response)
+
+    def top_traders(
+        self,
+        address: str,
+        time_frame: Optional[str] = "24h",
+        sort_type: Optional[str] = "desc",
+        sort_by: Optional[str] = "volume",
+        offset: Optional[int] = 0,
+        limit: Optional[int] = 10,
+    ) -> dict:
+        """Get top traders of given token.
+
+        :param address:     The address of the token.
+        :param time_frame:  The time frame for the data (e.g., '24h', '7d').
+        :param sort_type:   The type of sorting.
+        :param sort_by:     The field to sort by.
+        :param offset:      The offset.
+        :param limit:       The limit.
+        """
+        params = {
+            "address": address,
+            "time_frame": time_frame,
+            "sort_type": sort_type,
+            "sort_by": sort_by,
+            "offset": offset,
+            "limit": limit,
+        }
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(path=BirdEyeApiUrls.TOKEN_TOP_TRADERS, **request)
+
+        return cast(dict, response)
+
+    def all_markets(
+        self,
+        address: str,
+        time_frame: Optional[str] = "24h",
+        sort_type: Optional[str] = "desc",
+        sort_by: Optional[str] = "liquidity",
+        offset: Optional[int] = 0,
+        limit: Optional[int] = 10,
+    ) -> dict:
+        """The API provides detailed information about the markets for a specific cryptocurrency token on a specified blockchain. Users can retrieve data for one or multiple markets related to a single token. This endpoint requires the specification of a token address and the blockchain to filter results. Additionally, it supports optional query parameters such as offset, limit, and required sorting by liquidity or sort type (ascending or descending) to refine the output.
+
+        :param address:     The address of the token.
+        :param time_frame:  The time frame for the data (e.g., '24h', '7d').
+        :param sort_type:   The type of sorting.
+        :param sort_by:     The field to sort by.
+        :param offset:      The offset.
+        :param limit:       The limit.
+        """
+        params = {
+            "address": address,
+            "time_frame": time_frame,
+            "sort_type": sort_type,
+            "sort_by": sort_by,
+            "offset": offset,
+            "limit": limit,
+        }
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(path=BirdEyeApiUrls.TOKEN_ALL_MARKETS, **request)
+
+        return cast(dict, response)
+
+    def market_metadata_single(self, address: str) -> dict:
+        """Get metadata of single token
+
+        :param address:       The address of the token.
+        """
+        params = {"address": address}
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(path=BirdEyeApiUrls.TOKEN_METADATA_SINGLE, **request)
+
+        return cast(dict, response)
+
+    @as_api_args
+    def market_metadata_multiple(self, addresses: str | list[str]) -> dict:
+        """Get metadata of multiple tokens
+
+        :param addresses:       The address of the token...can be comma separated string or list of strings.
+        """
+        params = {"list_address": addresses}
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(
+            path=BirdEyeApiUrls.TOKEN_METADATA_MULTIPLE, **request
+        )
+
+        return cast(dict, response)
+
+    def market_data(self, address: str) -> dict:
+        """Get market data of single token.
+
+        :param address:       The address of the token.
+        """
+        params = {"address": address}
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(path=BirdEyeApiUrls.TOKEN_MARKET_DATA, **request)
+
+        return cast(dict, response)
+
+    def trade_data_single(self, address: str) -> dict:
+        """Get trade data of single token
+
+        :param addresses:       The address of the token.
+        """
+        params = {"address": address}
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(
+            path=BirdEyeApiUrls.TOKEN_TRADE_DATA_SINGLE, **request
+        )
+
+        return cast(dict, response)
+
+    @as_api_args
+    def trade_data_multiple(self, addresses: str | list[str]) -> dict:
+        """Get trade data of multiple tokens.
+
+        :param addresses:       The address of the token...can be comma separated string or list of strings.
+        """
+        params = {"list_address": addresses}
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(
+            path=BirdEyeApiUrls.TOKEN_TRADE_DATA_MULTIPLE, **request
+        )
+
+        return cast(dict, response)
+
+    def holder(self, address: str, offset: int = 0, limit: int = 100) -> dict:
+        """Get top holder list of the given token.
+
+        :param address:     The address of the token.
+        :param offset:      The offset.
+        :param limit:       The limit.
+        """
+        params = {"address": address, "offset": offset, "limit": limit}
+
+        request: BirdEyeRequestParams = {"params": params}
+        response = self.http.send(path=BirdEyeApiUrls.TOKEN_HOLDER, **request)
+
+        return cast(dict, response)

birdeyepy/utils/enums.py

@@ -14,6 +14,22 @@ class BirdEyeApiUrls:
     TRADER_GAINERS_LOSERS = "trader/gainers-losers"
     TRADER_SEEK_BY_TIME = "trader/txs/seek_by_time"
 
+    # TOKEN
+    TOKEN_SECURITY = "defi/token_security"
+    TOKEN_OVERVIEW = "defi/token_overview"
+    TOKEN_CREATION_INFO = "defi/token_creation_info"
+    TOKEN_TRENDING = "defi/token_trending"
+    TOKEN_LIST_V2 = "/defi/v2/tokens/all"
+    TOKEN_NEW_LISTING = "defi/v2/tokens/new_listing"
+    TOKEN_TOP_TRADERS = "defi/v2/tokens/top_traders"
+    TOKEN_ALL_MARKETS = "/defi/v2/markets"
+    TOKEN_METADATA_SINGLE = "defi/v3/token/meta-data/single"
+    TOKEN_METADATA_MULTIPLE = "defi/v3/token/meta-data/multiple"
+    TOKEN_MARKET_DATA = "defi/v3/token/market-data"
+    TOKEN_HOLDER = "defi/v3/token/holder"
+    TOKEN_TRADE_DATA_SINGLE = "defi/v3/token/trade-data/single"
+    TOKEN_TRADE_DATA_MULTIPLE = "defi/v3/token/trade-data/multiple"
+
 
 class BirdEyeChainEnum(SimpleEnum):
     # Solana