Project renaming for clarity

Author: cmoutafidis

README-dev.md

@@ -8,9 +8,9 @@ If you want to make changes to the SDK and test it locally:
 
 2. To use this library in another project while making changes to it, install the package from its local path in that project:
    ```sh
-   pip install -e /path/to/jup-ag-sdk
+   pip install -e /path/to/jup-python-sdk
    ```
 
-   Replace `/path/to/jup-ag-sdk` with the absolute or relative path to this project directory.
+   Replace `/path/to/jup-python-sdk` with the absolute or relative path to this project directory.
 
 By installing in editable mode, any changes you make to the SDK will immediately reflect in your tests without needing to reinstall the package.

README-release.md

@@ -27,4 +27,4 @@ To create and publish a new release of the package to PyPI:
       - Publish the package to PyPI.
 
 5. **Confirm the Release:**
-   - Check [PyPI](https://pypi.org/project/jup-ag-sdk/) to ensure the new version has been published successfully.
+   - Check [PyPI](https://pypi.org/project/jup-python-sdk/) to ensure the new version has been published successfully.

README.md

@@ -7,19 +7,16 @@ A Python SDK for interacting with Jupiter Exchange APIs.
 To install the SDK in your project, run:
 ```
 sh
-pip install jup-ag-sdk
+pip install jup-python-sdk
 ```
 ## **Quick Start**
 
-Here's a basic example to help you get started with the Jup Python SDK:
+Below is a simple example that shows how to fetch and execute an Ultra order with the Jup Python SDK:
 ```
 python
 from dotenv import load_dotenv
-
 from jup_python_sdk.clients.ultra_api_client import UltraApiClient
-from jup_python_sdk.models.ultra_api.ultra_order_request_model import (
-    UltraOrderRequest,
-)
+from jup_python_sdk.models.ultra_api.ultra_order_request_model import UltraOrderRequest
 
 load_dotenv()
 client = UltraApiClient()
@@ -34,17 +31,25 @@ order_request = UltraOrderRequest(
 try:
    client_response = client.order_and_execute(order_request)
    signature = str(client_response["signature"])
-   
+
    print("Order and Execute API Response:")
+   print(f"  - Status: {client_response.get('status')}")
+   if client_response.get("status") == "Failed":
+      print(f"  - Code: {client_response.get('code')}")
+      print(f"  - Error: {client_response.get('error')}")
+
    print(f"  - Transaction Signature: {signature}")
    print(f"  - View on Solscan: https://solscan.io/tx/{signature}")
 
 except Exception as e:
-   print("Error occurred while processing the order:", str(e))
+   print("Error occurred while processing the swap:", str(e))
 finally:
    client.close()
 ```
 
+You can find additional code examples and advanced usage scenarios in the [examples](./examples) folder.
+These examples cover every Ultra API endpoint and should help you get up and running quickly.
+
 ## **Setup Instructions**
 
 Before using the SDK, please ensure you have completed the following steps:
@@ -56,11 +61,27 @@ Before using the SDK, please ensure you have completed the following steps:
    export PRIVATE_KEY=your_private_key_here
    ```
 
-2. **Python Version**:  
-   Make sure you are using Python 3.9 or later.
+2. **Configuration**:  
+   Depending on your credentials and setup, you have a couple of options for initializing the `UltraApiClient`:
+
+   - **Custom Private Key Environment Variable:**  
+     By default, the SDK looks for your private key in an environment variable named `PRIVATE_KEY`.  
+     If you use a different environment variable name, you can specify it explicitly:
+     ```python
+     from jup_python_sdk.clients.ultra_api_client import UltraApiClient
+
+     client = UltraApiClient(private_key_env_var="YOUR_CUSTOM_ENV_VAR")
+     ```
+     This tells the SDK to read your private key from the environment variable you want.
+
+   - **Using an API Key for Enhanced Access:**  
+     If you have an API key from [the Jupiter Portal](https://portal.jup.ag/onboard), you can pass it directly when creating the client:
+     ```python
+     from jup_python_sdk.clients.ultra_api_client import UltraApiClient
 
-3**Configuration**:  
-   TBD
+     client = UltraApiClient(api_key="YOUR_API_KEY")
+     ```
+     When you supply an API key, the library will call the `https://api.jup.ag/` API rather than the default `https://lite-api.jup.ag/` API.
 
 ## **Disclaimer**
 

examples/balances/main.py

@@ -0,0 +1,23 @@
+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:
+    balances_response = client.balances(str(address))
+
+    print("Balances API Response:")
+    for token, details in balances_response.items():
+        print(f"Token: {token}")
+        print(f"  - Amount: {details['amount']}")
+        print(f"    UI Amount: {details['uiAmount']}")
+        print(f"    Slot: {details['slot']}")
+        print(f"    Is Frozen: {details['isFrozen']}")
+
+except Exception as e:
+    print("Error occurred while fetching balances:", str(e))
+finally:
+    client.close()

examples/order-and-execute/main.py

@@ -0,0 +1,31 @@
+from dotenv import load_dotenv
+from jup_python_sdk.clients.ultra_api_client import UltraApiClient
+from jup_python_sdk.models.ultra_api.ultra_order_request_model import UltraOrderRequest
+
+load_dotenv()
+client = UltraApiClient()
+
+order_request = UltraOrderRequest(
+    input_mint="So11111111111111111111111111111111111111112",  # WSOL
+    output_mint="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  # USDC
+    amount=10000000,  # 0.01 WSOL
+    taker=client._get_public_key()
+)
+
+try:
+    client_response = client.order_and_execute(order_request)
+    signature = str(client_response["signature"])
+
+    print("Order and Execute API Response:")
+    print(f"  - Status: {client_response.get('status')}")
+    if client_response.get("status") == "Failed":
+        print(f"  - Code: {client_response.get('code')}")
+        print(f"  - Error: {client_response.get('error')}")
+
+    print(f"  - Transaction Signature: {signature}")
+    print(f"  - View on Solscan: https://solscan.io/tx/{signature}")
+
+except Exception as e:
+    print("Error occurred while processing the swap:", str(e))
+finally:
+    client.close()

examples/shield/main.py

@@ -0,0 +1,25 @@
+from jup_python_sdk.clients.ultra_api_client import UltraApiClient
+
+client = UltraApiClient()
+
+# WSOL and USDC mints
+wsol_mint = "So11111111111111111111111111111111111111112"
+usdc_mint = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
+
+try:
+    shield_response = client.shield(mints=[wsol_mint, usdc_mint])
+
+    print("Shield API Response:")
+    if shield_response["warnings"]:
+        for mint, warnings in shield_response["warnings"].items():
+            print(f"Mint: {mint}")
+            for warning in warnings:
+                print(f"  - Type: {warning.get('type')}")
+                print(f"    Message: {warning.get('message')}")
+    else:
+        print("No warnings returned for provided mints")
+
+except Exception as e:
+    print("Error occurred while fetching shield information:", str(e))
+finally:
+    client.close()

pyproject.toml

@@ -5,8 +5,8 @@ description = "Python SDK for Jupiter Exchange APIs."
 authors = ["Fiji <[email protected]>"]
 license = "MIT"
 readme = "README.md"
-homepage = "https://github.com/cmoutafidis/jup-ag-sdk"
-repository = "https://github.com/cmoutafidis/jup-ag-sdk"
+homepage = "https://github.com/cmoutafidis/jup-python-sdk"
+repository = "https://github.com/cmoutafidis/jup-python-sdk"
 keywords = ["solana", "jupiter", "sdk"]
 packages = [{include = "jup_python_sdk"}]
 classifiers = [