Added holdings endpoint

Author: cmoutafidis

examples/holdings/main.py

@@ -0,0 +1,29 @@
+from dotenv import load_dotenv
+from jup_python_sdk.clients.ultra_api_client import UltraApiClient
+
+load_dotenv()
+client = UltraApiClient()
+
+address = client._get_public_key()
+
+try:
+    holdings_response = client.holdings(str(address))
+
+    print("Holdings API Response:")
+    print(f"Total Portfolio Value: {holdings_response['uiAmount']} ({holdings_response['uiAmountString']})")
+    
+    print("\nToken Holdings:")
+    for mint, token_accounts in holdings_response['tokens'].items():
+        print(f"\nToken Mint: {mint}")
+        for account in token_accounts:
+            print(f"  Account: {account['account']}")
+            print(f"  Amount: {account['uiAmountString']}")
+            print(f"  Decimals: {account['decimals']}")
+            print(f"  Is ATA: {account['isAssociatedTokenAccount']}")
+            print(f"  Is Frozen: {account['isFrozen']}")
+            print(f"  Exclude From Net Worth: {account['excludeFromNetWorth']}")
+
+except Exception as e:
+    print("Error occurred while fetching holdings:", str(e))
+finally:
+    client.close()

jup_python_sdk/clients/ultra_api_client.py

@@ -109,6 +109,23 @@ def balances(self, address: str) -> Dict[str, Any]:
 
         return response.json()  # type: ignore
 
+    def holdings(self, address: str) -> Dict[str, Any]:
+        """
+        Get token holdings of an account from the Jupiter Ultra API.
+
+        Args:
+            address (str): The public key of the account to get holdings for.
+
+        Returns:
+            dict: The dict api response containing portfolio value and detailed
+                  token account information organized by mint address.
+        """
+        url = f"{self.base_url}/ultra/v1/holdings/{address}"
+        response = self.client.get(url, headers=self._get_headers())
+        response.raise_for_status()
+
+        return response.json()  # type: ignore
+
     def shield(self, mints: list[str]) -> Dict[str, Any]:
         """
         Get token information and warnings for specific mints

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "jup-python-sdk"
-version = "1.1.1"
+version = "1.2.0"
 description = "Python SDK for Jupiter Exchange APIs."
 authors = ["Fiji <[email protected]>"]
 license = "MIT"

tests/test_ultra_holdings.py

@@ -0,0 +1,43 @@
+from dotenv import load_dotenv
+
+from jup_python_sdk.clients.ultra_api_client import UltraApiClient
+
+
+def test_ultra_get_holdings() -> None:
+    """
+    Test the UltraApiClient holdings method.
+    """
+    load_dotenv()
+    client = UltraApiClient()
+
+    address = client._get_public_key()
+
+    try:
+        holdings_response = client.holdings(str(address))
+        assert (
+            "amount" in holdings_response
+        ), "Response does not contain 'amount' key."
+        assert (
+            "tokens" in holdings_response
+        ), "Response does not contain 'tokens' key."
+
+        print()
+        print("Holdings API Response:")
+        print(
+            f"Total Portfolio Value: {holdings_response['uiAmount']} ({holdings_response['uiAmountString']})"
+        )
+
+        print("\nToken Holdings:")
+        for mint, token_accounts in holdings_response["tokens"].items():
+            print(f"\nToken Mint: {mint}")
+            for account in token_accounts:
+                print(f"  Account: {account['account']}")
+                print(f"  Amount: {account['uiAmountString']}")
+                print(f"  Decimals: {account['decimals']}")
+                print(f"  Is ATA: {account['isAssociatedTokenAccount']}")
+                print(f"  Is Frozen: {account['isFrozen']}")
+
+    except Exception as e:
+        print("Error occurred while fetching holdings:", str(e))
+    finally:
+        client.close()