decane-sdk 0.8.0__tar.gz

decane_sdk-0.8.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/

decane_sdk-0.8.0/LICENSE

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

decane_sdk-0.8.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.5
+Name: decane-sdk
+Version: 0.8.0
+Summary: Official Python SDK for Decane — institutional liquidity rail for crypto settlement
+Project-URL: Homepage, https://decane.io
+Project-URL: Documentation, https://decane.io/docs
+Project-URL: Repository, https://github.com/Decane-io/decane-python
+Project-URL: Issues, https://github.com/Decane-io/decane-python/issues
+Author-email: Decane <dev@decane.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bitcoin,crypto,ethereum,payment-gateway,payments,stablecoins
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Point-Of-Sale
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# decane-sdk
+
+Official Python SDK for Decane — institutional liquidity rail for crypto settlement.
+
+> **Renamed from granthe.** The old package was `granthe` on PyPI. The API and webhook formats are unchanged, and the server still sends `Granthe-Signature` (and `X-Granthe-Signature`) for older integrations. Read `Decane-Signature` first and fall back to `Granthe-Signature` if you handle both.
+
+[![PyPI](https://img.shields.io/pypi/v/decane-sdk)](https://pypi.org/project/decane-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/decane-sdk)](https://pypi.org/project/decane-sdk/)
+
+## Install
+
+```bash
+pip install decane-sdk
+```
+
+## Quick Start
+
+```python
+from decane import Decane
+
+decane = Decane(api_key="gr_...", webhook_secret="gr_whsec_...")
+
+# Create a payment invoice
+invoice = decane.invoices.create(
+    amount=100.00,
+    crypto_currency="USDT",
+    network="tron",
+    description="Premium Plan",
+    customer_email="buyer@example.com",
+    idempotency_key="order-1042",  # optional, safe to retry
+)
+print(f"Pay to: {invoice.wallet_address}")
+print(f"Status: {invoice.status}")
+
+# Request a payout
+payout = decane.payouts.create(
+    amount=50.00,
+    currency="USDT",
+    network="tron",
+    recipient_address="TXyz...recipientAddress",
+    idempotency_key="payout-1042",  # optional, safe to retry
+)
+print(f"Payout ID: {payout.id}")
+```
+
+## Async Support
+
+```python
+from decane import AsyncFlow
+
+async with AsyncFlow(api_key="gr_...") as flow:
+    invoice = await decane.invoices.create(
+        amount=100, crypto_currency="USDT", network="ethereum",
+    )
+```
+
+## Resources
+
+### Invoices
+
+```python
+# Create
+invoice = decane.invoices.create(amount=100, crypto_currency="USDT", network="tron")
+
+# Get by ID
+invoice = decane.invoices.get("inv_abc123")
+
+# List with filters
+result = decane.invoices.list(status="paid", page=1, limit=20)
+for inv in result.items:
+    print(inv.id, inv.amount, inv.status)
+
+# Cancel
+decane.invoices.cancel("inv_abc123")
+```
+
+### Payouts
+
+```python
+# Single payout
+payout = decane.payouts.create(
+    amount=50, currency="USDT", network="tron",
+    recipient_address="TXyz...addr",
+)
+
+# Batch payout
+payouts = decane.payouts.create_batch([
+    {"amount": 50, "currency": "USDT", "network": "tron", "recipient_address": "TXyz..."},
+    {"amount": 25, "currency": "USDT", "network": "tron", "recipient_address": "TAbc..."},
+])
+
+# Check status
+payout = decane.payouts.get("pout_abc123")
+```
+
+### Wallets
+
+```python
+# Generate a new deposit wallet
+wallet = decane.wallets.generate(network="ethereum", currency="USDT")
+print(wallet.address)
+
+# List wallets
+result = decane.wallets.list(network="tron")
+
+# Check balance
+wallet = decane.wallets.balance("wal_abc123")
+```
+
+### Swaps
+
+```python
+# Get a quote
+quote = flow.swaps.quote("BTC", "USDT", amount=0.01)
+print(f"Rate: {quote.rate}, You get: {quote.to_amount} USDT")
+
+# Execute swap
+swap = flow.swaps.create("BTC", "USDT", amount=0.01)
+```
+
+### Webhooks
+
+```python
+from decane import Decane, InvalidSignatureError
+
+decane = Decane(api_key="gr_...", webhook_secret="gr_whsec_...")
+
+# In your webhook handler. Use the raw body, not re-serialized JSON.
+def handle_webhook(request):
+    payload = request.body
+    header = request.headers.get("Decane-Signature") or request.headers["Granthe-Signature"]  # t=<unix>,v1=<hex>
+
+    try:
+        event = decane.webhooks.construct_event(payload, header, tolerance=300)
+    except InvalidSignatureError:
+        return {"error": "Invalid signature"}, 400
+
+    # X-Decane-Delivery is the same on every retry, so use it to drop duplicates.
+    if event.type == "invoice.completed":
+        invoice_id = event.data["id"]
+        print(f"Invoice {invoice_id} completed!")
+
+    return {"status": "ok"}
+```
+
+`decane.webhooks.verify_signature(payload, header)` returns a bool if you want to parse the body yourself. The old `webhooks.verify(payload, signature)` for `X-Decane-Signature` (or `X-Granthe-Signature`) still works but is deprecated, because it has no timestamp check.
+
+## Error Handling
+
+```python
+from decane import Decane, DecaneError, AuthenticationError, RateLimitError
+
+decane = Decane(api_key="gr_...")
+
+try:
+    invoice = decane.invoices.create(amount=100, crypto_currency="USDT", network="tron")
+except AuthenticationError:
+    print("Bad API key")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+except DecaneError as e:
+    print(f"Error: {e.message} (code={e.code}, status={e.status})")
+```
+
+## Configuration
+
+```python
+decane = Decane(
+    api_key="gr_...",
+    webhook_secret="gr_whsec_...",      # For webhook verification
+    base_url="https://api.decane.io/api/v1",  # Default
+    timeout=30.0,                     # Request timeout in seconds
+)
+```
+
+## Supported Networks
+
+Bitcoin, Ethereum, Tron, BNB Chain, Solana, Ripple, Polygon, Avalanche, Dogecoin, Litecoin, TON, and more.
+
+## License
+
+MIT

decane_sdk-0.8.0/README.md

@@ -0,0 +1,182 @@
+# decane-sdk
+
+Official Python SDK for Decane — institutional liquidity rail for crypto settlement.
+
+> **Renamed from granthe.** The old package was `granthe` on PyPI. The API and webhook formats are unchanged, and the server still sends `Granthe-Signature` (and `X-Granthe-Signature`) for older integrations. Read `Decane-Signature` first and fall back to `Granthe-Signature` if you handle both.
+
+[![PyPI](https://img.shields.io/pypi/v/decane-sdk)](https://pypi.org/project/decane-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/decane-sdk)](https://pypi.org/project/decane-sdk/)
+
+## Install
+
+```bash
+pip install decane-sdk
+```
+
+## Quick Start
+
+```python
+from decane import Decane
+
+decane = Decane(api_key="gr_...", webhook_secret="gr_whsec_...")
+
+# Create a payment invoice
+invoice = decane.invoices.create(
+    amount=100.00,
+    crypto_currency="USDT",
+    network="tron",
+    description="Premium Plan",
+    customer_email="buyer@example.com",
+    idempotency_key="order-1042",  # optional, safe to retry
+)
+print(f"Pay to: {invoice.wallet_address}")
+print(f"Status: {invoice.status}")
+
+# Request a payout
+payout = decane.payouts.create(
+    amount=50.00,
+    currency="USDT",
+    network="tron",
+    recipient_address="TXyz...recipientAddress",
+    idempotency_key="payout-1042",  # optional, safe to retry
+)
+print(f"Payout ID: {payout.id}")
+```
+
+## Async Support
+
+```python
+from decane import AsyncFlow
+
+async with AsyncFlow(api_key="gr_...") as flow:
+    invoice = await decane.invoices.create(
+        amount=100, crypto_currency="USDT", network="ethereum",
+    )
+```
+
+## Resources
+
+### Invoices
+
+```python
+# Create
+invoice = decane.invoices.create(amount=100, crypto_currency="USDT", network="tron")
+
+# Get by ID
+invoice = decane.invoices.get("inv_abc123")
+
+# List with filters
+result = decane.invoices.list(status="paid", page=1, limit=20)
+for inv in result.items:
+    print(inv.id, inv.amount, inv.status)
+
+# Cancel
+decane.invoices.cancel("inv_abc123")
+```
+
+### Payouts
+
+```python
+# Single payout
+payout = decane.payouts.create(
+    amount=50, currency="USDT", network="tron",
+    recipient_address="TXyz...addr",
+)
+
+# Batch payout
+payouts = decane.payouts.create_batch([
+    {"amount": 50, "currency": "USDT", "network": "tron", "recipient_address": "TXyz..."},
+    {"amount": 25, "currency": "USDT", "network": "tron", "recipient_address": "TAbc..."},
+])
+
+# Check status
+payout = decane.payouts.get("pout_abc123")
+```
+
+### Wallets
+
+```python
+# Generate a new deposit wallet
+wallet = decane.wallets.generate(network="ethereum", currency="USDT")
+print(wallet.address)
+
+# List wallets
+result = decane.wallets.list(network="tron")
+
+# Check balance
+wallet = decane.wallets.balance("wal_abc123")
+```
+
+### Swaps
+
+```python
+# Get a quote
+quote = flow.swaps.quote("BTC", "USDT", amount=0.01)
+print(f"Rate: {quote.rate}, You get: {quote.to_amount} USDT")
+
+# Execute swap
+swap = flow.swaps.create("BTC", "USDT", amount=0.01)
+```
+
+### Webhooks
+
+```python
+from decane import Decane, InvalidSignatureError
+
+decane = Decane(api_key="gr_...", webhook_secret="gr_whsec_...")
+
+# In your webhook handler. Use the raw body, not re-serialized JSON.
+def handle_webhook(request):
+    payload = request.body
+    header = request.headers.get("Decane-Signature") or request.headers["Granthe-Signature"]  # t=<unix>,v1=<hex>
+
+    try:
+        event = decane.webhooks.construct_event(payload, header, tolerance=300)
+    except InvalidSignatureError:
+        return {"error": "Invalid signature"}, 400
+
+    # X-Decane-Delivery is the same on every retry, so use it to drop duplicates.
+    if event.type == "invoice.completed":
+        invoice_id = event.data["id"]
+        print(f"Invoice {invoice_id} completed!")
+
+    return {"status": "ok"}
+```
+
+`decane.webhooks.verify_signature(payload, header)` returns a bool if you want to parse the body yourself. The old `webhooks.verify(payload, signature)` for `X-Decane-Signature` (or `X-Granthe-Signature`) still works but is deprecated, because it has no timestamp check.
+
+## Error Handling
+
+```python
+from decane import Decane, DecaneError, AuthenticationError, RateLimitError
+
+decane = Decane(api_key="gr_...")
+
+try:
+    invoice = decane.invoices.create(amount=100, crypto_currency="USDT", network="tron")
+except AuthenticationError:
+    print("Bad API key")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+except DecaneError as e:
+    print(f"Error: {e.message} (code={e.code}, status={e.status})")
+```
+
+## Configuration
+
+```python
+decane = Decane(
+    api_key="gr_...",
+    webhook_secret="gr_whsec_...",      # For webhook verification
+    base_url="https://api.decane.io/api/v1",  # Default
+    timeout=30.0,                     # Request timeout in seconds
+)
+```
+
+## Supported Networks
+
+Bitcoin, Ethereum, Tron, BNB Chain, Solana, Ripple, Polygon, Avalanche, Dogecoin, Litecoin, TON, and more.
+
+## License
+
+MIT

decane_sdk-0.8.0/decane/__init__.py

@@ -0,0 +1,45 @@
+"""Decane — Official Python SDK for institutional liquidity rail for crypto settlement."""
+
+from .client import Decane, AsyncDecane
+from .errors import (
+    DecaneError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+    InvalidSignatureError,
+)
+from .types import (
+    Invoice,
+    InvoiceStatus,
+    Payment,
+    Payout,
+    PayoutStatus,
+    Wallet,
+    SwapQuote,
+    Swap,
+    WebhookEvent,
+)
+
+__version__ = "0.8.0"
+__all__ = [
+    "Decane",
+    "AsyncDecane",
+    "DecaneError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "InvalidSignatureError",
+    "Invoice",
+    "InvoiceStatus",
+    "Payment",
+    "Payout",
+    "PayoutStatus",
+    "Wallet",
+    "SwapQuote",
+    "Swap",
+    "WebhookEvent",
+]

decane_sdk-0.8.0/decane/_internal/http.py

@@ -0,0 +1,195 @@
+"""HTTP transport layer for Decane SDK."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any
+
+import httpx
+
+from ..errors import (
+    AuthenticationError,
+    DecaneError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+DEFAULT_BASE_URL = "https://api.decane.io/api/v1/"
+DEFAULT_TIMEOUT = 30.0
+MAX_RETRIES = 3
+RETRY_STATUSES = {429, 500, 502, 503, 504}
+
+
+def _build_headers(api_key: str, api_secret: str | None = None) -> dict[str, str]:
+    headers = {
+        "X-API-Key": api_key,
+        "Content-Type": "application/json",
+        "User-Agent": "decane-python/0.8.0",
+    }
+    if api_secret:
+        headers["X-API-Secret"] = api_secret
+    return headers
+
+
+def _with_idempotency(kwargs: dict[str, Any], key: str | None) -> dict[str, Any]:
+    """Return kwargs with an Idempotency-Key header (generated if not given)."""
+    headers = dict(kwargs.get("headers") or {})
+    headers["Idempotency-Key"] = key or str(uuid.uuid4())
+    return {**kwargs, "headers": headers}
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Raise typed SDK errors from HTTP responses."""
+    if response.status_code < 400:
+        return
+
+    try:
+        body = response.json()
+    except Exception:
+        body = {"detail": response.text}
+
+    message = body.get("detail", body.get("message", body.get("error", str(body))))
+    code = body.get("code")
+
+    if response.status_code == 401:
+        raise AuthenticationError(message)
+    if response.status_code == 404:
+        raise NotFoundError(message)
+    if response.status_code == 422:
+        raise ValidationError(message, errors=body.get("errors"))
+    if response.status_code == 429:
+        retry_after = response.headers.get("Retry-After")
+        raise RateLimitError(message, retry_after=float(retry_after) if retry_after else None)
+    if response.status_code >= 500:
+        raise ServerError(message)
+
+    raise DecaneError(message, code=code, status=response.status_code)
+
+
+class SyncHTTP:
+    """Synchronous HTTP client with retry logic."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: float, api_secret: str | None = None):
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers=_build_headers(api_key, api_secret),
+            timeout=timeout,
+        )
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        last_exc: Exception | None = None
+        for attempt in range(MAX_RETRIES):
+            try:
+                response = self._client.request(method, path, **kwargs)
+                if response.status_code in RETRY_STATUSES and attempt < MAX_RETRIES - 1:
+                    wait = (2**attempt) * 0.5
+                    if response.status_code == 429:
+                        retry_after = response.headers.get("Retry-After")
+                        if retry_after:
+                            wait = float(retry_after)
+                    time.sleep(wait)
+                    continue
+                _raise_for_status(response)
+                if response.status_code == 204:
+                    return None
+                return response.json()
+            except (httpx.ConnectError, httpx.TimeoutException) as e:
+                last_exc = e
+                if attempt < MAX_RETRIES - 1:
+                    time.sleep((2**attempt) * 0.5)
+                    continue
+                raise DecaneError(f"Connection error: {e}", code="network_error") from e
+        if last_exc:
+            raise DecaneError(f"Max retries exceeded: {last_exc}", code="network_error") from last_exc
+        raise DecaneError("Unexpected error", code="unknown")
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, *, idempotency_key: str | None = None, **kwargs: Any) -> Any:
+        if idempotency_key is not None:
+            kwargs = _with_idempotency(kwargs, idempotency_key)
+        return self.request("POST", path, **kwargs)
+
+    def post_idempotent(self, path: str, *, idempotency_key: str | None = None, **kwargs: Any) -> Any:
+        """POST with an Idempotency-Key header (random UUID if none given)."""
+        return self.request("POST", path, **_with_idempotency(kwargs, idempotency_key))
+
+    def put(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PUT", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self.request("DELETE", path, **kwargs)
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncHTTP:
+    """Async HTTP client with retry logic."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: float, api_secret: str | None = None):
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers=_build_headers(api_key, api_secret),
+            timeout=timeout,
+        )
+
+    async def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        import asyncio
+
+        last_exc: Exception | None = None
+        for attempt in range(MAX_RETRIES):
+            try:
+                response = await self._client.request(method, path, **kwargs)
+                if response.status_code in RETRY_STATUSES and attempt < MAX_RETRIES - 1:
+                    wait = (2**attempt) * 0.5
+                    if response.status_code == 429:
+                        retry_after = response.headers.get("Retry-After")
+                        if retry_after:
+                            wait = float(retry_after)
+                    await asyncio.sleep(wait)
+                    continue
+                _raise_for_status(response)
+                if response.status_code == 204:
+                    return None
+                return response.json()
+            except (httpx.ConnectError, httpx.TimeoutException) as e:
+                last_exc = e
+                if attempt < MAX_RETRIES - 1:
+                    await asyncio.sleep((2**attempt) * 0.5)
+                    continue
+                raise DecaneError(f"Connection error: {e}", code="network_error") from e
+        if last_exc:
+            raise DecaneError(f"Max retries exceeded: {last_exc}", code="network_error") from last_exc
+        raise DecaneError("Unexpected error", code="unknown")
+
+    async def get(self, path: str, **kwargs: Any) -> Any:
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, *, idempotency_key: str | None = None, **kwargs: Any) -> Any:
+        if idempotency_key is not None:
+            kwargs = _with_idempotency(kwargs, idempotency_key)
+        return await self.request("POST", path, **kwargs)
+
+    async def post_idempotent(self, path: str, *, idempotency_key: str | None = None, **kwargs: Any) -> Any:
+        """POST with an Idempotency-Key header (random UUID if none given)."""
+        return await self.request("POST", path, **_with_idempotency(kwargs, idempotency_key))
+
+    async def put(self, path: str, **kwargs: Any) -> Any:
+        return await self.request("PUT", path, **kwargs)
+
+    async def patch(self, path: str, **kwargs: Any) -> Any:
+        return await self.request("PATCH", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs: Any) -> Any:
+        return await self.request("DELETE", path, **kwargs)
+
+    async def close(self) -> None:
+        await self._client.aclose()