feat: liquidity endpoint

datamaxi/datamaxi/dex.py

@@ -136,7 +136,7 @@ def candle(
             pandas (bool): Return data as pandas DataFrame
 
         Returns:
-            Candle data in pandas DataFrame and next request function
+            DEX candle data in pandas DataFrame and next request function
         """
         check_required_parameters(
             [
@@ -197,10 +197,102 @@ def next_request():
         else:
             return res, next_request
 
+    def liquidity(
+        self,
+        chain: str,
+        exchange: str,
+        pool: str,
+        page: int = 1,
+        limit: int = 1000,
+        fromDateTime: str = None,
+        toDateTime: str = None,
+        sort: str = "desc",
+        pandas: bool = True,
+    ) -> Union[Tuple[Dict, Callable], Tuple[pd.DataFrame, Callable]]:
+        """Fetch DEX liquidity data
+
+        `GET /api/v1/dex/liquidity`
+
+        <https://docs.datamaxiplus.com/rest/dex/liquidity>
+
+        Args:
+            chain (str): Chain name
+            exchange (str): Exchange name
+            pool (str): Pool name
+            page (int): Page number
+            limit (int): Limit of data
+            fromDateTime (str): Start date and time (accepts format "2006-01-02 15:04:05" or "2006-01-02")
+            toDateTime (str): End date and time (accepts format "2006-01-02 15:04:05" or "2006-01-02")
+            sort (str): Sort order
+            pandas (bool): Return data as pandas DataFrame
+
+        Returns:
+            DEX liquidity data in pandas DataFrame and next request function
+        """
+        check_required_parameters(
+            [
+                [chain, "chain"],
+                [exchange, "exchange"],
+                [pool, "pool"],
+            ]
+        )
+
+        if page < 1:
+            raise ValueError("page must be greater than 0")
+
+        if limit < 1:
+            raise ValueError("limit must be greater than 0")
+
+        if fromDateTime is not None and toDateTime is not None:
+            raise ValueError(
+                "fromDateTime and toDateTime cannot be set at the same time"
+            )
+
+        if sort not in ["asc", "desc"]:
+            raise ValueError("sort must be either asc or desc")
+
+        params = {
+            "chain": chain,
+            "exchange": exchange,
+            "pool": pool,
+            "page": page,
+            "limit": limit,
+            "from": fromDateTime,
+            "to": toDateTime,
+            "sort": sort,
+        }
+
+        res = self.query("/api/v1/dex/liquidity", params)
+        if res["data"] is None or len(res["data"]) == 0:
+            raise ValueError("no data found")
+
+        def next_request():
+            return self.get(
+                chain,
+                exchange,
+                pool,
+                page + 1,
+                limit,
+                fromDateTime,
+                toDateTime,
+                sort,
+                pandas,
+            )
+
+        if pandas:
+            df = convert_data_to_data_frame(
+                res["data"],
+                ["b", "l"],
+            )
+            return df, next_request
+        else:
+            return res, next_request
+
     def chains(self) -> List[str]:
         """Fetch supported chains accepted by
-        [datamaxi.DexCandle.get](./#datamaxi.datamaxi.DexCandle.get)
-        API.
+        [datamaxi.Dex.candle](./#datamaxi.datamaxi.Dex.candle),
+        [datamaxi.Dex.trade](./#datamaxi.datamaxi.Dex.trade) and
+        [datamaxi.Dex.liquidity](./#datamaxi.datamaxi.Dex.liquidity).
 
         `GET /api/v1/dex/chains`
 
@@ -215,8 +307,9 @@ def chains(self) -> List[str]:
 
     def exchanges(self) -> List[str]:
         """Fetch supported exchanges accepted by
-        [datamaxi.DexCandle.get](./#datamaxi.datamaxi.DexCandle.get)
-        API.
+        [datamaxi.Dex.candle](./#datamaxi.datamaxi.Dex.candle),
+        [datamaxi.Dex.trade](./#datamaxi.datamaxi.Dex.trade) and
+        [datamaxi.Dex.liquidity](./#datamaxi.datamaxi.Dex.liquidity).
 
         `GET /api/v1/dex/exchanges`
 
@@ -231,8 +324,9 @@ def exchanges(self) -> List[str]:
 
     def pools(self, exchange: str = None, chain: str = None) -> List[Dict]:
         """Fetch supported pools accepted by
-        [datamaxi.DexCandle.get](./#datamaxi.datamaxi.DexCandle.get)
-        API.
+        [datamaxi.Dex.candle](./#datamaxi.datamaxi.Dex.candle),
+        [datamaxi.Dex.trade](./#datamaxi.datamaxi.Dex.trade) and
+        [datamaxi.Dex.liquidity](./#datamaxi.datamaxi.Dex.liquidity).
 
         `GET /api/v1/dex/pools`
 
@@ -256,8 +350,7 @@ def pools(self, exchange: str = None, chain: str = None) -> List[Dict]:
 
     def intervals(self) -> List[str]:
         """Fetch supported intervals accepted by
-        [datamaxi.DexCandle.get](./#datamaxi.datamaxi.DexCandle.get)
-        API.
+        [datamaxi.Dex.candle](./#datamaxi.datamaxi.Dex.candle).
 
         `GET /api/v1/dex/intervals`