swapzone 0.1.0__py3-none-any.whl

swapzone/__init__.py

@@ -0,0 +1,23 @@
+"""Swapzone cryptocurrency exchange and DEX aggregator client."""
+
+from .client import Swapzone
+from .errors import SwapzoneError
+from .types import (
+    DEXBlockchain,
+    RateOffer,
+    SupportedCurrency,
+    TransactionResult,
+    TransactionStatus,
+    ValidateAddressResult,
+)
+
+__all__ = [
+    "DEXBlockchain",
+    "RateOffer",
+    "SupportedCurrency",
+    "Swapzone",
+    "SwapzoneError",
+    "TransactionResult",
+    "TransactionStatus",
+    "ValidateAddressResult",
+]

swapzone/client.py

@@ -0,0 +1,341 @@
+import os
+from typing import Any
+
+import httpx
+
+from .errors import SwapzoneError
+from .types import (
+    DEXBlockchain,
+    RateOffer,
+    SupportedCurrency,
+    TransactionResult,
+    TransactionStatus,
+    ValidateAddressResult,
+)
+
+
+class Swapzone:
+    """Client for the Swapzone cryptocurrency exchange and DEX aggregator API.
+
+    Attributes:
+        api_key: Swapzone API key.
+        base_url: Base URL of the API.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        user_agent: str | None = None,
+    ) -> None:
+        """Initializes the Swapzone client.
+
+        Args:
+            api_key: Swapzone API key. Defaults to SWAPZONE_API_KEY environment variable.
+            base_url: Base URL for the Swapzone API. Defaults to https://api.swapzone.io.
+            timeout: Timeout in seconds for HTTP requests. Defaults to 30.0.
+            user_agent: Custom User-Agent header string.
+
+        Examples:
+            >>> from swapzone import Swapzone
+            >>> client = Swapzone(api_key="your-api-key")
+            >>> currencies = client.get_currencies()
+            >>> print(len(currencies))
+        """
+        self.api_key = api_key or os.environ.get("SWAPZONE_API_KEY")
+        self.base_url = (base_url or "https://api.swapzone.io").rstrip("/")
+        ua = user_agent or "swapzone-client/0.1.0"
+
+        headers: dict[str, str] = {
+            "User-Agent": ua,
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=headers,
+        )
+
+    def close(self) -> None:
+        """Closes the underlying HTTP client session."""
+        self._client.close()
+
+    def __enter__(self) -> "Swapzone":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+    ) -> Any:
+        try:
+            response = self._client.request(
+                method,
+                path,
+                params=params,
+                json=json_data,
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            if isinstance(data, dict) and data.get("error") is True:
+                msg = data.get("message") or "Swapzone API error"
+                raise SwapzoneError(
+                    message=str(msg),
+                    status_code=response.status_code,
+                    response_body=data,
+                )
+
+            return data
+        except httpx.HTTPStatusError as e:
+            try:
+                data_err = e.response.json()
+            except Exception:
+                data_err = None
+            msg = "Swapzone API error"
+            if isinstance(data_err, dict) and data_err.get("message"):
+                msg = str(data_err["message"])
+            raise SwapzoneError(
+                message=msg,
+                status_code=e.response.status_code,
+                response_body=data_err,
+            ) from e
+        except httpx.RequestError as e:
+            raise SwapzoneError(f"HTTP request failed: {e}") from e
+
+    def get_currencies(self) -> list[SupportedCurrency]:
+        """Retrieves all supported cryptocurrencies and tokens.
+
+        Returns:
+            List of supported currencies with tickers and networks.
+
+        Examples:
+            >>> currencies = client.get_currencies()
+            >>> print(currencies[0]["ticker"])
+        """
+        return self._request("GET", "/v1/exchange/currencies")
+
+    def get_rate(
+        self,
+        from_currency: str,
+        to_currency: str,
+        amount: float | str,
+        rate_type: str = "all",
+        choose_rate: str = "best",
+        available_in_usa: bool | None = None,
+        no_refund_address: bool | None = None,
+        from_network: str | None = None,
+        to_network: str | None = None,
+        amount_to: float | str | None = None,
+        timeout: float | str | None = None,
+    ) -> RateOffer:
+        """Retrieves rate estimates for an exchange pair.
+
+        Args:
+            from_currency: Deposit asset ticker (e.g. 'btc').
+            to_currency: Receiving asset ticker (e.g. 'eth').
+            amount: Deposit amount.
+            rate_type: Rate type ('all', 'fixed', or 'floating').
+            choose_rate: Strategy ('best', 'all', or 'recommended').
+            available_in_usa: Restrict to partners supporting US clients.
+            no_refund_address: Restrict to exchangers with optional refund address.
+            from_network: Network for deposit asset.
+            to_network: Network for receiving asset.
+            amount_to: Target receiving amount (for reverse rate).
+            timeout: Maximum response timeout in ms.
+
+        Returns:
+            Rate offer dictionary with amounts and quota ID.
+
+        Examples:
+            >>> rate = client.get_rate("btc", "eth", amount="0.1")
+            >>> print(f"ETH: {rate['amountTo']} via {rate['adapter']}")
+        """
+        params: dict[str, Any] = {
+            "from": from_currency,
+            "to": to_currency,
+            "amount": str(amount),
+            "rateType": rate_type,
+            "chooseRate": choose_rate,
+        }
+        if available_in_usa is not None:
+            params["availableInUSA"] = available_in_usa
+        if no_refund_address is not None:
+            params["noRefundAddress"] = no_refund_address
+        if from_network is not None:
+            params["fromNetwork"] = from_network
+        if to_network is not None:
+            params["toNetwork"] = to_network
+        if amount_to is not None:
+            params["amountTo"] = str(amount_to)
+        if timeout is not None:
+            params["timeout"] = str(timeout)
+
+        return self._request("GET", "/v1/exchange/get-rate", params=params)
+
+    def create_transaction(
+        self,
+        from_currency: str,
+        to_currency: str,
+        amount_deposit: float | str,
+        address_receive: str,
+        extra_id_receive: str | None = None,
+        refund_address: str | None = None,
+        refund_extra_id: str | None = None,
+        quota_id: str | None = None,
+        no_quota_id: bool | None = None,
+        from_network: str | None = None,
+        to_network: str | None = None,
+        offer_reference_id: str | None = None,
+    ) -> TransactionResult:
+        """Creates an exchange transaction order.
+
+        Args:
+            from_currency: Deposit asset ticker.
+            to_currency: Receiving asset ticker.
+            amount_deposit: Amount to deposit.
+            address_receive: Destination recipient wallet address.
+            extra_id_receive: Optional memo / extra ID for recipient.
+            refund_address: Optional address to return funds on failure.
+            refund_extra_id: Optional memo for refund address.
+            quota_id: Quota ID obtained from get_rate.
+            no_quota_id: Bypass quota ID requirement.
+            from_network: Deposit blockchain network.
+            to_network: Receiving blockchain network.
+            offer_reference_id: Reference ID for fixed-rate quotes.
+
+        Returns:
+            Order details containing deposit address and transaction ID.
+
+        Examples:
+            >>> order = client.create_transaction(
+            ...     from_currency="btc",
+            ...     to_currency="eth",
+            ...     amount_deposit="0.1",
+            ...     address_receive="0xReceiverAddress...",
+            ...     quota_id=rate["quotaId"],
+            ... )
+            >>> print(f"Deposit address: {order['addressDeposit']}")
+        """
+        payload: dict[str, Any] = {
+            "from": from_currency,
+            "to": to_currency,
+            "amountDeposit": str(amount_deposit),
+            "addressReceive": address_receive,
+        }
+        if extra_id_receive is not None:
+            payload["extraIdReceive"] = extra_id_receive
+        if refund_address is not None:
+            payload["refundAddress"] = refund_address
+        if refund_extra_id is not None:
+            payload["refundExtraId"] = refund_extra_id
+        if quota_id is not None:
+            payload["quotaId"] = quota_id
+        if no_quota_id is not None:
+            payload["noQuotaId"] = no_quota_id
+        if from_network is not None:
+            payload["fromNetwork"] = from_network
+        if to_network is not None:
+            payload["toNetwork"] = to_network
+        if offer_reference_id is not None:
+            payload["offerReferenceId"] = offer_reference_id
+
+        return self._request("POST", "/v1/exchange/create", json_data=payload)
+
+    def get_transaction(self, transaction_id: str) -> TransactionStatus:
+        """Retrieves transaction status.
+
+        Args:
+            transaction_id: Swapzone transaction ID.
+
+        Returns:
+            Transaction details and status.
+
+        Examples:
+            >>> status = client.get_transaction("tx-id")
+            >>> print(status["status"])
+        """
+        return self._request("GET", "/v1/exchange/tx", params={"id": transaction_id})
+
+    def validate_address(
+        self,
+        currency: str,
+        address: str,
+        network: str | None = None,
+    ) -> ValidateAddressResult:
+        """Validates a cryptocurrency address for a given asset.
+
+        Args:
+            currency: Asset ticker (e.g. 'eth').
+            address: Wallet address to validate.
+            network: Blockchain network (e.g. 'ETH').
+
+        Returns:
+            Dictionary indicating if the address is valid.
+
+        Examples:
+            >>> res = client.validate_address("eth", "0x57f3...", network="ETH")
+            >>> print(res["result"])
+        """
+        params: dict[str, Any] = {
+            "currency": currency,
+            "address": address,
+        }
+        if network is not None:
+            params["network"] = network
+
+        return self._request("GET", "/v1/exchange/validate/address", params=params)
+
+    def get_markets(self, rate_type: str | None = None) -> list[Any]:
+        """Retrieves bulk rate markets for instant exchange pairs.
+
+        Args:
+            rate_type: Optional rate type filter ('all', 'fixed', 'floating').
+
+        Returns:
+            List of market pairs.
+
+        Examples:
+            >>> markets = client.get_markets("fixed")
+        """
+        params = {"rateType": rate_type} if rate_type else None
+        return self._request("GET", "/v1/exchange/markets", params=params)
+
+    def get_dex_blockchains(self) -> list[DEXBlockchain]:
+        """Retrieves supported blockchain networks for decentralized swaps.
+
+        Returns:
+            List of supported blockchains with chain IDs.
+
+        Examples:
+            >>> chains = client.get_dex_blockchains()
+            >>> print(len(chains))
+        """
+        res = self._request("GET", "/v1/dex/blockchains")
+        if isinstance(res, dict) and "result" in res:
+            return res["result"]
+        return res
+
+    def get_dex_tokens(self) -> list[Any]:
+        """Retrieves supported tokens for DEX swaps.
+
+        Returns:
+            List of supported tokens.
+
+        Examples:
+            >>> tokens = client.get_dex_tokens()
+        """
+        res = self._request("GET", "/v1/dex/tokens")
+        if isinstance(res, dict) and "result" in res:
+            return res["result"]
+        return res

swapzone/errors.py

@@ -0,0 +1,21 @@
+from typing import Any
+
+
+class SwapzoneError(Exception):
+    """Exception raised when a Swapzone API call fails."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response_body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response_body = response_body
+
+    def __str__(self) -> str:
+        if self.status_code is not None:
+            return f"[{self.status_code}] {self.message}"
+        return self.message

swapzone/types.py

@@ -0,0 +1,71 @@
+from typing import Any
+
+from typing_extensions import TypedDict
+
+
+class SupportedCurrency(TypedDict, total=False):
+    name: str
+    ticker: str
+    network: str
+    defaultAmount: float
+    smartContract: str | None
+    alias: list[str]
+    hasExternalId: bool
+
+
+class RateOffer(TypedDict, total=False):
+    adapter: str
+    from_: str
+    fromNetwork: str
+    to: str
+    toNetwork: str
+    amountFrom: float
+    amountTo: float
+    amountFromUSD: float
+    amountToUSD: float
+    quotaId: str
+    minAmount: float
+    maxAmount: float
+    time: int
+    accuracyRate: float
+
+
+class TransactionResult(TypedDict, total=False):
+    id: str
+    quotaId: str
+    status: str
+    addressReceive: str
+    addressDeposit: str
+    extraIdReceive: str
+    amountDeposit: float
+    amountEstimated: float
+    createdAt: str
+    refundAddress: str
+    refundExtraId: str
+    payTill: str
+
+
+class TransactionStatus(TypedDict, total=False):
+    id: str
+    status: str
+    amountDeposit: float
+    amountEstimated: float
+    addressDeposit: str
+    addressReceive: str
+    hashDeposit: str | None
+    hashReceive: str | None
+    createdAt: str
+    updatedAt: str
+
+
+class ValidateAddressResult(TypedDict, total=False):
+    result: bool
+    message: str | None
+
+
+class DEXBlockchain(TypedDict, total=False):
+    chainId: int
+    name: str
+    nativeCurrency: dict[str, Any]
+    rpcUrls: list[str]
+    explorerUrls: list[str]

swapzone-0.1.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: swapzone
+Version: 0.1.0
+Summary: Python client for the Swapzone cryptocurrency exchange and DEX aggregator API
+Project-URL: Repository, https://github.com/TysikGG/api-kit
+Project-URL: Documentation, https://documenter.getpostman.com/view/16362858/UVXokDS6
+License-Expression: ISC
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# swapzone
+
+[![PyPI version](https://img.shields.io/pypi/v/swapzone.svg)](https://pypi.org/project/swapzone/)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![Python Version](https://img.shields.io/pypi/pyversions/swapzone.svg)](https://pypi.org/project/swapzone/)
+
+Modern, fully typed Python client library for the [Swapzone](https://swapzone.io) instant cryptocurrency exchange & DEX cross-chain aggregator REST API.
+
+Official API documentation: <https://documenter.getpostman.com/view/16362858/UVXokDS6>
+
+---
+
+## Features
+
+- 🔄 **15+ Exchange Providers Aggregated** — Compares rates in real time across top instant swap platforms (SimpleSwap, StealthEX, ChangeNOW, Changelly, etc.).
+- 🪙 **1000+ Cryptocurrencies** — Full support for fixed and floating cross-chain swaps.
+- 🐍 **Modern Pythonic Design** — Type annotations, dataclass models (`RateOffer`, `TransactionResult`, `SupportedCurrency`, `TransactionStatus`), context manager support (`with Swapzone(...) as client:`), and custom exceptions.
+- ⚡ **DEX Aggregation** — DEX blockchain routes, token catalogs, and quote comparisons.
+- 🛡️ **Address Validation** — Built-in `validate_address()` helper to verify destination wallet addresses.
+
+---
+
+## Installation
+
+```bash
+pip install swapzone
+```
+
+Requires Python 3.10 or higher.
+
+---
+
+## Quick Start (Safe Check)
+
+The quick check only inspects supported currencies and compares live provider exchange rates. It does not create orders:
+
+```python
+import os
+from swapzone import Swapzone
+
+with Swapzone(api_key=os.environ["SWAPZONE_API_KEY"]) as client:
+    # 1. Fetch supported currencies
+    currencies = client.get_currencies()
+    print(f"Available currencies: {len(currencies)}")
+
+    # 2. Query best rate offer for 0.1 BTC to ETH
+    rate = client.get_rate(
+        from_currency="btc",
+        to_currency="eth",
+        amount=0.1,
+        rate_type="all",
+    )
+    print(f"Best Provider: {rate.best_offer.adapter}")
+    print(f"Estimated Receive: {rate.best_offer.amount_to} ETH")
+```
+
+---
+
+## Usage Guide
+
+### 1. Finding the Best Rate and Creating a Swap
+
+Full lifecycle: query provider rates, validate destination address, create transaction, and monitor status:
+
+```python
+from swapzone import Swapzone, SwapzoneError
+
+with Swapzone(api_key="your_api_key") as client:
+    # 1. Get rate offers across all providers
+    rate = client.get_rate(
+        from_currency="btc",
+        to_currency="eth",
+        amount=0.1,
+        rate_type="all",
+    )
+    best_offer = rate.best_offer
+    print(f"Selected Provider: {best_offer.adapter} (Quota: {best_offer.amount_to} ETH)")
+
+    # 2. Validate destination wallet address
+    check = client.validate_address(
+        currency="eth",
+        address="0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
+    )
+    if not check.result:
+        raise ValueError("Invalid destination wallet address!")
+
+    # 3. Create transaction with the selected provider
+    tx = client.create_transaction(
+        from_currency="btc",
+        to_currency="eth",
+        amount_deposit=0.1,
+        address_receive="0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
+        quota_id=best_offer.quota_id,
+        refund_address="bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",  # optional
+    )
+
+    print(f"Transaction Created! ID: {tx.transaction.id}")
+    print(f"Send BTC to Deposit Address: {tx.transaction.address_deposit}")
+    print(f"Status: {tx.transaction.status}")
+```
+
+### 2. Tracking Transaction Progress
+
+Monitor swap progress from deposit to settlement:
+
+```python
+current = client.get_transaction(tx.transaction.id)
+print(f"Status: {current.status}")
+
+if current.status == "finished":
+    print(f"Received: {current.amount_receive} ETH")
+```
+
+### 3. Querying DEX Aggregation
+
+Inspect supported DEX blockchains and token pairs:
+
+```python
+# List supported DEX blockchains
+blockchains = client.get_dex_blockchains()
+print("DEX Blockchains:", blockchains)
+
+# Check DEX tokens
+dex_tokens = client.get_dex_tokens()
+print(f"DEX Tokens count: {len(dex_tokens)}")
+```
+
+---
+
+## API Reference
+
+### `Swapzone` Class
+
+#### Constructor
+
+```python
+Swapzone(
+    api_key: str,
+    base_url: str = "https://api.swapzone.io/v1",
+    timeout: float = 30.0,
+)
+```
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `api_key` | `str` | **Required** | Your Swapzone API key. |
+| `base_url` | `str` | `"https://api.swapzone.io/v1"` | Swapzone API base URL. |
+| `timeout` | `float` | `30.0` | HTTP request timeout in seconds. |
+
+#### Methods
+
+- **`get_currencies() -> list[SupportedCurrency]`** — Returns all supported cryptocurrencies.
+- **`get_rate(from_currency, to_currency, amount, rate_type="all") -> RateOffer`** — Returns aggregated quotes.
+- **`create_transaction(from_currency, to_currency, amount_deposit, address_receive, quota_id, ...) -> TransactionResult`** — Creates transaction.
+- **`get_transaction(transaction_id: str) -> TransactionStatus`** — Checks swap status and execution details.
+- **`validate_address(currency, address) -> ValidateAddressResult`** — Validates destination wallet address.
+- **`get_markets(rate_type=None) -> list[Any]`** — Retrieves active market pairs.
+- **`get_dex_blockchains() -> list[DEXBlockchain]`** — Lists supported DEX blockchains.
+- **`get_dex_tokens() -> list[Any]`** — Lists tokens supported on DEX routers.
+
+---
+
+## Error Handling
+
+When the API returns an error, `SwapzoneError` is raised:
+
+```python
+from swapzone import Swapzone, SwapzoneError
+
+try:
+    with Swapzone(api_key="invalid_key") as client:
+        client.get_currencies()
+except SwapzoneError as exc:
+    print(f"Swapzone Error: {exc.message} (Status: {exc.status})")
+```
+
+Common HTTP status codes:
+- `400 Bad Request` — Invalid address or amount out of limits.
+- `401 Unauthorized` — Invalid API key.
+- `404 Not Found` — Transaction ID not found.
+
+---
+
+## License
+
+ISC

swapzone-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+swapzone/__init__.py,sha256=EeGsFbxT6hdtwVbVFbiZd6dx4yVLK4mDPDh4HgLsQiU,477
+swapzone/client.py,sha256=O95Pnqo8H2gululdU-vH0FrZPmeagDHLFRw-xL3Scls,11677
+swapzone/errors.py,sha256=L9Kt1Qq__Kp2NzbcAhWtQOfbRetq_HnWQMrrAH8akW4,566
+swapzone/types.py,sha256=KTygOSJLN3tYk2x7lfQtv7e0lu9q8MGSgAqDibG47P4,1411
+swapzone-0.1.0.dist-info/METADATA,sha256=A3S6sIU96Z8vQH2z8f41PzSqwSZu4FeQIw9FgM0srnE,6343
+swapzone-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+swapzone-0.1.0.dist-info/licenses/LICENSE,sha256=8S0uYmn_aeljwFudfBoV91HcIo79yab9s0yhMVsOHJ0,751
+swapzone-0.1.0.dist-info/RECORD,,

swapzone-0.1.0.dist-info/WHEEL

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

swapzone-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 api-kit contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.