exolix-client 0.1.0__py3-none-any.whl

exolix/__init__.py

@@ -0,0 +1,28 @@
+"""Exolix cryptocurrency exchange API (v2) client."""
+
+from .client import EXOLIX_API_KEY_HEADER, Exolix
+from .errors import ExolixError
+from .types import (
+    Currency,
+    Network,
+    PaginatedCurrencies,
+    PaginatedNetworks,
+    PaginatedTransactions,
+    Rate,
+    RateType,
+    Transaction,
+)
+
+__all__ = [
+    "EXOLIX_API_KEY_HEADER",
+    "Currency",
+    "Exolix",
+    "ExolixError",
+    "Network",
+    "PaginatedCurrencies",
+    "PaginatedNetworks",
+    "PaginatedTransactions",
+    "Rate",
+    "RateType",
+    "Transaction",
+]

exolix/client.py

@@ -0,0 +1,377 @@
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from .errors import ExolixError
+from .types import (
+    Network,
+    PaginatedCurrencies,
+    PaginatedNetworks,
+    PaginatedTransactions,
+    Rate,
+    RateType,
+    SortOrder,
+    Transaction,
+)
+
+# Header that carries the affiliate API key.
+#
+# Partner attribution is the API key itself. The default affiliate share is
+# 0.3%. There is no referral parameter.
+EXOLIX_API_KEY_HEADER = "Authorization"
+
+DEFAULT_BASE_URL = "https://exolix.com/api/v2"
+
+
+def _defined(values: dict[str, Any]) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    for key, value in values.items():
+        if value is None or value == "":
+            continue
+        if isinstance(value, bool):
+            params[key] = str(value).lower()
+        elif isinstance(value, list):
+            if not value:
+                continue
+            params[key] = ",".join(str(item) for item in value)
+        else:
+            params[key] = value
+    return params
+
+
+def _amount(value: float | str | None) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def _error_parts(data: Any, fallback: str) -> tuple[str, str | None]:
+    if isinstance(data, str) and data.strip():
+        return data.strip(), None
+    if isinstance(data, dict):
+        code_source = data.get("error")
+        code = None if code_source is None else str(code_source)
+        message_source = data.get("message", data.get("error"))
+        if isinstance(message_source, list):
+            message_source = ", ".join(str(item) for item in message_source)
+        message = fallback if message_source in (None, "") else str(message_source)
+        return message, code
+    return fallback, None
+
+
+class Exolix:
+    """Client for the Exolix cryptocurrency exchange API (v2).
+
+    Attributes:
+        api_key: Affiliate API key. Sent only in the Authorization header.
+        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 Exolix client.
+
+        Args:
+            api_key: Affiliate API key. Not read from the environment.
+                Attribution is this key (default affiliate share 0.3%).
+            base_url: API base URL. Defaults to https://exolix.com/api/v2.
+            timeout: Timeout in seconds for HTTP requests. Defaults to 30.0.
+            user_agent: Custom User-Agent header string.
+
+        Examples:
+            >>> from exolix import Exolix
+            >>> client = Exolix(api_key="your-api-key")
+            >>> currencies = client.get_currencies(page=1, size=10)
+            >>> print(currencies["count"])
+        """
+        self.api_key = api_key
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        ua = user_agent or "exolix-client/0.1.0"
+
+        headers: dict[str, str] = {
+            "User-Agent": ua,
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        if self.api_key:
+            headers[EXOLIX_API_KEY_HEADER] = 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) -> "Exolix":
+        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()
+            return response.json()
+        except httpx.HTTPStatusError as exc:
+            try:
+                data_err = exc.response.json()
+            except ValueError:
+                data_err = exc.response.text or None
+            message, code = _error_parts(data_err, "Exolix API error")
+            raise ExolixError(
+                message=message,
+                status_code=exc.response.status_code,
+                code=code,
+                response_body=data_err,
+            ) from exc
+        except httpx.RequestError as exc:
+            raise ExolixError(f"HTTP request failed: {exc}") from exc
+
+    def get_currencies(
+        self,
+        page: int | None = None,
+        size: int | None = None,
+        search: str | None = None,
+        with_networks: bool | None = None,
+    ) -> PaginatedCurrencies:
+        """Lists currencies. Set with_networks to include each coin's networks.
+
+        Args:
+            page: Page number.
+            size: Page size.
+            search: Currency code or name filter.
+            with_networks: Include networks on each currency.
+
+        Returns:
+            Page of currencies and the total count.
+
+        Examples:
+            >>> page = client.get_currencies(search="BTC", with_networks=True)
+        """
+        params = _defined(
+            {"page": page, "size": size, "search": search, "withNetworks": with_networks}
+        )
+        return self._request("GET", "/currencies", params=params or None)
+
+    def get_currency_networks(self, code: str) -> list[Network]:
+        """Lists networks for one currency code.
+
+        Args:
+            code: Currency code, for example ``ETH``.
+
+        Returns:
+            Networks for that currency.
+
+        Examples:
+            >>> networks = client.get_currency_networks("ETH")
+        """
+        return self._request("GET", f"/currencies/{quote(code, safe='')}/networks")
+
+    def get_networks(
+        self,
+        page: int | None = None,
+        size: int | None = None,
+        search: str | None = None,
+    ) -> PaginatedNetworks:
+        """Lists every network in the catalog.
+
+        Args:
+            page: Page number.
+            size: Page size.
+            search: Network name filter.
+
+        Returns:
+            Page of networks and the total count.
+
+        Examples:
+            >>> networks = client.get_networks(page=1, size=50)
+        """
+        params = _defined({"page": page, "size": size, "search": search})
+        return self._request("GET", "/currencies/networks", params=params or None)
+
+    def get_rate(
+        self,
+        coin_from: str,
+        coin_to: str,
+        rate_type: RateType,
+        *,
+        network_from: str | None = None,
+        network_to: str | None = None,
+        amount: float | str | None = None,
+        withdrawal_amount: float | str | None = None,
+    ) -> Rate:
+        """Quotes a fixed or floating rate.
+
+        Pass amount (what you send) or withdrawal_amount (what you want to
+        receive). Partner attribution is the API key, not a query field.
+
+        Args:
+            coin_from: Deposit currency code.
+            coin_to: Payout currency code.
+            rate_type: ``float`` or ``fixed``.
+            network_from: Deposit network.
+            network_to: Payout network.
+            amount: Deposit amount.
+            withdrawal_amount: Desired payout amount.
+
+        Returns:
+            Quote with amounts, rate, and limits.
+
+        Examples:
+            >>> quote = client.get_rate("BTC", "ETH", "float", amount="0.1")
+        """
+        params = _defined(
+            {
+                "coinFrom": coin_from,
+                "networkFrom": network_from,
+                "coinTo": coin_to,
+                "networkTo": network_to,
+                "amount": _amount(amount),
+                "withdrawalAmount": _amount(withdrawal_amount),
+                "rateType": rate_type,
+            }
+        )
+        return self._request("GET", "/rate", params=params)
+
+    def create_transaction(
+        self,
+        coin_from: str,
+        coin_to: str,
+        network_from: str,
+        network_to: str,
+        withdrawal_address: str,
+        *,
+        amount: float | str | None = None,
+        withdrawal_amount: float | str | None = None,
+        withdrawal_extra_id: str | None = None,
+        rate_type: RateType | None = None,
+        refund_address: str | None = None,
+        refund_extra_id: str | None = None,
+        slippage: float | str | None = None,
+    ) -> Transaction:
+        """Creates an exchange and returns the deposit address.
+
+        This opens a real swap. Call it only when a transaction should be created.
+
+        Args:
+            coin_from: Deposit currency code.
+            coin_to: Payout currency code.
+            network_from: Deposit network.
+            network_to: Payout network.
+            withdrawal_address: Address that receives the payout.
+            amount: Deposit amount.
+            withdrawal_amount: Desired payout amount.
+            withdrawal_extra_id: Memo or extra id for the payout address.
+            rate_type: ``float`` or ``fixed``. Defaults to float on the API.
+            refund_address: Address used if the swap is refunded.
+            refund_extra_id: Memo or extra id for the refund address.
+            slippage: Allowed rate movement, percent. Requires a refund address.
+
+        Returns:
+            Created transaction, including the deposit address.
+
+        Examples:
+            >>> tx = client.create_transaction(
+            ...     "ETH",
+            ...     "USDT",
+            ...     "ETH",
+            ...     "ETH",
+            ...     "0x0E29D1E501f90649Ad5982E900c455006e4522FC",
+            ...     amount=0.5,
+            ...     rate_type="float",
+            ... )
+        """
+        payload = _defined(
+            {
+                "coinFrom": coin_from,
+                "networkFrom": network_from,
+                "coinTo": coin_to,
+                "networkTo": network_to,
+                "amount": amount,
+                "withdrawalAmount": withdrawal_amount,
+                "withdrawalAddress": withdrawal_address,
+                "withdrawalExtraId": withdrawal_extra_id,
+                "rateType": rate_type,
+                "refundAddress": refund_address,
+                "refundExtraId": refund_extra_id,
+                "slippage": slippage,
+            }
+        )
+        return self._request("POST", "/transactions", json_data=payload)
+
+    def get_transaction(self, transaction_id: str) -> Transaction:
+        """Fetches one transaction by id.
+
+        Args:
+            transaction_id: Transaction id returned by create.
+
+        Returns:
+            Transaction status and addresses.
+
+        Examples:
+            >>> tx = client.get_transaction("ab93061434dd0s")
+        """
+        return self._request("GET", f"/transactions/{quote(transaction_id, safe='')}")
+
+    def get_transactions(
+        self,
+        page: int | None = None,
+        size: int | None = None,
+        search: str | None = None,
+        sort: str | None = None,
+        order: SortOrder | None = None,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        statuses: str | list[str] | None = None,
+    ) -> PaginatedTransactions:
+        """Lists transaction history for the affiliate API key.
+
+        Exolix enables this route per key. A rejected request means history is
+        not activated for that key.
+
+        Args:
+            page: Page number.
+            size: Page size.
+            search: Transaction id filter.
+            sort: Field to sort by.
+            order: ``asc`` or ``desc``.
+            date_from: Inclusive start datetime.
+            date_to: Inclusive end datetime.
+            statuses: One status or a list. A list is sent comma-separated.
+
+        Returns:
+            Page of transactions and the total count.
+
+        Examples:
+            >>> history = client.get_transactions(page=1, size=25, order="desc")
+        """
+        params = _defined(
+            {
+                "page": page,
+                "size": size,
+                "search": search,
+                "sort": sort,
+                "order": order,
+                "dateFrom": date_from,
+                "dateTo": date_to,
+                "statuses": statuses,
+            }
+        )
+        return self._request("GET", "/transactions", params=params or None)

exolix/errors.py

@@ -0,0 +1,23 @@
+from typing import Any
+
+
+class ExolixError(Exception):
+    """Exception raised when an Exolix API operation fails."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        code: str | None = None,
+        response_body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = 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

exolix/types.py

@@ -0,0 +1,103 @@
+from typing import Literal, TypedDict
+
+RateType = Literal["float", "fixed"]
+SortOrder = Literal["asc", "desc"]
+TransactionStatus = Literal[
+    "wait",
+    "confirmation",
+    "confirmed",
+    "exchanging",
+    "sending",
+    "success",
+    "overdue",
+    "refund",
+    "refunded",
+]
+
+
+class Network(TypedDict, total=False):
+    network: str
+    name: str
+    shortName: str | None
+    notes: str | None
+    addressRegex: str | None
+    isDefault: bool
+    blockExplorer: str | None
+    memoNeeded: bool
+    memoName: str | None
+    memoRegex: str | None
+    precision: int
+    decimal: int | None
+    contract: str | None
+    icon: str | None
+
+
+class Currency(TypedDict, total=False):
+    code: str
+    name: str
+    icon: str
+    notes: str | None
+    networks: list[Network]
+
+
+class Rate(TypedDict, total=False):
+    fromAmount: float
+    toAmount: float
+    rate: float
+    message: str | None
+    minAmount: float
+    withdrawMin: float
+    maxAmount: float
+
+
+class TransactionCoin(TypedDict, total=False):
+    coinCode: str
+    coinName: str
+    network: str
+    networkName: str
+    networkShortName: str | None
+    icon: str | None
+    memoName: str | None
+    contract: str | None
+
+
+class TransactionHash(TypedDict, total=False):
+    hash: str | None
+    link: str | None
+
+
+class Transaction(TypedDict, total=False):
+    id: str
+    amount: float
+    amountTo: float
+    coinFrom: TransactionCoin
+    coinTo: TransactionCoin
+    comment: str | None
+    createdAt: str
+    depositAddress: str
+    depositExtraId: str | None
+    withdrawalAddress: str
+    withdrawalExtraId: str | None
+    hashIn: TransactionHash
+    hashOut: TransactionHash
+    rate: float
+    rateType: str
+    refundAddress: str | None
+    refundExtraId: str | None
+    status: str
+    source: str
+
+
+class PaginatedCurrencies(TypedDict):
+    data: list[Currency]
+    count: int
+
+
+class PaginatedNetworks(TypedDict):
+    data: list[Network]
+    count: int
+
+
+class PaginatedTransactions(TypedDict):
+    data: list[Transaction]
+    count: int

exolix_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: exolix-client
+Version: 0.1.0
+Summary: Python client for the Exolix cryptocurrency exchange API (v2)
+Project-URL: Repository, https://github.com/TysikGG/api-kit
+Project-URL: Documentation, https://exolix.com/developers
+License-Expression: ISC
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# exolix-client
+
+[![PyPI version](https://img.shields.io/pypi/v/exolix-client.svg)](https://pypi.org/project/exolix-client/)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![Python Version](https://img.shields.io/pypi/pyversions/exolix-client.svg)](https://pypi.org/project/exolix-client/)
+
+Modern, fully typed Python client library for the [Exolix](https://exolix.com) instant cryptocurrency exchange API (v2).
+
+Official API documentation: <https://exolix.com/developers>
+
+The PyPI package is `exolix-client`. Import it as `exolix`.
+
+---
+
+## Features
+
+- ⚡ **Fixed & Floating Rates** — Quote a swap by deposit `amount` or by desired `withdrawal_amount`, at a floating or fixed rate.
+- 🪙 **Currencies & Networks** — List coins, networks for one coin, and the full network catalog.
+- 🐍 **Modern Pythonic Design** — Type annotations, context manager support (`with Exolix(...) as client:`), and a custom exception.
+- 🔄 **Transactions** — Create a swap, fetch it by id, and list affiliate transaction history.
+
+---
+
+## Installation
+
+```bash
+pip install exolix-client
+```
+
+Requires Python 3.10 or higher.
+
+---
+
+## Authentication
+
+Partner attribution is the affiliate API key. The default affiliate share is 0.3%. The client sends the key in one header and does not add a referral parameter:
+
+```python
+from exolix import EXOLIX_API_KEY_HEADER
+
+print(EXOLIX_API_KEY_HEADER)  # "Authorization"
+```
+
+Pass the key to the constructor. The client does not read `EXOLIX_API_KEY` from the environment. Public reads work without a key. Transaction history requires a key that Exolix has enabled for that route.
+
+---
+
+## Quick Start (Safe Check)
+
+The quick check only queries currencies and a rate. It does not create a transaction:
+
+```python
+import os
+from exolix import Exolix
+
+with Exolix(api_key=os.environ["EXOLIX_API_KEY"]) as client:
+    currencies = client.get_currencies(page=1, size=5, with_networks=True)
+    print(f"Available currencies: {currencies['count']}")
+
+    quote = client.get_rate(
+        "BTC",
+        "ETH",
+        "float",
+        network_from="BTC",
+        network_to="ETH",
+        amount="0.1",
+    )
+    print(f"0.1 BTC -> {quote['toAmount']} ETH (rate {quote['rate']})")
+```
+
+---
+
+## Usage Guide
+
+### 1. Creating a Floating Rate Swap
+
+```python
+from exolix import Exolix, ExolixError
+
+with Exolix(api_key="your_api_key") as client:
+    quote = client.get_rate(
+        "ETH",
+        "USDT",
+        "float",
+        network_from="ETH",
+        network_to="ETH",
+        amount="0.5",
+    )
+    print(f"Min {quote['minAmount']}, you receive {quote['toAmount']} USDT")
+
+    tx = client.create_transaction(
+        "ETH",
+        "USDT",
+        "ETH",
+        "ETH",
+        "0x0E29D1E501f90649Ad5982E900c455006e4522FC",
+        amount=0.5,
+        rate_type="float",
+    )
+    print(f"Send ETH to {tx['depositAddress']} ({tx['id']})")
+```
+
+`create_transaction` opens a real swap. Quote with `get_rate` first.
+
+### 2. Fixed Rate by Withdrawal Amount
+
+```python
+quote = client.get_rate(
+    "ETH",
+    "USDT",
+    "fixed",
+    network_from="ETH",
+    network_to="ETH",
+    withdrawal_amount="50",
+)
+print(f"Send {quote['fromAmount']} ETH to receive {quote['toAmount']} USDT")
+```
+
+### 3. Tracking Status and History
+
+```python
+tx = client.get_transaction("ab93061434dd0s")
+print(tx["status"])  # wait, confirmation, confirmed, exchanging, sending, success, ...
+
+history = client.get_transactions(page=1, size=25, order="desc")
+print(history["count"])
+```
+
+History is authenticated. Exolix enables it per API key.
+
+---
+
+## API Reference
+
+### `Exolix` Class
+
+#### Constructor
+
+```python
+Exolix(
+    api_key: str | None = None,
+    base_url: str | None = None,
+    timeout: float = 30.0,
+    user_agent: str | None = None,
+)
+```
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `api_key` | `str` | unset | Affiliate API key. Sent as `Authorization`. |
+| `base_url` | `str` | `"https://exolix.com/api/v2"` | API base URL. |
+| `timeout` | `float` | `30.0` | Request timeout in seconds. |
+| `user_agent` | `str` | `"exolix-client/0.1.0"` | User-Agent header. |
+
+#### Methods
+
+- **`get_currencies(...)`** — `GET /currencies`
+- **`get_currency_networks(code)`** — `GET /currencies/{code}/networks`
+- **`get_networks(...)`** — `GET /currencies/networks`
+- **`get_rate(...)`** — `GET /rate` (`rate_type` `float` or `fixed`, `amount` or `withdrawal_amount`)
+- **`create_transaction(...)`** — `POST /transactions`
+- **`get_transaction(transaction_id)`** — `GET /transactions/{id}`
+- **`get_transactions(...)`** — `GET /transactions` (authenticated history)
+
+---
+
+## Error Handling
+
+```python
+from exolix import Exolix, ExolixError
+
+try:
+    with Exolix(api_key="invalid_key") as client:
+        client.get_transactions()
+except ExolixError as error:
+    print(f"{error.code}: {error.message} (HTTP {error.status_code})")
+```
+
+---
+
+## Live Tests
+
+Unit tests mock HTTP and always run. The live suite calls the real API and runs only when `EXOLIX_API_KEY` is set. It is read-only: currencies, networks, a floating rate, a fixed rate, and transaction history. It never creates a transaction.
+
+```bash
+uv run pytest -m "not live"
+EXOLIX_API_KEY=your_key uv run pytest -m live
+```
+
+---
+
+## License
+
+ISC

exolix_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+exolix/__init__.py,sha256=_Ih3H6gLxTzRxfBlSn6siMIooicgxGPS-bhWKl4uh5s,539
+exolix/client.py,sha256=_jwlJ_HXltbYbmIV0qr_Vc5_pQBlIwTzO0-Oas6lph8,12346
+exolix/errors.py,sha256=cDe2uBKoCCBpIeQBk6gDA9UpucvNtiFv1OmP4V6LOq0,626
+exolix/types.py,sha256=nvAZe2HkPb17LS1Vefq7aIMUvC1utJbYLibDJFTmITE,2018
+exolix_client-0.1.0.dist-info/METADATA,sha256=H3NccXFjsCZ_jAiUtj8HKidzTjbbWJNA-weWPrE8bnY,5678
+exolix_client-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+exolix_client-0.1.0.dist-info/licenses/LICENSE,sha256=8S0uYmn_aeljwFudfBoV91HcIo79yab9s0yhMVsOHJ0,751
+exolix_client-0.1.0.dist-info/RECORD,,

exolix_client-0.1.0.dist-info/WHEEL

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

exolix_client-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.