solanab-jup-python-sdk 2.0.3__py3-none-any.whl → 2.0.6__py3-none-any.whl

jup_python_sdk/clients/jupiter_client.py

@@ -15,11 +15,26 @@ class _CoreJupiterClient:
     """
 
     def __init__(self, api_key: Optional[str], private_key_env_var: str):
+        """
+        Initialize the core Jupiter client.
+
+        Args:
+            api_key: Optional API key for enhanced access to Jupiter API.
+                If provided, uses https://api.jup.ag endpoint.
+            private_key_env_var: Name of environment variable containing the
+                private key. Defaults to 'PRIVATE_KEY'.
+        """
         self.api_key = api_key
         self.base_url = "https://api.jup.ag" if api_key else "https://lite-api.jup.ag"
         self.private_key_env_var = private_key_env_var
 
     def _get_headers(self) -> dict[str, str]:
+        """
+        Get headers for GET requests.
+
+        Returns:
+            Dict containing headers with Accept and optional API key.
+        """
         headers = {
             "Accept": "application/json",
         }
@@ -28,6 +43,12 @@ class _CoreJupiterClient:
         return headers
 
     def _post_headers(self) -> dict[str, str]:
+        """
+        Get headers for POST requests.
+
+        Returns:
+            Dict containing headers with Accept, Content-Type, and optional API key.
+        """
         headers = {
             "Accept": "application/json",
             "Content-Type": "application/json",
@@ -58,13 +79,34 @@ class _CoreJupiterClient:
             raise ValueError(f"Invalid base58 private key format: {e}") from e
 
     def get_public_key(self) -> str:
+        """
+        Get the public key from the loaded private key.
+
+        Returns:
+            Public key as a base58-encoded string.
+        """
         wallet = Keypair.from_bytes(self._load_private_key_bytes())
         return str(wallet.pubkey())
 
     async def get_public_key_async(self) -> str:
+        """
+        Async wrapper for get_public_key().
+
+        Returns:
+            Public key as a base58-encoded string.
+        """
         return self.get_public_key()
 
     def _sign_base64_transaction(self, transaction_base64: str) -> VersionedTransaction:
+        """
+        Sign a base64-encoded transaction.
+
+        Args:
+            transaction_base64: Base64-encoded transaction string.
+
+        Returns:
+            Signed VersionedTransaction object.
+        """
         transaction_bytes = base64.b64decode(transaction_base64)
         versioned_transaction = VersionedTransaction.from_bytes(transaction_bytes)
         return self._sign_versioned_transaction(versioned_transaction)
@@ -72,6 +114,15 @@ class _CoreJupiterClient:
     def _sign_versioned_transaction(
         self, versioned_transaction: VersionedTransaction
     ) -> VersionedTransaction:
+        """
+        Sign a VersionedTransaction with the loaded private key.
+
+        Args:
+            versioned_transaction: VersionedTransaction to sign.
+
+        Returns:
+            Signed VersionedTransaction with signature applied.
+        """
         wallet = Keypair.from_bytes(self._load_private_key_bytes())
         account_keys = versioned_transaction.message.account_keys
         wallet_index = account_keys.index(wallet.pubkey())
@@ -87,6 +138,15 @@ class _CoreJupiterClient:
     def _serialize_versioned_transaction(
         self, versioned_transaction: VersionedTransaction
     ) -> str:
+        """
+        Serialize a VersionedTransaction to base64 string.
+
+        Args:
+            versioned_transaction: VersionedTransaction to serialize.
+
+        Returns:
+            Base64-encoded string representation of the transaction.
+        """
         return base64.b64encode(bytes(versioned_transaction)).decode("utf-8")
 
 
@@ -102,12 +162,29 @@ class JupiterClient(_CoreJupiterClient):
         private_key_env_var: str = "PRIVATE_KEY",
         client_kwargs: Optional[dict[str, Any]] = None,
     ):
+        """
+        Initialize the synchronous Jupiter client.
+
+        Args:
+            api_key: Optional API key for enhanced access to Jupiter API.
+            private_key_env_var: Name of environment variable containing the
+                private key.
+            client_kwargs: Optional kwargs to pass to curl_cffi Session.
+                Common options include 'proxies', 'timeout', 'impersonate'.
+        """
         super().__init__(api_key, private_key_env_var)
         kwargs = client_kwargs or {}
-        kwargs.setdefault("impersonate", "chrome110")
+        # Use realworld random browser impersonation based on market share
+        # if not specified
+        kwargs.setdefault("impersonate", "realworld")
         self.client = requests.Session(**kwargs)
 
     def close(self) -> None:
+        """
+        Close the underlying HTTP session.
+
+        Always call this method when done to properly cleanup resources.
+        """
         self.client.close()
 
 
@@ -123,14 +200,37 @@ class AsyncJupiterClient(_CoreJupiterClient):
         private_key_env_var: str = "PRIVATE_KEY",
         client_kwargs: Optional[dict[str, Any]] = None,
     ):
+        """
+        Initialize the asynchronous Jupiter client.
+
+        Args:
+            api_key: Optional API key for enhanced access to Jupiter API.
+            private_key_env_var: Name of environment variable containing the
+                private key.
+            client_kwargs: Optional kwargs to pass to curl_cffi AsyncSession.
+                Common options include 'proxies', 'timeout', 'impersonate'.
+        """
         super().__init__(api_key, private_key_env_var)
         kwargs = client_kwargs or {}
-        kwargs.setdefault("impersonate", "chrome110")
+        # Use realworld random browser impersonation based on market share
+        # if not specified
+        kwargs.setdefault("impersonate", "realworld")
         self.client = AsyncSession(**kwargs)
 
     async def close(self) -> None:
+        """
+        Close the underlying HTTP session.
+
+        Always call this method when done to properly cleanup resources.
+        """
         await self.client.close()
 
     # Override get_public_key for async context consistency
     async def get_public_key(self) -> str:  # type: ignore[override]
+        """
+        Get the public key from the loaded private key.
+
+        Returns:
+            Public key as a base58-encoded string.
+        """
         return super().get_public_key()

jup_python_sdk/models/common/dex_enum.py

@@ -3,6 +3,13 @@ from urllib.parse import quote
 
 
 class DexEnum(str, Enum):
+    """
+    Enumeration of supported DEXes (Decentralized Exchanges) on Jupiter.
+
+    Each value represents a different liquidity source that Jupiter can route through.
+    The string values are URL-encoded when used in API requests.
+    """
+
     WOOFI = "Woofi"
     PUMP_FUN = "Pump.fun"
     WHIRLPOOL = "Whirlpool"
@@ -54,4 +61,10 @@ class DexEnum(str, Enum):
     GUACSWAP = "Guacswap"
 
     def __str__(self) -> str:
+        """
+        Return URL-encoded string representation of the DEX name.
+
+        Returns:
+            URL-encoded DEX name suitable for API requests.
+        """
         return quote(self.value)

jup_python_sdk/models/ultra_api/ultra_execute_request_model.py

@@ -5,10 +5,24 @@ from pydantic.alias_generators import to_camel
 
 
 class UltraExecuteRequest(BaseModel):
+    """
+    Pydantic model for executing a previously created order.
+
+    Attributes:
+        signed_transaction: Base64-encoded signed transaction string.
+        request_id: The request ID returned from the order endpoint.
+    """
+
     signed_transaction: str
     request_id: str
 
     def to_dict(self) -> dict[str, Any]:
+        """
+        Convert the model to a dictionary with camelCase keys.
+
+        Returns:
+            Dict with camelCase keys suitable for API requests.
+        """
         params = self.model_dump(exclude_none=True)
 
         camel_case_params = {to_camel(key): value for key, value in params.items()}

jup_python_sdk/models/ultra_api/ultra_order_request_model.py

@@ -5,6 +5,18 @@ from pydantic.alias_generators import to_camel
 
 
 class UltraOrderRequest(BaseModel):
+    """
+    Pydantic model for creating swap orders on Jupiter Ultra API.
+
+    Attributes:
+        input_mint: Mint address of the input token.
+        output_mint: Mint address of the output token.
+        amount: Amount to swap in the smallest unit (e.g., lamports for SOL).
+        taker: Optional public key of the taker (usually your wallet address).
+        referral_account: Optional referral account address for fee sharing.
+        referral_fee: Optional referral fee in basis points (1 bp = 0.01%).
+    """
+
     input_mint: str
     output_mint: str
     amount: int
@@ -13,6 +25,12 @@ class UltraOrderRequest(BaseModel):
     referral_fee: Optional[int] = None
 
     def to_dict(self) -> dict[str, Any]:
+        """
+        Convert the model to a dictionary with camelCase keys.
+
+        Returns:
+            Dict with camelCase keys suitable for API requests.
+        """
         params = self.model_dump(exclude_none=True)
 
         camel_case_params = {to_camel(key): value for key, value in params.items()}

solanab_jup_python_sdk-2.0.6.dist-info/METADATA

@@ -0,0 +1,592 @@
+Metadata-Version: 2.4
+Name: solanab-jup-python-sdk
+Version: 2.0.6
+Summary: High-performance sync/async Python SDK for Jupiter Exchange APIs, powered by curl_cffi.
+Project-URL: homepage, https://github.com/solanab/jup-python-sdk
+Project-URL: repository, https://github.com/solanab/jup-python-sdk
+Author-email: Fiji <charismoutafidis@gmail.com>, solanab <whiredj@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: jupiter,sdk,solana
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: base58>=2.1.1
+Requires-Dist: curl-cffi>=0.12
+Requires-Dist: pydantic>=2.11.3
+Requires-Dist: solders>=0.26.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: mypy>=1.15.0; extra == 'dev'
+Requires-Dist: pip-audit>=2.8.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.7; extra == 'dev'
+Requires-Dist: pytest-cov>=6.1.1; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: python-dotenv>=1.1.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# **Jupiter Python SDK**
+
+[![PyPI version](https://badge.fury.io/py/solanab-jup-python-sdk.svg)](https://badge.fury.io/py/solanab-jup-python-sdk)
+[![Python](https://img.shields.io/pypi/pyversions/solanab-jup-python-sdk.svg)](https://pypi.org/project/solanab-jup-python-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A high-performance, async-first Python SDK for seamless interaction with the Jupiter Ultra API, powered by `curl_cffi` for maximum speed and flexibility.
+
+With Ultra API, you don't need to manage or connect to any RPC endpoints, or deal with complex configurations. Everything from getting quotes to transaction execution happens directly through a powerful API.
+
+Or as we like to say around here: **"RPCs are for NPCs."**
+
+## **Table of Contents**
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [API Reference](#api-reference)
+- [Usage Examples](#usage-examples)
+- [Best Practices](#best-practices)
+- [Advanced Usage](#advanced-usage)
+- [Error Handling](#error-handling)
+- [Contributing](#contributing)
+- [Resources](#resources)
+
+## **Features**
+
+- 🚀 **High Performance**: Built on `curl_cffi` for blazing-fast HTTP requests
+- 🔄 **Async/Sync Support**: Both asynchronous and synchronous clients available
+- 🛡️ **Token Safety**: Built-in shield API for token security warnings
+- 💰 **Balance Checking**: Easy balance retrieval for any Solana address
+- 🔧 **Advanced Configuration**: Support for proxies, custom DNS, and more
+- 📦 **Type Safety**: Full type hints with Pydantic models
+- 🎯 **Zero Configuration**: Works out of the box with minimal setup
+
+## **Installation**
+
+```bash
+pip install solanab-jup-python-sdk
+```
+
+### Requirements
+
+- Python 3.9 or higher
+- A Solana wallet private key (for transaction signing)
+
+## **Quick Start**
+
+### Async Example
+
+```python
+import asyncio
+from jup_python_sdk.clients.ultra_api_client import AsyncUltraApiClient
+from jup_python_sdk.models.ultra_api.ultra_order_request_model import UltraOrderRequest
+
+async def main():
+    # Initialize the async client
+    client = AsyncUltraApiClient()
+
+    # Create a swap order
+    order_request = UltraOrderRequest(
+        input_mint="So11111111111111111111111111111111111111112",  # WSOL
+        output_mint="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  # USDC
+        amount=10000000,  # 0.01 WSOL
+        taker=await client.get_public_key(),
+    )
+
+    try:
+        # Execute the swap
+        response = await client.order_and_execute(order_request)
+        print(f"Transaction: https://solscan.io/tx/{response['signature']}")
+    finally:
+        await client.close()
+
+asyncio.run(main())
+```
+
+### Sync Example
+
+```python
+from jup_python_sdk.clients.ultra_api_client import UltraApiClient
+from jup_python_sdk.models.ultra_api.ultra_order_request_model import UltraOrderRequest
+
+# Initialize the sync client
+client = UltraApiClient()
+
+# Create and execute a swap
+order_request = UltraOrderRequest(
+    input_mint="So11111111111111111111111111111111111111112",  # WSOL
+    output_mint="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  # USDC
+    amount=10000000,  # 0.01 WSOL
+    taker=client.get_public_key(),
+)
+
+response = client.order_and_execute(order_request)
+print(f"Transaction: https://solscan.io/tx/{response['signature']}")
+client.close()
+```
+
+## **Configuration**
+
+### Environment Variables
+
+Set up your private key as an environment variable:
+
+```bash
+# Base58 format (standard Solana format)
+export PRIVATE_KEY=your_base58_private_key_here
+
+# OR as a uint8 array
+export PRIVATE_KEY=[10,229,131,132,213,96,74,22,...]
+```
+
+### Client Configuration
+
+```python
+from jup_python_sdk.clients.ultra_api_client import AsyncUltraApiClient
+
+# With API key (for enhanced access)
+client = AsyncUltraApiClient(
+    api_key="YOUR_API_KEY",  # Get from https://portal.jup.ag/onboard
+    private_key_env_var="CUSTOM_PRIVATE_KEY"  # Custom env var name
+)
+
+# With custom client configuration
+client = AsyncUltraApiClient(
+    client_kwargs={
+        "timeout": 30,  # 30 seconds timeout
+        "impersonate": "chrome110",  # Browser impersonation
+        "verify": True,  # SSL verification
+    }
+)
+```
+
+## **API Reference**
+
+### UltraApiClient / AsyncUltraApiClient
+
+The main client classes for interacting with the Jupiter Ultra API.
+
+#### Methods
+
+##### `order(request: UltraOrderRequest) -> dict`
+
+Get a swap order from the Jupiter Ultra API.
+
+**Parameters:**
+
+- `request`: An `UltraOrderRequest` object containing:
+  - `input_mint` (str): Input token mint address
+  - `output_mint` (str): Output token mint address
+  - `amount` (int): Amount in smallest unit (e.g., lamports for SOL)
+  - `taker` (str, optional): Taker's public key
+  - `referral_account` (str, optional): Referral account address
+  - `referral_fee` (int, optional): Referral fee in basis points
+
+**Returns:** Dict containing order details including `requestId` and `transaction`
+
+##### `execute(request: UltraExecuteRequest) -> dict`
+
+Execute a previously created order.
+
+**Parameters:**
+
+- `request`: An `UltraExecuteRequest` object containing:
+  - `request_id` (str): The request ID from the order
+  - `signed_transaction` (str): Base64-encoded signed transaction
+
+**Returns:** Dict containing execution result including `signature` and `status`
+
+##### `order_and_execute(request: UltraOrderRequest) -> dict`
+
+Create and execute an order in a single call.
+
+**Parameters:**
+
+- `request`: Same as `order()` method
+
+**Returns:** Dict containing execution result including `signature` and `status`
+
+##### `balances(address: str) -> dict`
+
+Get token balances for a Solana address.
+
+**Parameters:**
+
+- `address` (str): Solana public key address
+
+**Returns:** Dict mapping token symbols to balance details:
+
+```python
+{
+    "SOL": {
+        "amount": "100000000",
+        "uiAmount": 0.1,
+        "slot": 123456,
+        "isFrozen": False
+    }
+}
+```
+
+##### `shield(mints: list[str]) -> dict`
+
+Check tokens for safety warnings.
+
+**Parameters:**
+
+- `mints` (list[str]): List of token mint addresses to check
+
+**Returns:** Dict containing warnings for each mint:
+
+```python
+{
+    "warnings": {
+        "mint_address": [
+            {
+                "type": "warning_type",
+                "message": "Warning description"
+            }
+        ]
+    }
+}
+```
+
+### Models
+
+#### UltraOrderRequest
+
+Pydantic model for creating swap orders.
+
+```python
+UltraOrderRequest(
+    input_mint="So11111111111111111111111111111111111111112",
+    output_mint="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+    amount=10000000,
+    taker="your_public_key",
+    referral_account="optional_referral_address",
+    referral_fee=50  # 0.5% in basis points
+)
+```
+
+#### UltraExecuteRequest
+
+Pydantic model for executing orders.
+
+```python
+UltraExecuteRequest(
+    request_id="order_request_id",
+    signed_transaction="base64_encoded_signed_transaction"
+)
+```
+
+## **Usage Examples**
+
+### Check Token Balances
+
+```python
+import asyncio
+from jup_python_sdk.clients.ultra_api_client import AsyncUltraApiClient
+
+async def check_balances():
+    client = AsyncUltraApiClient()
+
+    # Get your wallet address
+    address = await client.get_public_key()
+
+    # Fetch balances
+    balances = await client.balances(address)
+
+    for token, details in balances.items():
+        print(f"{token}: {details['uiAmount']} (frozen: {details['isFrozen']})")
+
+    await client.close()
+
+asyncio.run(check_balances())
+```
+
+### Check Token Safety
+
+```python
+import asyncio
+from jup_python_sdk.clients.ultra_api_client import AsyncUltraApiClient
+
+async def check_token_safety():
+    client = AsyncUltraApiClient()
+
+    # Popular tokens to check
+    mints = [
+        "So11111111111111111111111111111111111111112",  # WSOL
+        "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  # USDC
+        "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",  # BONK
+    ]
+
+    shield_response = await client.shield(mints)
+
+    for mint, warnings in shield_response.get("warnings", {}).items():
+        if warnings:
+            print(f"⚠️ {mint} has warnings:")
+            for warning in warnings:
+                print(f"  - {warning['type']}: {warning['message']}")
+        else:
+            print(f"✅ {mint} appears safe")
+
+    await client.close()
+
+asyncio.run(check_token_safety())
+```
+
+### Concurrent Operations
+
+```python
+import asyncio
+from jup_python_sdk.clients.ultra_api_client import AsyncUltraApiClient
+
+async def concurrent_operations():
+    client = AsyncUltraApiClient()
+
+    # Define multiple tokens to check
+    tokens = [
+        "So11111111111111111111111111111111111111112",
+        "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+        "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
+    ]
+
+    # Create tasks for concurrent execution
+    tasks = []
+    for token in tokens:
+        task = client.shield([token])
+        tasks.append(task)
+
+    # Execute all requests concurrently
+    results = await asyncio.gather(*tasks)
+
+    # Process results
+    for token, result in zip(tokens, results):
+        print(f"Token {token}: {result}")
+
+    await client.close()
+
+asyncio.run(concurrent_operations())
+```
+
+## **Best Practices**
+
+### 1. Always Close Clients
+
+```python
+# Using try/finally
+client = AsyncUltraApiClient()
+try:
+    # Your code here
+    pass
+finally:
+    await client.close()
+
+# Or using async context manager (if implemented)
+async with AsyncUltraApiClient() as client:
+    # Your code here
+    pass
+```
+
+### 2. Error Handling
+
+```python
+try:
+    response = await client.order_and_execute(order_request)
+
+    if response.get("status") == "Failed":
+        print(f"Transaction failed: {response.get('error')}")
+    else:
+        print(f"Success: {response['signature']}")
+
+except Exception as e:
+    print(f"Error occurred: {e}")
+```
+
+### 3. Rate Limiting
+
+```python
+import asyncio
+
+# Use semaphore to limit concurrent requests
+semaphore = asyncio.Semaphore(5)  # Max 5 concurrent requests
+
+async def rate_limited_request(client, mint):
+    async with semaphore:
+        return await client.shield([mint])
+```
+
+### 4. Retry Logic
+
+```python
+import asyncio
+from typing import Optional
+
+async def retry_request(func, max_retries=3, delay=1.0):
+    for attempt in range(max_retries):
+        try:
+            return await func()
+        except Exception as e:
+            if attempt == max_retries - 1:
+                raise
+            await asyncio.sleep(delay * (attempt + 1))
+```
+
+### 5. Token Amount Calculations
+
+```python
+# Always work with the smallest unit (lamports for SOL)
+sol_amount = 0.01  # SOL
+lamports = int(sol_amount * 10**9)  # Convert to lamports
+
+# For other tokens, check their decimals
+usdc_amount = 10.0  # USDC
+usdc_smallest_unit = int(usdc_amount * 10**6)  # USDC has 6 decimals
+```
+
+## **Advanced Usage**
+
+### Using Proxies
+
+```python
+# SOCKS5 proxy
+proxies = {"https": "socks5://user:pass@host:port"}
+client = AsyncUltraApiClient(client_kwargs={"proxies": proxies})
+
+# HTTP proxy
+proxies = {
+    "http": "http://user:pass@proxy.example.com:8080",
+    "https": "http://user:pass@proxy.example.com:8080",
+}
+client = AsyncUltraApiClient(client_kwargs={"proxies": proxies})
+```
+
+### Custom DNS Resolution
+
+```python
+# Force specific DNS resolution
+client = AsyncUltraApiClient(
+    client_kwargs={
+        "resolve": ["api.jup.ag:443:1.2.3.4"],
+        "dns_servers": ["1.1.1.1", "1.0.0.1"],
+    }
+)
+```
+
+### Custom Headers and Browser Impersonation
+
+```python
+# Default: Uses "realworld" - randomly selects browser based on market share
+client = AsyncUltraApiClient()
+
+# Specify a specific browser version
+client = AsyncUltraApiClient(
+    client_kwargs={
+        "impersonate": "chrome124",  # Specific browser version
+    }
+)
+
+# Use latest version of a browser
+client = AsyncUltraApiClient(
+    client_kwargs={
+        "impersonate": "chrome",  # Latest Chrome
+    }
+)
+
+# Custom headers with browser impersonation
+client = AsyncUltraApiClient(
+    client_kwargs={
+        "impersonate": "safari",  # Latest Safari
+        "headers": {
+            "Accept-Language": "en-US,en;q=0.9",
+        }
+    }
+)
+```
+
+**Note**: By default, the SDK uses `impersonate="realworld"` which randomly selects a browser version based on current market share. This helps avoid detection and provides better anonymity.
+
+## **Error Handling**
+
+The SDK may raise various exceptions:
+
+### Common Exceptions
+
+```python
+try:
+    response = await client.order_and_execute(order_request)
+except ValueError as e:
+    # Invalid private key format
+    print(f"Configuration error: {e}")
+except requests.HTTPError as e:
+    # HTTP errors (4xx, 5xx)
+    print(f"API error: {e}")
+except Exception as e:
+    # Other errors
+    print(f"Unexpected error: {e}")
+```
+
+### Response Status Handling
+
+```python
+response = await client.order_and_execute(order_request)
+
+if response.get("status") == "Failed":
+    error_code = response.get("code")
+    error_message = response.get("error")
+
+    if error_code == "INSUFFICIENT_BALANCE":
+        print("Not enough balance for the swap")
+    elif error_code == "SLIPPAGE_EXCEEDED":
+        print("Slippage tolerance exceeded")
+    else:
+        print(f"Transaction failed: {error_message}")
+```
+
+## **Contributing**
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/solanab/jup-python-sdk.git
+cd jup-python-sdk
+
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run linters
+ruff check .
+ruff format .
+```
+
+## **Resources**
+
+- [Ultra API Documentation](https://dev.jup.ag/docs/ultra-api/)
+- [Jupiter Portal](https://portal.jup.ag/onboard) - Get your API key
+- [Discord Community](https://discord.gg/jup)
+- [GitHub Repository](https://github.com/solanab/jup-python-sdk)
+
+## **License**
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## **Disclaimer**
+
+🚨 **This project is actively maintained.**
+While we strive for stability, the SDK is under active development. We recommend staying updated with the latest releases. Important updates will be announced in the [Discord server](https://discord.gg/jup).

{solanab_jup_python_sdk-2.0.3.dist-info → solanab_jup_python_sdk-2.0.6.dist-info}/RECORD

@@ -1,14 +1,14 @@
 jup_python_sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 jup_python_sdk/clients/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-jup_python_sdk/clients/jupiter_client.py,sha256=3zX4e9iEmLP5KqSzmHt2vrry4UVbAKLaKSir6HFLf-U,4607
+jup_python_sdk/clients/jupiter_client.py,sha256=9XXruDRIyFs8n3H2RsU0FhaihF--9mzNwMDs0ldiYPA,7762
 jup_python_sdk/clients/ultra_api_client.py,sha256=jgNgf04bDSJxu8MY1oGRx3Bxemyy4B4y5eUuQBN61qA,6750
 jup_python_sdk/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 jup_python_sdk/models/common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-jup_python_sdk/models/common/dex_enum.py,sha256=javWWg5TTbPAVNhoBQJlaVEUlpTkwfin7SO4xGKToaI,1510
+jup_python_sdk/models/common/dex_enum.py,sha256=ie9bTkVYTdNZijwLB4mCZ-AN3g-cV5OahXke1z8V0PY,1921
 jup_python_sdk/models/ultra_api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-jup_python_sdk/models/ultra_api/ultra_execute_request_model.py,sha256=jvoPgCa5QxUFuMmZ7brFPcAyQzU7WgxtnwXH1KgxIPM,403
-jup_python_sdk/models/ultra_api/ultra_order_request_model.py,sha256=DSxQtLALHgHGwr5gw3Iu1fkg4LbydUUmEo-aHF55G4Y,534
-solanab_jup_python_sdk-2.0.3.dist-info/METADATA,sha256=OoA0fmw4M3EEXukcMU_LcViHFLl-oa1_vxdc6U6fh2A,5992
-solanab_jup_python_sdk-2.0.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-solanab_jup_python_sdk-2.0.3.dist-info/licenses/LICENSE,sha256=3va7FgUbc2istAEEchr1jkoUjBoSYPMkguY1BGuHt2U,1061
-solanab_jup_python_sdk-2.0.3.dist-info/RECORD,,
+jup_python_sdk/models/ultra_api/ultra_execute_request_model.py,sha256=jgvBjzVwslq1aItsxOJX9BWechEGiJq8Nr4H3om352I,806
+jup_python_sdk/models/ultra_api/ultra_order_request_model.py,sha256=gv_xxvVjQVbD9NSJa3d06WMe9MkTK31KkKmKq0e7UOc,1221
+solanab_jup_python_sdk-2.0.6.dist-info/METADATA,sha256=P0T43FXZAWo-Vm8Fx_zMWNacHCZhqbYxcTMieFHOIMQ,15957
+solanab_jup_python_sdk-2.0.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+solanab_jup_python_sdk-2.0.6.dist-info/licenses/LICENSE,sha256=3va7FgUbc2istAEEchr1jkoUjBoSYPMkguY1BGuHt2U,1061
+solanab_jup_python_sdk-2.0.6.dist-info/RECORD,,

solanab_jup_python_sdk-2.0.3.dist-info/METADATA

@@ -1,158 +0,0 @@
-Metadata-Version: 2.4
-Name: solanab-jup-python-sdk
-Version: 2.0.3
-Summary: High-performance sync/async Python SDK for Jupiter Exchange APIs, powered by curl_cffi.
-Project-URL: homepage, https://github.com/solanab/jup-python-sdk
-Project-URL: repository, https://github.com/solanab/jup-python-sdk
-Author-email: Fiji <charismoutafidis@gmail.com>, solanab <whiredj@gmail.com>
-License: MIT
-License-File: LICENSE
-Keywords: jupiter,sdk,solana
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.9
-Requires-Dist: base58>=2.1.1
-Requires-Dist: curl-cffi>=0.12
-Requires-Dist: pydantic>=2.11.3
-Requires-Dist: solana>=0.36.6
-Requires-Dist: solders>=0.26.0
-Provides-Extra: dev
-Requires-Dist: bandit>=1.7; extra == 'dev'
-Requires-Dist: black>=25.1.0; extra == 'dev'
-Requires-Dist: flake8>=7.1.1; extra == 'dev'
-Requires-Dist: isort>=6.0.0; extra == 'dev'
-Requires-Dist: mypy>=1.15.0; extra == 'dev'
-Requires-Dist: pre-commit>=4.1.0; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23.7; extra == 'dev'
-Requires-Dist: pytest-cov>=6.1.1; extra == 'dev'
-Requires-Dist: pytest>=8.3.4; extra == 'dev'
-Requires-Dist: python-dotenv>=1.1.0; extra == 'dev'
-Requires-Dist: responses>=0.25.6; extra == 'dev'
-Requires-Dist: safety>=2.3; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# **Jup Python SDK**
-
-A high-performance, async-first Python SDK for seamless interaction with the Jupiter Ultra API, powered by `curl_cffi` for maximum speed and flexibility.<br>
-With Ultra API, you don't need to manage or connect to any RPC endpoints, or deal with complex configurations.<br>
-Everything from getting quotes to transaction execution happens directly through a powerful API.<br>
-
-Or as we like to say around here:<br>
-**"RPCs are for NPCs."**
-
-For a deeper understanding of the Ultra API, including its features and benefits, check out the [Ultra API Docs](https://dev.jup.ag/docs/ultra-api/).
-
-## **Installation**
-
-To install the SDK in your project, run:
-```sh
-pip install jup-python-sdk
-```
-
-## **Quick Start (Async)**
-
-Below is a simple asynchronous example to fetch and execute an Ultra order.
-
-```python
-import asyncio
-from dotenv import load_dotenv
-from jup_python_sdk.clients.ultra_api_client import AsyncUltraApiClient
-from jup_python_sdk.models.ultra_api.ultra_order_request_model import UltraOrderRequest
-
-async def main():
-   load_dotenv()
-   # Note: For async client, methods are awaited.
-   client = AsyncUltraApiClient()
-
-   order_request = UltraOrderRequest(
-      input_mint="So11111111111111111111111111111111111111112",  # WSOL
-      output_mint="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  # USDC
-      amount=10000000,  # 0.01 WSOL
-      taker=await client.get_public_key(),
-   )
-
-   try:
-      client_response = await 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:
-      await client.close()
-
-if __name__ == "__main__":
-   asyncio.run(main())
-```
-
-> **Note**: A synchronous client (`UltraApiClient`) is also available. See the [examples](./examples) folder for both sync and async usage.
-
-## **Setup Instructions**
-
-Before using the SDK, please ensure you have completed the following steps:
-
-1. **Environment Variables**:  
-   Set up your required environment variables.  
-   The SDK supports both base58 string and uint8 array formats for your private key.
-   ```sh
-   # Base58 format
-   export PRIVATE_KEY=your_base58_private_key_here
-
-   # OR as a uint8 array
-   export PRIVATE_KEY=[10,229,131,132,213,96,74,22,...]
-   ```
-   
-> **Note**: `PRIVATE_KEY` can be either a base58-encoded string (default Solana format), or a uint8 array (e.g. `[181,99,240,...]`). The SDK will automatically detect and parse the format.
-
-2. **Optional Configuration**:  
-   Depending on your credentials and setup, you have a couple of options for initializing the `UltraApiClient`:
-   - **API Key**: Use an API key from [the Jupiter Portal](https://portal.jup.ag/onboard) for enhanced access. This will use the `https://api.jup.ag/` endpoint.
-   - **Custom Private Key Env Var**: Specify a different environment variable name for your private key.
-
-    ```python
-    from jup_python_sdk.clients.ultra_api_client import AsyncUltraApiClient
-
-    client = AsyncUltraApiClient(
-        api_key="YOUR_API_KEY",
-        private_key_env_var="YOUR_CUSTOM_ENV_VAR"
-    )
-    ```
-
-## **Advanced Configuration (Proxies, Custom DNS)**
-
-The SDK is built on `curl_cffi`, allowing you to pass any valid `curl_cffi` client parameter during initialization for advanced network control.
-
-### Using a SOCKS5 Proxy
-
-```python
-from jup_python_sdk.clients.ultra_api_client import AsyncUltraApiClient
-
-proxies = {"httpss": "socks5://user:pass@host:port"}
-client = AsyncUltraApiClient(client_kwargs={"proxies": proxies, "impersonate": "chrome110"})
-```
-
-### Using Custom DNS Resolution
-
-This is useful for bypassing local DNS caches or using a specialized DNS resolver.
-
-```python
-from jup_python_sdk.clients.ultra_api_client import AsyncUltraApiClient
-
-# Tell the client to resolve jup.ag to a specific IP address
-resolve_string = "jup.ag:443:1.2.3.4"
-client = AsyncUltraApiClient(client_kwargs={"resolve": [resolve_string]})
-```
-
-## **Disclaimer**
-
-🚨 **This project is actively worked on.**  
-While we don't expect breaking changes as the SDK evolves, we recommend you stay updated with the latest releases.  
-Any important updates will be announced in the [Discord server](https://discord.gg/jup).