jupiter-swap-python 0.1.0__py3-none-any.whl

jupiter_swap/__init__.py

@@ -0,0 +1,19 @@
+"""
+jupiter-swap-python — async Jupiter DEX aggregator client for Python.
+"""
+
+from .client import JupiterClient
+from .models import QuoteResponse, SwapResponse, TokenInfo, UltraOrder
+from .tokens import TokenClient
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "JupiterClient",
+    "TokenClient",
+    "QuoteResponse",
+    "SwapResponse",
+    "UltraOrder",
+    "TokenInfo",
+    "__version__",
+]

jupiter_swap/client.py

@@ -0,0 +1,397 @@
+"""
+Jupiter DEX aggregator client — V6 quote/swap and Ultra API.
+
+Supports:
+- Quote: get the best swap route and price
+- Swap: build a transaction from a quote
+- Ultra: combined quote + swap with MEV protection
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any
+
+import httpx
+
+from .models import QuoteResponse, SwapResponse, UltraOrder
+
+logger = logging.getLogger(__name__)
+
+# Jupiter public API base URLs
+_DEFAULT_V6_URL = "https://quote-api.jup.ag/v6"
+_DEFAULT_ULTRA_URL = "https://api.jup.ag/ultra/v1"
+
+
+class JupiterError(Exception):
+    """Raised when a Jupiter API call fails."""
+
+    def __init__(self, message: str, status_code: int = 0, body: str = "") -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class JupiterClient:
+    """
+    Async client for the Jupiter DEX aggregator.
+
+    Usage::
+
+        async with JupiterClient() as jup:
+            quote = await jup.get_quote("So11...", "EPjFW...", 1_000_000)
+            swap = await jup.get_swap_transaction(quote, "YourPublicKey...")
+
+    Handles 429 rate limiting with automatic retry and exponential backoff.
+    """
+
+    __slots__ = (
+        "_v6_url",
+        "_ultra_url",
+        "_api_key",
+        "_http",
+        "_max_retries",
+        "_last_request_time",
+        "_min_interval",
+    )
+
+    def __init__(
+        self,
+        *,
+        api_key: str = "",
+        v6_url: str = _DEFAULT_V6_URL,
+        ultra_url: str = _DEFAULT_ULTRA_URL,
+        max_retries: int = 3,
+        requests_per_second: float = 10.0,
+    ) -> None:
+        """
+        Initialise the Jupiter client.
+
+        Args:
+            api_key: Optional Jupiter API key for higher rate limits.
+            v6_url: Base URL for the V6 quote/swap API.
+            ultra_url: Base URL for the Ultra swap API.
+            max_retries: Max retry attempts on 429 responses.
+            requests_per_second: Simple rate limiter — minimum interval between requests.
+        """
+        self._v6_url = v6_url.rstrip("/")
+        self._ultra_url = ultra_url.rstrip("/")
+        self._api_key = api_key
+        self._http: httpx.AsyncClient | None = None
+        self._max_retries = max_retries
+        self._last_request_time: float = 0.0
+        self._min_interval: float = 1.0 / requests_per_second if requests_per_second > 0 else 0.0
+
+    # -- Lifecycle -----------------------------------------------------------
+
+    async def __aenter__(self) -> JupiterClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+    async def connect(self) -> None:
+        """Open the HTTP connection pool."""
+        if self._http is None:
+            self._http = httpx.AsyncClient(timeout=httpx.Timeout(15.0))
+
+    async def close(self) -> None:
+        """Close the HTTP connection pool."""
+        if self._http:
+            await self._http.aclose()
+            self._http = None
+
+    # -- V6 Quote/Swap -------------------------------------------------------
+
+    async def get_quote(
+        self,
+        input_mint: str,
+        output_mint: str,
+        amount: int,
+        slippage_bps: int = 50,
+        *,
+        swap_mode: str = "ExactIn",
+        restrict_intermediate_tokens: bool = True,
+        max_accounts: int = 64,
+    ) -> QuoteResponse:
+        """
+        Get the best swap route from Jupiter.
+
+        Args:
+            input_mint: Source token mint address.
+            output_mint: Destination token mint address.
+            amount: Amount in smallest unit (lamports for SOL).
+            slippage_bps: Maximum slippage in basis points (1 bps = 0.01%).
+            swap_mode: "ExactIn" or "ExactOut".
+            restrict_intermediate_tokens: Avoid illiquid intermediate hops.
+            max_accounts: Max accounts in the route (higher = more complex routes).
+
+        Returns:
+            QuoteResponse with route details and expected output amount.
+
+        Raises:
+            JupiterError: If the quote request fails.
+        """
+        params: dict[str, str | int] = {
+            "inputMint": input_mint,
+            "outputMint": output_mint,
+            "amount": str(amount),
+            "slippageBps": slippage_bps,
+            "swapMode": swap_mode,
+        }
+        if restrict_intermediate_tokens:
+            params["restrictIntermediateTokens"] = "true"
+        if max_accounts != 64:
+            params["maxAccounts"] = str(max_accounts)
+
+        data = await self._request("GET", f"{self._v6_url}/quote", params=params)
+
+        return QuoteResponse(
+            input_mint=data.get("inputMint", input_mint),
+            output_mint=data.get("outputMint", output_mint),
+            in_amount=data.get("inAmount", str(amount)),
+            out_amount=data.get("outAmount", "0"),
+            price_impact_pct=data.get("priceImpactPct", "0"),
+            route_plan=data.get("routePlan", []),
+            other_amount_threshold=data.get("otherAmountThreshold", "0"),
+            swap_mode=data.get("swapMode", swap_mode),
+            slippage_bps=data.get("slippageBps", slippage_bps),
+            raw=data,
+        )
+
+    async def get_swap_transaction(
+        self,
+        quote: QuoteResponse,
+        user_public_key: str,
+        *,
+        wrap_and_unwrap_sol: bool = True,
+        priority_fee_lamports: int = 0,
+        dynamic_compute_unit_limit: bool = True,
+        priority_level: str = "veryHigh",
+    ) -> SwapResponse:
+        """
+        Build a swap transaction from a quote.
+
+        Args:
+            quote: A QuoteResponse from get_quote().
+            user_public_key: The wallet public key that will sign the tx.
+            wrap_and_unwrap_sol: Auto wrap/unwrap SOL ↔ WSOL.
+            priority_fee_lamports: Max priority fee in lamports (0 = use default).
+            dynamic_compute_unit_limit: Auto-optimize compute unit limit.
+            priority_level: Priority level — "medium", "high", "veryHigh".
+
+        Returns:
+            SwapResponse with the base64-encoded transaction.
+
+        Raises:
+            JupiterError: If the swap request fails.
+        """
+        max_fee = priority_fee_lamports if priority_fee_lamports > 0 else 1_000_000
+
+        body: dict[str, Any] = {
+            "quoteResponse": quote.raw,
+            "userPublicKey": user_public_key,
+            "wrapAndUnwrapSol": wrap_and_unwrap_sol,
+            "dynamicComputeUnitLimit": dynamic_compute_unit_limit,
+            "dynamicSlippage": True,
+            "prioritizationFeeLamports": {
+                "priorityLevelWithMaxLamports": {
+                    "maxLamports": max_fee,
+                    "priorityLevel": priority_level,
+                },
+            },
+        }
+
+        data = await self._request("POST", f"{self._v6_url}/swap", json=body)
+
+        return SwapResponse(
+            swap_transaction=data.get("swapTransaction", ""),
+            last_valid_block_height=data.get("lastValidBlockHeight", 0),
+            priority_fee_lamports=data.get("prioritizationFeeLamports", 0),
+            raw=data,
+        )
+
+    # -- Ultra API -----------------------------------------------------------
+
+    async def ultra_order(
+        self,
+        input_mint: str,
+        output_mint: str,
+        amount: int,
+        taker: str,
+        slippage_bps: int = 50,
+    ) -> UltraOrder:
+        """
+        Request a swap via Jupiter Ultra API (combined quote + swap).
+
+        Ultra provides:
+        - Built-in MEV protection
+        - Automatic priority fee optimisation
+        - Better routing engine
+        - Gasless mode support
+
+        Args:
+            input_mint: Source token mint address.
+            output_mint: Destination token mint address.
+            amount: Amount in smallest unit.
+            taker: Wallet public key of the swap taker.
+            slippage_bps: Maximum slippage in basis points.
+
+        Returns:
+            UltraOrder with a transaction ready to sign and execute.
+
+        Raises:
+            JupiterError: If the order request fails.
+        """
+        body: dict[str, Any] = {
+            "inputMint": input_mint,
+            "outputMint": output_mint,
+            "amount": str(amount),
+            "taker": taker,
+            "slippageBps": slippage_bps,
+        }
+
+        data = await self._request("POST", f"{self._ultra_url}/order", json=body)
+
+        return UltraOrder(
+            request_id=data.get("requestId", ""),
+            input_mint=data.get("inputMint", input_mint),
+            output_mint=data.get("outputMint", output_mint),
+            in_amount=data.get("inAmount", str(amount)),
+            out_amount=data.get("outAmount", "0"),
+            swap_transaction=data.get("transaction", ""),
+            swap_type=data.get("type", "swap"),
+            priority_fee_lamports=data.get("prioritizationFeeLamports", 0),
+            dynamic_slippage_bps=data.get("dynamicSlippageReport", {}).get(
+                "slippageBps", slippage_bps,
+            ),
+            raw=data,
+        )
+
+    async def ultra_execute(
+        self,
+        signed_transaction: str,
+        request_id: str,
+    ) -> str:
+        """
+        Execute a signed Ultra swap order.
+
+        Submit the signed transaction back to Jupiter Ultra for
+        execution with MEV protection and confirmation tracking.
+
+        Args:
+            signed_transaction: Base64-encoded signed transaction.
+            request_id: The request_id from the UltraOrder.
+
+        Returns:
+            Transaction signature string.
+
+        Raises:
+            JupiterError: If execution fails.
+        """
+        body = {
+            "signedTransaction": signed_transaction,
+            "requestId": request_id,
+        }
+
+        data = await self._request("POST", f"{self._ultra_url}/execute", json=body)
+
+        status = data.get("status", "")
+        tx_sig = data.get("signature", "")
+
+        if status == "Failed":
+            raise JupiterError(
+                f"Ultra swap execution failed: {data.get('error', 'unknown')}",
+            )
+
+        return tx_sig
+
+    # -- Internal ------------------------------------------------------------
+
+    def _auth_headers(self) -> dict[str, str]:
+        if self._api_key:
+            return {"x-api-key": self._api_key}
+        return {}
+
+    async def _rate_limit(self) -> None:
+        """Simple rate limiter — ensure minimum interval between requests."""
+        if self._min_interval <= 0:
+            return
+        now = time.monotonic()
+        elapsed = now - self._last_request_time
+        if elapsed < self._min_interval:
+            await asyncio.sleep(self._min_interval - elapsed)
+        self._last_request_time = time.monotonic()
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: dict | None = None,
+        json: dict | None = None,
+    ) -> dict:
+        """
+        Make an HTTP request with rate limiting and 429 retry.
+
+        Returns parsed JSON dict on success.
+        Raises JupiterError on failure.
+        """
+        if self._http is None:
+            raise JupiterError("Client not connected — call connect() or use async with")
+
+        await self._rate_limit()
+
+        last_status = 0
+        last_body = ""
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                if method == "GET":
+                    resp = await self._http.get(url, params=params, headers=self._auth_headers())
+                else:
+                    resp = await self._http.post(url, json=json, headers=self._auth_headers())
+
+                last_status = resp.status_code
+                last_body = resp.text[:500] if resp.status_code != 200 else ""
+
+                if resp.status_code == 200:
+                    return resp.json()
+
+                if resp.status_code == 429:
+                    retry_after = self._parse_retry_after(resp)
+                    wait = retry_after if retry_after else 0.5 * (attempt + 1)
+                    logger.warning(
+                        "Jupiter 429 rate limited (attempt %d/%d), waiting %.1fs",
+                        attempt + 1, self._max_retries + 1, wait,
+                    )
+                    await asyncio.sleep(wait)
+                    continue
+
+                # Non-retryable error
+                break
+
+            except httpx.TimeoutException as exc:
+                if attempt < self._max_retries:
+                    await asyncio.sleep(0.5 * (attempt + 1))
+                    continue
+                raise JupiterError(f"Request timed out: {exc}") from exc
+
+        raise JupiterError(
+            f"Jupiter API error (HTTP {last_status})",
+            status_code=last_status,
+            body=last_body,
+        )
+
+    @staticmethod
+    def _parse_retry_after(resp: httpx.Response) -> float | None:
+        header = resp.headers.get("Retry-After")
+        if not header:
+            return None
+        try:
+            return max(0.0, float(header))
+        except (TypeError, ValueError):
+            return None

jupiter_swap/models.py

@@ -0,0 +1,82 @@
+"""
+Data models for Jupiter API responses.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class QuoteResponse:
+    """Parsed quote from Jupiter V6 API."""
+
+    input_mint: str
+    output_mint: str
+    in_amount: str
+    out_amount: str
+    price_impact_pct: str = "0"
+    route_plan: list[dict] = field(default_factory=list)
+    other_amount_threshold: str = "0"
+    swap_mode: str = "ExactIn"
+    slippage_bps: int = 50
+    raw: dict = field(default_factory=dict, repr=False)
+
+    @property
+    def in_amount_float(self) -> float:
+        """Input amount as float (divide by decimals yourself)."""
+        try:
+            return float(self.in_amount)
+        except (TypeError, ValueError):
+            return 0.0
+
+    @property
+    def out_amount_float(self) -> float:
+        """Output amount as float (divide by decimals yourself)."""
+        try:
+            return float(self.out_amount)
+        except (TypeError, ValueError):
+            return 0.0
+
+
+@dataclass(slots=True)
+class SwapResponse:
+    """Parsed swap transaction from Jupiter V6 API."""
+
+    swap_transaction: str
+    last_valid_block_height: int = 0
+    priority_fee_lamports: int = 0
+    raw: dict = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True)
+class UltraOrder:
+    """Response from Jupiter Ultra API — combined quote + swap in one call."""
+
+    request_id: str
+    input_mint: str
+    output_mint: str
+    in_amount: str
+    out_amount: str
+    swap_transaction: str
+    swap_type: str = "swap"
+    priority_fee_lamports: int = 0
+    dynamic_slippage_bps: int = 0
+    raw: dict = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True)
+class TokenInfo:
+    """Token metadata from Jupiter Token API."""
+
+    address: str
+    name: str = ""
+    symbol: str = ""
+    decimals: int = 0
+    logo_uri: str = ""
+    tags: list[str] = field(default_factory=list)
+    daily_volume: float | None = None
+    freeze_authority: str | None = None
+    mint_authority: str | None = None
+    is_verified: bool = False
+    is_banned: bool = False

jupiter_swap/tokens.py

@@ -0,0 +1,232 @@
+"""
+Jupiter Token API client — token verification, metadata, and banned detection.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import httpx
+
+from .models import TokenInfo
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_TOKEN_URL = "https://tokens.jup.ag"
+
+# Cache TTLs
+_TOKEN_INFO_TTL: float = 300.0
+_BANNED_LIST_TTL: float = 600.0
+
+
+class TokenClient:
+    """
+    Async client for the Jupiter Token API.
+
+    Provides token metadata, verification status, and banned token detection.
+
+    Usage::
+
+        async with TokenClient() as tokens:
+            info = await tokens.get_token_info("EPjFWdd5...")
+            print(info.symbol, info.is_verified)
+
+            is_scam = await tokens.is_banned("ScamMint...")
+    """
+
+    __slots__ = (
+        "_base_url",
+        "_api_key",
+        "_http",
+        "_banned_mints",
+        "_banned_loaded",
+        "_cache",
+        "_cache_ttl",
+    )
+
+    def __init__(
+        self,
+        *,
+        base_url: str = _DEFAULT_TOKEN_URL,
+        api_key: str = "",
+        cache_ttl: float = _TOKEN_INFO_TTL,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._http: httpx.AsyncClient | None = None
+        self._banned_mints: set[str] = set()
+        self._banned_loaded: bool = False
+        self._cache: dict[str, tuple[float, Any]] = {}
+        self._cache_ttl = cache_ttl
+
+    # -- Lifecycle -----------------------------------------------------------
+
+    async def __aenter__(self) -> TokenClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+    async def connect(self) -> None:
+        """Open HTTP client and preload the banned token list."""
+        headers: dict[str, str] = {}
+        if self._api_key:
+            headers["x-api-key"] = self._api_key
+        self._http = httpx.AsyncClient(
+            timeout=httpx.Timeout(15.0),
+            headers=headers,
+        )
+        await self._refresh_banned_list()
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._http:
+            await self._http.aclose()
+            self._http = None
+
+    # -- Public API ----------------------------------------------------------
+
+    async def get_token_info(self, mint: str) -> TokenInfo:
+        """
+        Get token metadata and verification status.
+
+        Args:
+            mint: Token mint address.
+
+        Returns:
+            TokenInfo with name, symbol, decimals, verification flags.
+
+        Raises:
+            httpx.HTTPError: On network failure.
+        """
+        cached = self._get_cached(f"token:{mint}")
+        if cached is not None:
+            return cached
+
+        if self._http is None:
+            raise RuntimeError("TokenClient not connected — call connect() first")
+
+        resp = await self._http.get(f"{self._base_url}/tokens/v1/{mint}")
+
+        if resp.status_code == 404:
+            token = TokenInfo(
+                address=mint,
+                is_verified=False,
+                is_banned=mint in self._banned_mints,
+            )
+            self._set_cached(f"token:{mint}", token)
+            return token
+
+        resp.raise_for_status()
+
+        data = resp.json()
+        tags = data.get("tags", [])
+        token = TokenInfo(
+            address=data.get("address", mint),
+            name=data.get("name", ""),
+            symbol=data.get("symbol", ""),
+            decimals=data.get("decimals", 0),
+            logo_uri=data.get("logoURI", ""),
+            tags=tags,
+            daily_volume=data.get("daily_volume"),
+            freeze_authority=data.get("freeze_authority"),
+            mint_authority=data.get("mint_authority"),
+            is_verified="verified" in tags or "strict" in tags or "community" in tags,
+            is_banned=mint in self._banned_mints,
+        )
+        self._set_cached(f"token:{mint}", token)
+        return token
+
+    async def is_banned(self, mint: str) -> bool:
+        """Check if a token is on Jupiter's banned list (known scams)."""
+        if mint in self._banned_mints:
+            return True
+        if not self._banned_loaded:
+            await self._refresh_banned_list()
+        return mint in self._banned_mints
+
+    async def is_verified(self, mint: str) -> bool:
+        """Check if a token is on the verified list."""
+        info = await self.get_token_info(mint)
+        return info.is_verified
+
+    async def get_strict_list(self) -> list[TokenInfo]:
+        """
+        Get the strictly verified token list (vetted tokens only).
+
+        Returns:
+            List of TokenInfo for all strictly verified tokens.
+        """
+        cached = self._get_cached("strict_list")
+        if cached is not None:
+            return cached
+
+        if self._http is None:
+            raise RuntimeError("TokenClient not connected — call connect() first")
+
+        resp = await self._http.get(f"{self._base_url}/tokens/v1/strict")
+        resp.raise_for_status()
+
+        tokens = []
+        for item in resp.json():
+            if isinstance(item, dict):
+                tags = item.get("tags", [])
+                tokens.append(TokenInfo(
+                    address=item.get("address", ""),
+                    name=item.get("name", ""),
+                    symbol=item.get("symbol", ""),
+                    decimals=item.get("decimals", 0),
+                    logo_uri=item.get("logoURI", ""),
+                    tags=tags,
+                    daily_volume=item.get("daily_volume"),
+                    freeze_authority=item.get("freeze_authority"),
+                    mint_authority=item.get("mint_authority"),
+                    is_verified=True,
+                    is_banned=False,
+                ))
+
+        self._set_cached("strict_list", tokens, ttl=_BANNED_LIST_TTL)
+        return tokens
+
+    async def refresh_banned_list(self) -> int:
+        """
+        Manually refresh the banned token list.
+
+        Returns:
+            Number of banned tokens loaded.
+        """
+        await self._refresh_banned_list()
+        return len(self._banned_mints)
+
+    # -- Internal helpers ----------------------------------------------------
+
+    async def _refresh_banned_list(self) -> None:
+        if self._http is None:
+            return
+        try:
+            resp = await self._http.get(f"{self._base_url}/tokens/v1/banned")
+            if resp.status_code == 200:
+                data = resp.json()
+                if isinstance(data, list):
+                    self._banned_mints = {
+                        item.get("address", item) if isinstance(item, dict) else str(item)
+                        for item in data
+                    }
+                    self._banned_loaded = True
+                    logger.debug("Loaded %d banned tokens", len(self._banned_mints))
+        except Exception as exc:
+            logger.warning("Failed to load banned token list: %s", exc)
+
+    def _get_cached(self, key: str) -> Any | None:
+        if key in self._cache:
+            expires, value = self._cache[key]
+            if time.monotonic() < expires:
+                return value
+            del self._cache[key]
+        return None
+
+    def _set_cached(self, key: str, value: Any, ttl: float | None = None) -> None:
+        self._cache[key] = (time.monotonic() + (ttl or self._cache_ttl), value)

jupiter_swap_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: jupiter-swap-python
+Version: 0.1.0
+Summary: Async Python client for the Jupiter DEX aggregator on Solana — V6 quote/swap and Ultra API.
+Project-URL: Homepage, https://github.com/JinUltimate1995/jupiter-swap-python
+Project-URL: Repository, https://github.com/JinUltimate1995/jupiter-swap-python
+Project-URL: Issues, https://github.com/JinUltimate1995/jupiter-swap-python/issues
+Project-URL: Changelog, https://github.com/JinUltimate1995/jupiter-swap-python/blob/main/CHANGELOG.md
+Author: JinUltimate1995
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aggregator,async,crypto,defi,dex,jupiter,python,solana,swap,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# jupiter-swap-python
+
+**The missing Jupiter swap client for Python. Async. Typed. Production-tested.**
+
+[![PyPI version](https://img.shields.io/pypi/v/jupiter-swap-python?color=blue)](https://pypi.org/project/jupiter-swap-python/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/JinUltimate1995/jupiter-swap-python/actions/workflows/ci.yml/badge.svg)](https://github.com/JinUltimate1995/jupiter-swap-python/actions)
+
+Jupiter's own Python SDK was abandoned (returns 404). This library fills the gap — a clean, typed, async client for [Jupiter](https://jup.ag), the #1 DEX aggregator on Solana.
+
+---
+
+## ⚡ Quickstart
+
+```bash
+pip install jupiter-swap-python
+```
+
+### Get a quote
+
+```python
+import asyncio
+from jupiter_swap import JupiterClient
+
+SOL = "So11111111111111111111111111111111111111112"
+USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
+
+async def main():
+    async with JupiterClient() as jup:
+        quote = await jup.get_quote(SOL, USDC, 1_000_000_000)  # 1 SOL
+        print(f"1 SOL = {int(quote.out_amount) / 1e6:.2f} USDC")
+        print(f"Price impact: {quote.price_impact_pct}%")
+
+asyncio.run(main())
+```
+
+### Swap tokens
+
+```python
+async with JupiterClient(api_key="your-key") as jup:
+    # Step 1: Get quote
+    quote = await jup.get_quote(SOL, USDC, 1_000_000_000)
+
+    # Step 2: Build swap transaction
+    swap = await jup.get_swap_transaction(
+        quote,
+        user_public_key="YourWalletPublicKey...",
+        priority_fee_lamports=500_000,  # 0.0005 SOL
+    )
+
+    # Step 3: Sign and send swap.swap_transaction with your wallet
+    print(f"Transaction ready (block height: {swap.last_valid_block_height})")
+```
+
+### Ultra API (recommended for production)
+
+```python
+async with JupiterClient(api_key="your-key") as jup:
+    # Combined quote + swap in one call
+    order = await jup.ultra_order(
+        input_mint=SOL,
+        output_mint=USDC,
+        amount=1_000_000_000,
+        taker="YourWalletPublicKey...",
+    )
+
+    print(f"Swap type: {order.swap_type}")
+    print(f"Out amount: {order.out_amount}")
+
+    # Sign order.swap_transaction with your wallet, then:
+    tx_sig = await jup.ultra_execute(signed_transaction, order.request_id)
+    print(f"Executed: {tx_sig}")
+```
+
+### Token verification
+
+```python
+from jupiter_swap import TokenClient
+
+async with TokenClient() as tokens:
+    info = await tokens.get_token_info("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v")
+    print(f"{info.symbol} — verified: {info.is_verified}, banned: {info.is_banned}")
+
+    # Check if a token is a known scam
+    if await tokens.is_banned("SomeScamMint..."):
+        print("🚫 Token is banned!")
+```
+
+---
+
+## 🔧 API Reference
+
+### `JupiterClient`
+
+| Method | Description |
+|--------|-------------|
+| `get_quote()` | Get the best swap route and price |
+| `get_swap_transaction()` | Build a signable transaction from a quote |
+| `ultra_order()` | Combined quote + swap via Ultra API (MEV protection) |
+| `ultra_execute()` | Execute a signed Ultra swap order |
+
+### `TokenClient`
+
+| Method | Description |
+|--------|-------------|
+| `get_token_info()` | Get token metadata and verification status |
+| `is_banned()` | Check if a token is on the banned list |
+| `is_verified()` | Check if a token is verified |
+| `get_strict_list()` | Get all strictly verified tokens |
+| `refresh_banned_list()` | Manually refresh the banned list |
+
+### Models
+
+- `QuoteResponse` — Route details, expected output, price impact
+- `SwapResponse` — Base64 transaction ready to sign
+- `UltraOrder` — Combined quote + transaction from Ultra API
+- `TokenInfo` — Name, symbol, decimals, verification flags
+
+---
+
+## 🛡️ Why this library?
+
+| Problem | Solution |
+|---------|----------|
+| Jupiter's Python SDK is deleted | This exists |
+| Raw `httpx.post()` calls everywhere | Typed client with proper models |
+| No 429 handling | Built-in retry with exponential backoff |
+| Token safety is an afterthought | `TokenClient` with banned/verified checks |
+| Sync-only clients | Fully async with `httpx` |
+
+---
+
+## 🔑 API Key
+
+A Jupiter API key is optional but recommended for production use (higher rate limits).
+
+Get one at [station.jup.ag](https://station.jup.ag/).
+
+```python
+client = JupiterClient(api_key="your-api-key")
+```
+
+---
+
+## 📦 Also by JinUltimate1995
+
+- [**solana-rpc-resilient**](https://github.com/JinUltimate1995/solana-rpc-resilient) — Solana RPC client with automatic failover, rate limiting, and circuit breaker
+- [**dexscreener-python**](https://github.com/JinUltimate1995/dexscreener-python) — Async DexScreener API client for token/pair data across 80+ chains
+
+---
+
+## License
+
+MIT

jupiter_swap_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+jupiter_swap/__init__.py,sha256=0QHLBTFYjdNF3w9mv8uXvKVtHoCZLx7uY7UHlZ5HZ00,391
+jupiter_swap/client.py,sha256=bbpxnxdAAcABWeZ7amdNjbrXO-kwytGKM_d6eI9TrYo,13062
+jupiter_swap/models.py,sha256=PXlpq_1_f_YhYxq3MyvccNK-sjevrIpnnR4t7IHSTJo,2095
+jupiter_swap/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jupiter_swap/tokens.py,sha256=RFgZExVcBtYWrqDhcKmwiKKllw9Xpejm2SAdfiG2hEs,7387
+jupiter_swap_python-0.1.0.dist-info/METADATA,sha256=okCLod9i4wvpGL5-psxWMoYpfhN9oNzM-JPZYMkp5WM,6271
+jupiter_swap_python-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+jupiter_swap_python-0.1.0.dist-info/licenses/LICENSE,sha256=D7y6S1R0LcQMuzvEM3af4NM2zASwS0H82DKH-3g_FDE,1072
+jupiter_swap_python-0.1.0.dist-info/RECORD,,

jupiter_swap_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

jupiter_swap_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JinUltimate1995
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.