swapzone 0.1.0__tar.gz

swapzone-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Dependencies
+node_modules/
+.pnp.*
+.yarn/
+.pnpm-store/
+
+# Build
+dist/
+build/
+*.tsbuildinfo
+*.egg-info/
+.eggs/
+wheels/
+
+# Tests and coverage
+coverage/
+.nyc_output/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+.coverage.*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+env/
+
+# Secrets
+.env
+.env.*
+!.env.example
+AGENTS.md
+
+# GitBook / HonKit
+_book/
+
+# OS and editors
+.DS_Store
+Thumbs.db
+.idea/
+*.swp

swapzone-0.1.0/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.

swapzone-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,186 @@
+# 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/examples/quickstart.py

@@ -0,0 +1,24 @@
+import os
+import sys
+
+from swapzone import Swapzone
+
+
+def main() -> None:
+    api_key = os.environ.get("SWAPZONE_API_KEY")
+    if not api_key:
+        print("Please set SWAPZONE_API_KEY environment variable.", file=sys.stderr)
+        sys.exit(1)
+
+    with Swapzone(api_key=api_key) as client:
+        currencies = client.get_currencies()
+        print(f"Supported currencies: {len(currencies)}")
+        sample = [f"{c['name']} ({c['ticker'].upper()})" for c in currencies[:5]]
+        print("Sample:", ", ".join(sample))
+
+        rate = client.get_rate("btc", "eth", "0.1")
+        print(f"\n0.1 BTC -> {rate['amountTo']} ETH via {rate['adapter']}")
+
+
+if __name__ == "__main__":
+    main()

swapzone-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "swapzone"
+version = "0.1.0"
+description = "Python client for the Swapzone cryptocurrency exchange and DEX aggregator API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "ISC"
+dependencies = [
+  "httpx>=0.27",
+]
+
+[project.urls]
+Repository = "https://github.com/TysikGG/api-kit"
+Documentation = "https://documenter.getpostman.com/view/16362858/UVXokDS6"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-httpx>=0.30",
+  "ruff>=0.8",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/swapzone"]
+
+[tool.pytest.ini_options]
+markers = [
+  "live: calls the real Swapzone API and needs SWAPZONE_API_KEY",
+]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests", "examples"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

swapzone-0.1.0/src/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",
+]