cryptunnel 1.0.0__tar.gz

cryptunnel-1.0.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    groups:
+      dependencies:
+        patterns: ['*']
+        update-types: [minor, patch]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday

cryptunnel-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish
+
+on:
+  push:
+    tags: ['v*']
+
+# Trusted publishing (OIDC): no PyPI token is stored anywhere
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

cryptunnel-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e . pytest pytest-asyncio
+      - run: pytest -q

cryptunnel-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/

cryptunnel-1.0.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this package are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the package follows semantic versioning.
+
+## [1.0.0] - 2026-10-03
+
+### Added
+
+- `Cryptunnel` async client and `CryptunnelSync` blocking mirror over `httpx`.
+- Payment creation (widget and h2h), payment read and list, currency list, merchant info.
+- `verify_webhook` - constant-time HMAC-SHA256 verification with a timestamp tolerance.
+- `wait_for_payment` - polling with exponential backoff for scripts and development.
+- Exception hierarchy mapping API status codes, keeping the raw API `code`.
+- `sandbox=True` switch marking every created payment as a test payment.

cryptunnel-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cryptunnel
+
+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.

cryptunnel-1.0.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: cryptunnel
+Version: 1.0.0
+Summary: Python SDK for Cryptunnel - accept crypto payments straight to your own wallets
+Project-URL: Homepage, https://cryptunnel.io
+Project-URL: Documentation, https://docs.cryptunnel.io
+Project-URL: Issues, https://github.com/cryptunnel/cryptunnel-python/issues
+Project-URL: Source, https://github.com/cryptunnel/cryptunnel-python
+Author: Cryptunnel
+License: MIT
+License-File: LICENSE
+Keywords: bitcoin,crypto,cryptunnel,ethereum,payments,tron,usdt
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# cryptunnel
+
+Python SDK for [Cryptunnel](https://cryptunnel.io) - accept crypto payments straight into your own
+wallets. Async-first for bots on aiogram, with a blocking mirror for scripts.
+
+```bash
+pip install cryptunnel
+```
+
+`httpx` is the only dependency. Python 3.10+.
+
+## Create a sandbox payment
+
+```python
+from cryptunnel import CryptunnelSync
+
+cryptunnel = CryptunnelSync("<merchant id>", "<api key>", sandbox=True)
+
+print(cryptunnel.get_merchant())  # your credentials work if this prints your merchant
+
+payment = cryptunnel.create_widget_payment(
+    amount=10,
+    currency="USD",
+    external_id="order-1",
+    success_url="https://example.com/thanks",
+)
+print(payment["url"])  # send the buyer here
+```
+
+`sandbox=True` sets `is_test` on every payment it creates: the payer is offered testnet currencies
+only, and the payment is excluded from your stats and fees. It is the same host and the same key -
+the sandbox is a flag, not a second account.
+
+## Verify a webhook
+
+```python
+from flask import Flask, request
+
+from cryptunnel import verify_webhook
+
+app = Flask(__name__)
+WEBHOOK_SECRET = "<whsec_...>"
+
+@app.post("/cryptunnel")
+def callback():
+    if not verify_webhook(WEBHOOK_SECRET, request.headers, request.get_data()):
+        return "", 401
+    payment = request.get_json()
+    if payment["status"] in ("confirmed", "confirmed_manual"):
+        deliver(payment["external_id"])  # deduplicate on (id, status): retries repeat the same pair
+    return "", 200
+```
+
+Pass the raw body bytes as received - parsing and re-serialising the JSON changes the signature.
+A failed delivery is retried 60 times, once a minute, for one hour, each attempt re-signed with a
+fresh timestamp over the same body.
+
+## Async
+
+```python
+import asyncio
+
+from cryptunnel import Cryptunnel
+
+async def main():
+    async with Cryptunnel("<merchant id>", "<api key>", sandbox=True) as cryptunnel:
+        currencies = await cryptunnel.list_currencies()
+        payment = await cryptunnel.create_h2h_payment(10, "USD", "order-2", currencies[0]["code"])
+        print(payment["wallet_address"], payment["amount"], payment["currency"])
+
+asyncio.run(main())
+```
+
+## The whole surface
+
+| Method | Call |
+| --- | --- |
+| `create_widget_payment(amount, currency, external_id, ...)` | `POST /v1/payments/widget` |
+| `create_h2h_payment(amount, currency, external_id, target_currency, ...)` | `POST /v1/payments/h2h` |
+| `get_payment(payment_id)` | `GET /v1/payments/{id}` |
+| `list_payments(limit, offset)` | `GET /v1/payments` |
+| `list_currencies()` | `GET /v1/currencies` |
+| `get_merchant()` | `GET /v1/merchants` |
+| `verify_webhook(secret, headers, raw_body)` | local, no request |
+| `wait_for_payment(payment_id)` | polls `GET /v1/payments/{id}` |
+
+Every method exists on both `Cryptunnel` (await it) and `CryptunnelSync` (call it).
+
+Payment creation is idempotent on `external_id`: a retry after a network timeout returns the payment
+you already created instead of a second one. Repeating an `external_id` with a different amount or
+currency is rejected with `PAYMENT_ALREADY_EXISTS`.
+
+`get_payment` returns two shapes, and the status tells them apart: a `created` or `expired` payment
+carries no `amount`, `currency` or `wallet_address`, because nobody has picked a currency for it
+yet. Read them with `payment.get("amount")` rather than `payment["amount"]` unless you already know
+the status.
+
+`wait_for_payment` is for scripts and development - it polls every 5 seconds, backing off to 30, and
+raises `PaymentTimeoutError` after 30 minutes. In production the webhook is the guarantee: a buyer
+who closes the page still produces a callback.
+
+## Errors
+
+```python
+from cryptunnel import AuthenticationError, RateLimitError, ValidationError
+
+try:
+    cryptunnel.create_h2h_payment(10, "USD", "order-3", "DOGE")
+except ValidationError as error:
+    print(error.code)  # WALLET_NOT_FOUND - you have no active DOGE wallet
+except AuthenticationError:
+    print("check the merchant id and the api key")
+except RateLimitError as error:
+    print(error.retry_after)  # seconds to wait; None when the API sends no Retry-After header
+```
+
+`CryptunnelError` is the base; `AuthenticationError` (401), `NotFoundError` (404),
+`ValidationError` (400), `RateLimitError` (429) and `ApiError` (5xx and transport failures) derive
+from it. The raw API `code` is always on the exception.
+
+## Links
+
+- [Quickstart](https://docs.cryptunnel.io/docs/quickstart) - registration to first payment
+- [Sandbox and faucets](https://docs.cryptunnel.io/docs/sandbox) - test coins without spending any
+- [API reference](https://docs.cryptunnel.io)
+- Support: [GitHub Issues](https://github.com/cryptunnel/cryptunnel-python/issues)
+
+MIT licensed.

cryptunnel-1.0.0/README.md

@@ -0,0 +1,128 @@
+# cryptunnel
+
+Python SDK for [Cryptunnel](https://cryptunnel.io) - accept crypto payments straight into your own
+wallets. Async-first for bots on aiogram, with a blocking mirror for scripts.
+
+```bash
+pip install cryptunnel
+```
+
+`httpx` is the only dependency. Python 3.10+.
+
+## Create a sandbox payment
+
+```python
+from cryptunnel import CryptunnelSync
+
+cryptunnel = CryptunnelSync("<merchant id>", "<api key>", sandbox=True)
+
+print(cryptunnel.get_merchant())  # your credentials work if this prints your merchant
+
+payment = cryptunnel.create_widget_payment(
+    amount=10,
+    currency="USD",
+    external_id="order-1",
+    success_url="https://example.com/thanks",
+)
+print(payment["url"])  # send the buyer here
+```
+
+`sandbox=True` sets `is_test` on every payment it creates: the payer is offered testnet currencies
+only, and the payment is excluded from your stats and fees. It is the same host and the same key -
+the sandbox is a flag, not a second account.
+
+## Verify a webhook
+
+```python
+from flask import Flask, request
+
+from cryptunnel import verify_webhook
+
+app = Flask(__name__)
+WEBHOOK_SECRET = "<whsec_...>"
+
+@app.post("/cryptunnel")
+def callback():
+    if not verify_webhook(WEBHOOK_SECRET, request.headers, request.get_data()):
+        return "", 401
+    payment = request.get_json()
+    if payment["status"] in ("confirmed", "confirmed_manual"):
+        deliver(payment["external_id"])  # deduplicate on (id, status): retries repeat the same pair
+    return "", 200
+```
+
+Pass the raw body bytes as received - parsing and re-serialising the JSON changes the signature.
+A failed delivery is retried 60 times, once a minute, for one hour, each attempt re-signed with a
+fresh timestamp over the same body.
+
+## Async
+
+```python
+import asyncio
+
+from cryptunnel import Cryptunnel
+
+async def main():
+    async with Cryptunnel("<merchant id>", "<api key>", sandbox=True) as cryptunnel:
+        currencies = await cryptunnel.list_currencies()
+        payment = await cryptunnel.create_h2h_payment(10, "USD", "order-2", currencies[0]["code"])
+        print(payment["wallet_address"], payment["amount"], payment["currency"])
+
+asyncio.run(main())
+```
+
+## The whole surface
+
+| Method | Call |
+| --- | --- |
+| `create_widget_payment(amount, currency, external_id, ...)` | `POST /v1/payments/widget` |
+| `create_h2h_payment(amount, currency, external_id, target_currency, ...)` | `POST /v1/payments/h2h` |
+| `get_payment(payment_id)` | `GET /v1/payments/{id}` |
+| `list_payments(limit, offset)` | `GET /v1/payments` |
+| `list_currencies()` | `GET /v1/currencies` |
+| `get_merchant()` | `GET /v1/merchants` |
+| `verify_webhook(secret, headers, raw_body)` | local, no request |
+| `wait_for_payment(payment_id)` | polls `GET /v1/payments/{id}` |
+
+Every method exists on both `Cryptunnel` (await it) and `CryptunnelSync` (call it).
+
+Payment creation is idempotent on `external_id`: a retry after a network timeout returns the payment
+you already created instead of a second one. Repeating an `external_id` with a different amount or
+currency is rejected with `PAYMENT_ALREADY_EXISTS`.
+
+`get_payment` returns two shapes, and the status tells them apart: a `created` or `expired` payment
+carries no `amount`, `currency` or `wallet_address`, because nobody has picked a currency for it
+yet. Read them with `payment.get("amount")` rather than `payment["amount"]` unless you already know
+the status.
+
+`wait_for_payment` is for scripts and development - it polls every 5 seconds, backing off to 30, and
+raises `PaymentTimeoutError` after 30 minutes. In production the webhook is the guarantee: a buyer
+who closes the page still produces a callback.
+
+## Errors
+
+```python
+from cryptunnel import AuthenticationError, RateLimitError, ValidationError
+
+try:
+    cryptunnel.create_h2h_payment(10, "USD", "order-3", "DOGE")
+except ValidationError as error:
+    print(error.code)  # WALLET_NOT_FOUND - you have no active DOGE wallet
+except AuthenticationError:
+    print("check the merchant id and the api key")
+except RateLimitError as error:
+    print(error.retry_after)  # seconds to wait; None when the API sends no Retry-After header
+```
+
+`CryptunnelError` is the base; `AuthenticationError` (401), `NotFoundError` (404),
+`ValidationError` (400), `RateLimitError` (429) and `ApiError` (5xx and transport failures) derive
+from it. The raw API `code` is always on the exception.
+
+## Links
+
+- [Quickstart](https://docs.cryptunnel.io/docs/quickstart) - registration to first payment
+- [Sandbox and faucets](https://docs.cryptunnel.io/docs/sandbox) - test coins without spending any
+- [API reference](https://docs.cryptunnel.io)
+- Support: [GitHub Issues](https://github.com/cryptunnel/cryptunnel-python/issues)
+
+MIT licensed.

cryptunnel-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cryptunnel"
+version = "1.0.0"
+description = "Python SDK for Cryptunnel - accept crypto payments straight to your own wallets"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Cryptunnel" }]
+keywords = ["cryptunnel", "crypto", "payments", "usdt", "tron", "bitcoin", "ethereum"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Financial",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://cryptunnel.io"
+Documentation = "https://docs.cryptunnel.io"
+Issues = "https://github.com/cryptunnel/cryptunnel-python/issues"
+Source = "https://github.com/cryptunnel/cryptunnel-python"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cryptunnel"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

cryptunnel-1.0.0/src/cryptunnel/__init__.py

@@ -0,0 +1,38 @@
+"""Cryptunnel - accept crypto payments straight to your own wallets.
+
+```python
+from cryptunnel import CryptunnelSync
+
+cryptunnel = CryptunnelSync("<merchant id>", "<api key>", sandbox=True)
+payment = cryptunnel.create_widget_payment(10, "USD", "order-1")
+print(payment["url"])
+```
+"""
+
+from .client import DEFAULT_BASE_URL, TERMINAL_STATUSES, Cryptunnel, CryptunnelSync
+from .errors import (
+    ApiError,
+    AuthenticationError,
+    CryptunnelError,
+    NotFoundError,
+    PaymentTimeoutError,
+    RateLimitError,
+    ValidationError,
+)
+from .webhooks import verify_webhook
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "TERMINAL_STATUSES",
+    "ApiError",
+    "AuthenticationError",
+    "Cryptunnel",
+    "CryptunnelError",
+    "CryptunnelSync",
+    "NotFoundError",
+    "PaymentTimeoutError",
+    "RateLimitError",
+    "ValidationError",
+    "verify_webhook",
+]
+__version__ = "1.0.0"

cryptunnel-1.0.0/src/cryptunnel/client.py

@@ -0,0 +1,267 @@
+"""The Cryptunnel API clients: ``Cryptunnel`` (async) and ``CryptunnelSync``."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Mapping
+
+import httpx
+
+from .errors import ApiError, PaymentTimeoutError, RateLimitError, error_from_response
+
+DEFAULT_BASE_URL = "https://api.cryptunnel.io"
+DEFAULT_TIMEOUT = 30.0
+
+#: Statuses a payment never leaves.
+TERMINAL_STATUSES = frozenset({"confirmed", "confirmed_manual", "failed", "expired"})
+
+
+class _BaseClient:
+    """Request building and error mapping, shared by the async and the sync client.
+
+    The endpoint methods below are plain functions returning ``self._request(...)``: on the async
+    client that is a coroutine to await, on the sync client the parsed response.
+    """
+
+    def __init__(
+        self,
+        merchant_id: str,
+        api_key: str,
+        sandbox: bool = False,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.merchant_id = merchant_id
+        self.sandbox = sandbox
+        self.base_url = base_url.rstrip("/")
+        self._options: dict[str, Any] = {
+            "base_url": self.base_url,
+            "headers": {"x-merchant-id": merchant_id, "x-api-key": api_key},
+            "timeout": timeout,
+        }
+
+    def create_widget_payment(
+        self,
+        amount: float,
+        currency: str,
+        external_id: str,
+        *,
+        success_url: str | None = None,
+        fail_url: str | None = None,
+        callback_url: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        fee_payer: str | None = None,
+    ):
+        """Create a payment and get the widget url to send the payer to."""
+        body = self._payment_body(amount, currency, external_id, callback_url, metadata, fee_payer)
+        body.update(_present(success_url=success_url, fail_url=fail_url))
+        return self._request("POST", "/v1/payments/widget", json=body)
+
+    def create_h2h_payment(
+        self,
+        amount: float,
+        currency: str,
+        external_id: str,
+        target_currency: str,
+        *,
+        auto_trace: bool = False,
+        callback_url: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        fee_payer: str | None = None,
+    ):
+        """Create a payment and get the wallet address and crypto amount to show yourself.
+
+        ``target_currency`` must be one of the codes ``list_currencies`` returns.
+        """
+        body = self._payment_body(amount, currency, external_id, callback_url, metadata, fee_payer)
+        body["target_currency"] = target_currency
+        body["auto_trace"] = auto_trace
+        return self._request("POST", "/v1/payments/h2h", json=body)
+
+    def get_payment(self, payment_id: str):
+        """Read one payment by its Cryptunnel id."""
+        return self._request("GET", f"/v1/payments/{payment_id}")
+
+    def list_payments(self, limit: int = 20, offset: int = 0):
+        """List your payments, newest first."""
+        return self._request("GET", "/v1/payments", params={"limit": limit, "offset": offset})
+
+    def list_currencies(self):
+        """List the currencies you can receive - exactly the values ``target_currency`` accepts."""
+        return self._request("GET", "/v1/currencies", params={"is_test": _flag(self.sandbox)})
+
+    def get_merchant(self):
+        """Read your merchant - the call that tells you the credentials work."""
+        return self._request("GET", "/v1/merchants")
+
+    def _payment_body(
+        self,
+        amount: float,
+        currency: str,
+        external_id: str,
+        callback_url: str | None,
+        metadata: Mapping[str, Any] | None,
+        fee_payer: str | None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "amount": amount,
+            "currency": currency,
+            "external_id": external_id,
+            "is_test": self.sandbox,
+        }
+        body.update(_present(callback_url=callback_url, metadata=metadata, fee_payer=fee_payer))
+        return body
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    @staticmethod
+    def _payload(response: httpx.Response) -> Any:
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+        if response.is_success:
+            return payload
+        raise error_from_response(response.status_code, payload, _retry_after(response.headers))
+
+
+class Cryptunnel(_BaseClient):
+    """Async client - the one to use inside a bot or a web framework.
+
+    ```python
+    async with Cryptunnel(merchant_id, api_key, sandbox=True) as cryptunnel:
+        payment = await cryptunnel.create_widget_payment(10, "USD", "order-1")
+    ```
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._http = httpx.AsyncClient(**self._options)
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            response = await self._http.request(method, path, **kwargs)
+        except httpx.HTTPError as error:
+            raise ApiError(f"Request to {path} failed: {error}") from error
+        return self._payload(response)
+
+    async def wait_for_payment(
+        self,
+        payment_id: str,
+        *,
+        timeout: float = 1800,
+        first_delay: float = 5,
+        max_delay: float = 30,
+    ) -> Any:
+        """Poll until the payment reaches a terminal status.
+
+        For scripts and development. In production the webhook is the guarantee: a buyer who closes
+        the page still gets a callback, a polling process that dies does not.
+        """
+        waiter = _Waiter(timeout, first_delay, max_delay)
+        delay = waiter.next_delay()
+        while True:
+            await asyncio.sleep(delay)
+            if waiter.expired():
+                raise PaymentTimeoutError(f"Payment {payment_id} did not settle within {timeout} seconds")
+            try:
+                payment = await self.get_payment(payment_id)
+            except RateLimitError as error:
+                delay = waiter.next_delay(error.retry_after)
+                continue
+            if payment.get("status") in TERMINAL_STATUSES:
+                return payment
+            delay = waiter.next_delay()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "Cryptunnel":
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.close()
+
+
+class CryptunnelSync(_BaseClient):
+    """Blocking mirror of :class:`Cryptunnel` for scripts and one-off calls."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._http = httpx.Client(**self._options)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            response = self._http.request(method, path, **kwargs)
+        except httpx.HTTPError as error:
+            raise ApiError(f"Request to {path} failed: {error}") from error
+        return self._payload(response)
+
+    def wait_for_payment(
+        self,
+        payment_id: str,
+        *,
+        timeout: float = 1800,
+        first_delay: float = 5,
+        max_delay: float = 30,
+    ) -> Any:
+        """Poll until the payment reaches a terminal status - see :meth:`Cryptunnel.wait_for_payment`."""
+        waiter = _Waiter(timeout, first_delay, max_delay)
+        delay = waiter.next_delay()
+        while True:
+            time.sleep(delay)
+            if waiter.expired():
+                raise PaymentTimeoutError(f"Payment {payment_id} did not settle within {timeout} seconds")
+            try:
+                payment = self.get_payment(payment_id)
+            except RateLimitError as error:
+                delay = waiter.next_delay(error.retry_after)
+                continue
+            if payment.get("status") in TERMINAL_STATUSES:
+                return payment
+            delay = waiter.next_delay()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "CryptunnelSync":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+
+class _Waiter:
+    """Polling pace: exponential backoff, capped, never sleeping past the deadline."""
+
+    def __init__(self, timeout: float, first_delay: float, max_delay: float) -> None:
+        self.deadline = time.monotonic() + timeout
+        self.delay = first_delay
+        self.max_delay = max_delay
+
+    def expired(self) -> bool:
+        return time.monotonic() >= self.deadline
+
+    def next_delay(self, retry_after: float | None = None) -> float:
+        # The API sends Retry-After on a 429, but the backoff has to stand on its own if it ever stops
+        delay = self.delay if retry_after is None else retry_after
+        self.delay = min(self.delay * 2, self.max_delay)
+        return max(0.0, min(delay, self.deadline - time.monotonic()))
+
+
+def _retry_after(headers: Mapping[str, Any]) -> float | None:
+    value = headers.get("retry-after")
+    try:
+        return float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+
+
+def _flag(value: bool) -> str:
+    return "true" if value else "false"
+
+
+def _present(**values: Any) -> dict[str, Any]:
+    return {key: value for key, value in values.items() if value is not None}

cryptunnel-1.0.0/src/cryptunnel/errors.py

@@ -0,0 +1,74 @@
+"""Exceptions raised by the client - branch on the type, read the API code from ``code``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class CryptunnelError(Exception):
+    """Base for every error this package raises."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        status: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        # The raw API code, e.g. PAYMENT_ALREADY_EXISTS, CURRENCY_NOT_FOUND, WALLET_NOT_FOUND
+        self.code = code
+        self.status = status
+
+
+class AuthenticationError(CryptunnelError):
+    """401: wrong merchant id, wrong or rotated key, or a suspended merchant."""
+
+
+class NotFoundError(CryptunnelError):
+    """404: the payment or currency does not exist for this merchant."""
+
+
+class ValidationError(CryptunnelError):
+    """400: the request was rejected, see ``code`` for which rule."""
+
+
+class RateLimitError(CryptunnelError):
+    """429: too many requests. ``retry_after`` is None when the API sends no header."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        status: int | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message, code=code, status=status)
+        self.retry_after = retry_after
+
+
+class ApiError(CryptunnelError):
+    """A server-side failure or a transport error."""
+
+
+class PaymentTimeoutError(CryptunnelError):
+    """``wait_for_payment`` gave up before the payment reached a terminal status."""
+
+
+def error_from_response(status: int, payload: Any, retry_after: float | None = None) -> CryptunnelError:
+    """Map an API error response onto the exception hierarchy."""
+    body = payload if isinstance(payload, dict) else {}
+    code = body.get("code")
+    message = body.get("message") or f"Cryptunnel API returned {status}"
+
+    if status == 401:
+        return AuthenticationError(message, code=code, status=status)
+    if status == 404:
+        return NotFoundError(message, code=code, status=status)
+    if status == 429:
+        return RateLimitError(message, code=code, status=status, retry_after=retry_after)
+    if status == 400:
+        return ValidationError(message, code=code, status=status)
+    return ApiError(message, code=code, status=status)

cryptunnel-1.0.0/src/cryptunnel/webhooks.py

@@ -0,0 +1,50 @@
+"""Webhook signature verification - the one part of an integration that must not be hand-rolled."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from typing import Any, Mapping
+
+DEFAULT_TOLERANCE = 300
+
+
+def verify_webhook(
+    secret: str,
+    headers: Mapping[str, Any],
+    raw_body: bytes | str,
+    tolerance: int = DEFAULT_TOLERANCE,
+) -> bool:
+    """Verify a callback signed by Cryptunnel.
+
+    ``raw_body`` must be the bytes as received: parsing and re-serialising the JSON changes the
+    signature. Returns False for anything that does not verify - it never raises.
+    """
+    timestamp = _header(headers, "x-webhook-timestamp")
+    signature = _header(headers, "x-webhook-signature")
+    if not timestamp or not signature:
+        return False
+
+    try:
+        sent_at = int(timestamp)
+    except (TypeError, ValueError):
+        return False
+
+    if abs(time.time() - sent_at) > tolerance:
+        return False
+
+    body = raw_body.encode() if isinstance(raw_body, str) else raw_body
+    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
+    # compare_digest is constant time and safe for signatures of the wrong length
+    return hmac.compare_digest(expected, signature)
+
+
+def _header(headers: Mapping[str, Any], name: str) -> str | None:
+    value = headers.get(name)
+    if value is None:
+        # Plain dicts keep the casing the framework handed over
+        value = next((v for k, v in headers.items() if k.lower() == name), None)
+    if isinstance(value, bytes):
+        return value.decode()
+    return value if value is None else str(value)

cryptunnel-1.0.0/tests/test_client.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from cryptunnel import (
+    ApiError,
+    AuthenticationError,
+    Cryptunnel,
+    CryptunnelSync,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
+
+def client_returning(status: int, payload: dict, headers: dict | None = None):
+    seen: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        return httpx.Response(status, json=payload, headers=headers)
+
+    cryptunnel = CryptunnelSync("merchant-id", "ct_live_key", sandbox=True)
+    cryptunnel._http = httpx.Client(transport=httpx.MockTransport(handler), **cryptunnel._options)
+    return cryptunnel, seen
+
+
+def test_sandbox_marks_creates_as_test_payments():
+    cryptunnel, seen = client_returning(200, {"id": "pay-1", "url": "https://pay.cryptunnel.io/pay-1"})
+
+    payment = cryptunnel.create_widget_payment(10, "USD", "order-1", success_url="https://shop/ok")
+
+    assert payment["url"] == "https://pay.cryptunnel.io/pay-1"
+    body = seen[0].read().decode()
+    assert '"is_test": true' in body.replace('":', '": ')
+    assert seen[0].headers["x-merchant-id"] == "merchant-id"
+    assert "fail_url" not in body
+
+
+def test_sandbox_asks_for_the_testnet_currency_family():
+    cryptunnel, seen = client_returning(200, {})
+
+    cryptunnel.list_currencies()
+
+    assert seen[0].url.params["is_test"] == "true"
+
+
+def test_h2h_sends_the_target_currency():
+    cryptunnel, seen = client_returning(200, {"id": "pay-1"})
+
+    cryptunnel.create_h2h_payment(10, "USD", "order-1", "USDT")
+
+    assert '"target_currency"' in seen[0].read().decode()
+    assert seen[0].url.path == "/v1/payments/h2h"
+
+
+@pytest.mark.parametrize(
+    ("status", "expected"),
+    [
+        (400, ValidationError),
+        (401, AuthenticationError),
+        (404, NotFoundError),
+        (500, ApiError),
+    ],
+)
+def test_error_status_maps_to_its_exception(status, expected):
+    cryptunnel, _ = client_returning(status, {"code": "WALLET_NOT_FOUND", "message": "Wallet not found"})
+
+    with pytest.raises(expected) as raised:
+        cryptunnel.get_merchant()
+
+    assert raised.value.code == "WALLET_NOT_FOUND"
+    assert raised.value.status == status
+
+
+def test_rate_limit_carries_retry_after_when_the_header_is_there():
+    cryptunnel, _ = client_returning(429, {"code": "TOO_MANY"}, {"retry-after": "12"})
+
+    with pytest.raises(RateLimitError) as raised:
+        cryptunnel.get_merchant()
+
+    assert raised.value.retry_after == 12
+
+
+def test_rate_limit_without_a_header_leaves_retry_after_unset():
+    cryptunnel, _ = client_returning(429, {"code": "TOO_MANY"})
+
+    with pytest.raises(RateLimitError) as raised:
+        cryptunnel.get_merchant()
+
+    assert raised.value.retry_after is None
+
+
+def test_transport_failures_surface_as_api_errors():
+    def handler(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("connection refused")
+
+    cryptunnel = CryptunnelSync("merchant-id", "ct_live_key")
+    cryptunnel._http = httpx.Client(transport=httpx.MockTransport(handler), **cryptunnel._options)
+
+    with pytest.raises(ApiError):
+        cryptunnel.get_merchant()
+
+
+async def test_the_async_client_maps_errors_the_same_way():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(401, json={"code": "INVALID_CREDENTIALS", "message": "Invalid credentials"})
+
+    cryptunnel = Cryptunnel("merchant-id", "ct_live_key")
+    cryptunnel._http = httpx.AsyncClient(transport=httpx.MockTransport(handler), **cryptunnel._options)
+
+    with pytest.raises(AuthenticationError) as raised:
+        await cryptunnel.get_payment("pay-1")
+
+    assert raised.value.code == "INVALID_CREDENTIALS"
+    await cryptunnel.close()
+
+
+def test_base_url_is_honoured():
+    local = CryptunnelSync("merchant-id", "ct_live_key", base_url="http://localhost:3000/")
+    assert local._options["base_url"] == "http://localhost:3000"

cryptunnel-1.0.0/tests/test_webhooks.py

@@ -0,0 +1,52 @@
+import hashlib
+import hmac
+import time
+
+from cryptunnel import verify_webhook
+
+SECRET = "whsec_test"
+BODY = b'{"id":"n9cdFaTccYbXecVekHKW8Q","status":"confirmed"}'
+
+
+def sign(body: bytes, timestamp: int, secret: str = SECRET) -> dict[str, str]:
+    signature = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
+    return {"x-webhook-timestamp": str(timestamp), "x-webhook-signature": signature}
+
+
+def test_accepts_a_genuine_callback():
+    assert verify_webhook(SECRET, sign(BODY, int(time.time())), BODY) is True
+
+
+def test_accepts_headers_in_any_casing_and_a_string_body():
+    headers = {key.title(): value for key, value in sign(BODY, int(time.time())).items()}
+    assert verify_webhook(SECRET, headers, BODY.decode()) is True
+
+
+def test_rejects_a_tampered_body():
+    assert verify_webhook(SECRET, sign(BODY, int(time.time())), BODY + b" ") is False
+
+
+def test_rejects_a_stale_timestamp():
+    assert verify_webhook(SECRET, sign(BODY, int(time.time()) - 301), BODY) is False
+
+
+def test_accepts_a_stale_timestamp_within_a_wider_tolerance():
+    headers = sign(BODY, int(time.time()) - 301)
+    assert verify_webhook(SECRET, headers, BODY, tolerance=600) is True
+
+
+def test_rejects_a_signature_of_the_wrong_length():
+    headers = sign(BODY, int(time.time()))
+    headers["x-webhook-signature"] = headers["x-webhook-signature"][:10]
+    assert verify_webhook(SECRET, headers, BODY) is False
+
+
+def test_rejects_another_secret():
+    assert verify_webhook(SECRET, sign(BODY, int(time.time()), "whsec_other"), BODY) is False
+
+
+def test_rejects_missing_or_unparsable_headers():
+    assert verify_webhook(SECRET, {}, BODY) is False
+    headers = sign(BODY, int(time.time()))
+    headers["x-webhook-timestamp"] = "not-a-number"
+    assert verify_webhook(SECRET, headers, BODY) is False