coincircuit 0.2.0__tar.gz

coincircuit-0.2.0/.gitignore

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

coincircuit-0.2.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: coincircuit
+Version: 0.2.0
+Summary: Official Python SDK for the CoinCircuit API
+License-Expression: MIT
+Keywords: blockchain,coincircuit,crypto,payments,x402
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'

coincircuit-0.2.0/README.md

@@ -0,0 +1,91 @@
+# coincircuit
+
+Official CoinCircuit Python SDK. Supports both synchronous and asynchronous usage.
+
+## Install
+
+```bash
+pip install coincircuit
+```
+
+## Usage (Sync)
+
+```python
+from coincircuit import CoinCircuit
+
+cc = CoinCircuit(api_key="api_live_...")
+
+# Create a payment session
+session = cc.payments.create(
+    amount="10.00",
+    currency="USD",
+    asset="USDC",
+    chain="base",
+    customer={"email": "buyer@example.com"},
+)
+
+# List transactions
+result = cc.transactions.list(page=1, size=20)
+for tx in result.data:
+    print(tx)
+
+# Auto-paginate
+for tx in cc.transactions.list_auto_paginate():
+    print(tx)
+
+# Settle x402 gasless payment
+result = cc.x402.settle(
+    scheme="eip3009",
+    chain="base",
+    asset="USDC",
+    payload={
+        "from": "0xSender...",
+        "to": "0xDeposit...",
+        "value": "1000000",
+        "validAfter": "0",
+        "validBefore": "1774055094",
+        "nonce": "0xrandom32bytes...",
+        "signature": "0xsigned...",
+    },
+)
+```
+
+## Usage (Async)
+
+```python
+from coincircuit import AsyncCoinCircuit
+
+async with AsyncCoinCircuit(api_key="api_live_...") as cc:
+    session = await cc.payments.create(
+        amount="10.00",
+        currency="USD",
+    )
+```
+
+## Resources
+
+| Resource | Methods |
+|----------|---------|
+| `cc.payments` | create, list, get, generate_deposit_address, estimate |
+| `cc.x402` | settle, verify |
+| `cc.invoices` | create, list, get |
+| `cc.transactions` | list, get |
+| `cc.payouts` | create, list, get, estimate_fees |
+| `cc.balance` | get |
+| `cc.blockchain` | get_supported_assets, get_confirmations, get_gas_fees |
+| `cc.customers` | create, list, get |
+| `cc.refunds` | create_for_session, create_for_invoice, list, get, estimate |
+| `cc.settlements` | list, get |
+| `cc.rates` | convert, list |
+| `cc.payment_pages` | create, list, update, delete, sessions |
+| `cc.bank_accounts` | create, list, get, update, delete, banks |
+| `cc.crypto_addresses` | create, list, get, update, delete, validate |
+
+## Links
+
+- [API Reference](https://coincircuit.io/api-reference)
+- [Dashboard](https://dashboard.coincircuit.io)
+
+## License
+
+MIT

coincircuit-0.2.0/coincircuit/__init__.py

@@ -0,0 +1,168 @@
+"""CoinCircuit Python SDK.
+
+Usage (synchronous)::
+
+    from coincircuit import CoinCircuit
+
+    cc = CoinCircuit(api_key="sk_live_...")
+    session = cc.payments.create(
+        title="Order #123",
+        description="Widget purchase",
+        amount="10.00",
+        currency="USD",
+        customer={"email": "buyer@example.com"},
+        asset="USDC",
+        chain="base",
+    )
+
+Usage (asynchronous)::
+
+    from coincircuit import AsyncCoinCircuit
+
+    async_cc = AsyncCoinCircuit(api_key="sk_live_...")
+    session = await async_cc.payments.create(...)
+"""
+
+from .client import AsyncHttpClient, HttpClient
+from .errors import CoinCircuitApiError, CoinCircuitAuthError, CoinCircuitError
+from .pagination import PaginatedResponse
+from .resources.balance import AsyncBalanceResource, BalanceResource
+from .resources.blockchain import AsyncBlockchainResource, BlockchainResource
+from .resources.customers import AsyncCustomersResource, CustomersResource
+from .resources.invoices import AsyncInvoicesResource, InvoicesResource
+from .resources.payments import AsyncPaymentsResource, PaymentsResource
+from .resources.payouts import AsyncPayoutsResource, PayoutsResource
+from .resources.rates import AsyncRatesResource, RatesResource
+from .resources.refunds import AsyncRefundsResource, RefundsResource
+from .resources.settlements import AsyncSettlementsResource, SettlementsResource
+from .resources.transactions import AsyncTransactionsResource, TransactionsResource
+from .resources.x402 import AsyncX402Resource, X402Resource
+from .resources.payment_pages import AsyncPaymentPagesResource, PaymentPagesResource
+from .resources.bank_accounts import AsyncBankAccountsResource, BankAccountsResource
+from .resources.crypto_addresses import AsyncCryptoAddressesResource, CryptoAddressesResource
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Main clients
+    "CoinCircuit",
+    "AsyncCoinCircuit",
+    # Errors
+    "CoinCircuitError",
+    "CoinCircuitApiError",
+    "CoinCircuitAuthError",
+    # Pagination
+    "PaginatedResponse",
+    # Version
+    "__version__",
+]
+
+
+class CoinCircuit:
+    """Synchronous CoinCircuit API client.
+
+    Provides access to all CoinCircuit API resources through
+    namespace attributes (e.g. ``cc.payments``, ``cc.invoices``).
+
+    Args:
+        api_key: Your CoinCircuit API key (e.g. "sk_live_...").
+        base_url: API base URL. Defaults to https://api.coincircuit.io.
+        timeout: Request timeout in seconds. Defaults to 30.
+        max_retries: Max retry attempts for transient errors. Defaults to 2.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.coincircuit.io",
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        self._client = HttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        # Resource namespaces
+        self.payments = PaymentsResource(self._client)
+        self.x402 = X402Resource(self._client)
+        self.invoices = InvoicesResource(self._client)
+        self.transactions = TransactionsResource(self._client)
+        self.payouts = PayoutsResource(self._client)
+        self.balance = BalanceResource(self._client)
+        self.blockchain = BlockchainResource(self._client)
+        self.customers = CustomersResource(self._client)
+        self.refunds = RefundsResource(self._client)
+        self.settlements = SettlementsResource(self._client)
+        self.rates = RatesResource(self._client)
+        self.payment_pages = PaymentPagesResource(self._client)
+        self.bank_accounts = BankAccountsResource(self._client)
+        self.crypto_addresses = CryptoAddressesResource(self._client)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release resources."""
+        self._client.close()
+
+    def __enter__(self) -> "CoinCircuit":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncCoinCircuit:
+    """Asynchronous CoinCircuit API client.
+
+    Provides the same resource namespaces as ``CoinCircuit`` but all
+    methods are coroutines.
+
+    Args:
+        api_key: Your CoinCircuit API key (e.g. "sk_live_...").
+        base_url: API base URL. Defaults to https://api.coincircuit.io.
+        timeout: Request timeout in seconds. Defaults to 30.
+        max_retries: Max retry attempts for transient errors. Defaults to 2.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.coincircuit.io",
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        self._client = AsyncHttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        # Resource namespaces
+        self.payments = AsyncPaymentsResource(self._client)
+        self.x402 = AsyncX402Resource(self._client)
+        self.invoices = AsyncInvoicesResource(self._client)
+        self.transactions = AsyncTransactionsResource(self._client)
+        self.payouts = AsyncPayoutsResource(self._client)
+        self.balance = AsyncBalanceResource(self._client)
+        self.blockchain = AsyncBlockchainResource(self._client)
+        self.customers = AsyncCustomersResource(self._client)
+        self.refunds = AsyncRefundsResource(self._client)
+        self.settlements = AsyncSettlementsResource(self._client)
+        self.rates = AsyncRatesResource(self._client)
+        self.payment_pages = AsyncPaymentPagesResource(self._client)
+        self.bank_accounts = AsyncBankAccountsResource(self._client)
+        self.crypto_addresses = AsyncCryptoAddressesResource(self._client)
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client and release resources."""
+        await self._client.close()
+
+    async def __aenter__(self) -> "AsyncCoinCircuit":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

coincircuit-0.2.0/coincircuit/client.py

@@ -0,0 +1,333 @@
+"""Low-level HTTP client with retries, auth, and envelope unwrapping."""
+
+import time
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import httpx
+
+from .errors import CoinCircuitApiError, CoinCircuitAuthError, CoinCircuitError
+from .pagination import PaginatedResponse
+
+DEFAULT_BASE_URL = "https://api.coincircuit.io"
+DEFAULT_TIMEOUT = 30.0
+MAX_RETRIES = 2
+RETRYABLE_STATUS_CODES = (429, 500, 502, 503, 504)
+
+
+def _build_headers(api_key: str) -> Dict[str, str]:
+    return {
+        "x-api-key": api_key,
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+
+
+def _parse_response(response: httpx.Response) -> Any:
+    """Parse the response, raise on errors, unwrap the envelope."""
+    status = response.status_code
+
+    # Try to decode JSON body
+    try:
+        body = response.json()
+    except Exception:
+        body = {}
+
+    # Auth errors (401, 403)
+    if status in (401, 403):
+        message = body.get("message", "Authentication failed")
+        if isinstance(message, list):
+            message = "; ".join(message)
+        raise CoinCircuitAuthError(
+            message=message,
+            status_code=status,
+            body=body,
+        )
+
+    # Other error status codes
+    if status >= 400:
+        message = body.get("message", f"API request failed with status {status}")
+        if isinstance(message, list):
+            message = "; ".join(message)
+        raise CoinCircuitApiError(
+            message=message,
+            status_code=status,
+            body=body,
+        )
+
+    # Envelope unwrapping: {"success": bool, "message": str, "data": T}
+    # If the body matches the envelope format, return just "data".
+    if isinstance(body, dict) and "success" in body:
+        if not body.get("success", True):
+            raise CoinCircuitApiError(
+                message=body.get("message", "Request was not successful"),
+                status_code=status,
+                body=body,
+            )
+        # Return data if present, otherwise the full body
+        if "data" in body:
+            return body["data"]
+        return body
+
+    return body
+
+
+def _parse_paginated_response(response: httpx.Response) -> PaginatedResponse:
+    """Parse a paginated response, returning a PaginatedResponse wrapper."""
+    status = response.status_code
+
+    try:
+        body = response.json()
+    except Exception:
+        body = {}
+
+    if status in (401, 403):
+        message = body.get("message", "Authentication failed")
+        if isinstance(message, list):
+            message = "; ".join(message)
+        raise CoinCircuitAuthError(
+            message=message,
+            status_code=status,
+            body=body,
+        )
+
+    if status >= 400:
+        message = body.get("message", f"API request failed with status {status}")
+        if isinstance(message, list):
+            message = "; ".join(message)
+        raise CoinCircuitApiError(
+            message=message,
+            status_code=status,
+            body=body,
+        )
+
+    if isinstance(body, dict) and "success" in body:
+        if not body.get("success", True):
+            raise CoinCircuitApiError(
+                message=body.get("message", "Request was not successful"),
+                status_code=status,
+                body=body,
+            )
+
+    data = body.get("data", [])
+    meta = body.get("meta", {"page": 1, "size": len(data), "total": len(data), "totalPages": 1})
+    return PaginatedResponse(data=data, meta=meta)
+
+
+def _backoff_delay(attempt: int) -> float:
+    """Exponential backoff: 0.5s, 1.0s, 2.0s, etc."""
+    return 0.5 * (2 ** attempt)
+
+
+class HttpClient:
+    """Synchronous HTTP client for the CoinCircuit API.
+
+    Handles authentication, retries with exponential backoff, and
+    response envelope unwrapping.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = MAX_RETRIES,
+    ) -> None:
+        if not api_key:
+            raise CoinCircuitError("api_key is required")
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=_build_headers(api_key),
+            timeout=timeout,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Make a request, retry on transient errors, unwrap envelope."""
+        # Strip None values from params
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        last_error: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method=method,
+                    url=path,
+                    params=params,
+                    json=json_body,
+                )
+                if response.status_code in RETRYABLE_STATUS_CODES and attempt < self.max_retries:
+                    time.sleep(_backoff_delay(attempt))
+                    continue
+                return _parse_response(response)
+            except (CoinCircuitAuthError, CoinCircuitApiError):
+                raise
+            except httpx.HTTPError as exc:
+                last_error = exc
+                if attempt < self.max_retries:
+                    time.sleep(_backoff_delay(attempt))
+                    continue
+                raise CoinCircuitError(f"HTTP request failed: {exc}") from exc
+
+        # Should not reach here, but just in case
+        raise CoinCircuitError(f"Request failed after {self.max_retries + 1} attempts")
+
+    def request_paginated(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> PaginatedResponse:
+        """Make a request and return a PaginatedResponse."""
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        last_error: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method=method,
+                    url=path,
+                    params=params,
+                )
+                if response.status_code in RETRYABLE_STATUS_CODES and attempt < self.max_retries:
+                    time.sleep(_backoff_delay(attempt))
+                    continue
+                return _parse_paginated_response(response)
+            except (CoinCircuitAuthError, CoinCircuitApiError):
+                raise
+            except httpx.HTTPError as exc:
+                last_error = exc
+                if attempt < self.max_retries:
+                    time.sleep(_backoff_delay(attempt))
+                    continue
+                raise CoinCircuitError(f"HTTP request failed: {exc}") from exc
+
+        raise CoinCircuitError(f"Request failed after {self.max_retries + 1} attempts")
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncHttpClient:
+    """Asynchronous HTTP client for the CoinCircuit API.
+
+    Same behaviour as ``HttpClient`` but uses ``httpx.AsyncClient``.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = MAX_RETRIES,
+    ) -> None:
+        if not api_key:
+            raise CoinCircuitError("api_key is required")
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=_build_headers(api_key),
+            timeout=timeout,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Make an async request, retry on transient errors, unwrap envelope."""
+        import asyncio
+
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        last_error: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method=method,
+                    url=path,
+                    params=params,
+                    json=json_body,
+                )
+                if response.status_code in RETRYABLE_STATUS_CODES and attempt < self.max_retries:
+                    await asyncio.sleep(_backoff_delay(attempt))
+                    continue
+                return _parse_response(response)
+            except (CoinCircuitAuthError, CoinCircuitApiError):
+                raise
+            except httpx.HTTPError as exc:
+                last_error = exc
+                if attempt < self.max_retries:
+                    await asyncio.sleep(_backoff_delay(attempt))
+                    continue
+                raise CoinCircuitError(f"HTTP request failed: {exc}") from exc
+
+        raise CoinCircuitError(f"Request failed after {self.max_retries + 1} attempts")
+
+    async def request_paginated(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> PaginatedResponse:
+        """Make an async request and return a PaginatedResponse."""
+        import asyncio
+
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        last_error: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method=method,
+                    url=path,
+                    params=params,
+                )
+                if response.status_code in RETRYABLE_STATUS_CODES and attempt < self.max_retries:
+                    await asyncio.sleep(_backoff_delay(attempt))
+                    continue
+                return _parse_paginated_response(response)
+            except (CoinCircuitAuthError, CoinCircuitApiError):
+                raise
+            except httpx.HTTPError as exc:
+                last_error = exc
+                if attempt < self.max_retries:
+                    await asyncio.sleep(_backoff_delay(attempt))
+                    continue
+                raise CoinCircuitError(f"HTTP request failed: {exc}") from exc
+
+        raise CoinCircuitError(f"Request failed after {self.max_retries + 1} attempts")
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHttpClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

coincircuit-0.2.0/coincircuit/errors.py

@@ -0,0 +1,47 @@
+"""CoinCircuit SDK error classes."""
+
+from typing import Any, Dict, Optional
+
+
+class CoinCircuitError(Exception):
+    """Base error for all CoinCircuit SDK errors."""
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(self.message)
+
+
+class CoinCircuitApiError(CoinCircuitError):
+    """Raised when the CoinCircuit API returns a non-success response."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.status_code = status_code
+        self.body = body or {}
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"CoinCircuitApiError({self.status_code}): {self.message}"
+
+    def __repr__(self) -> str:
+        return (
+            f"CoinCircuitApiError(message={self.message!r}, "
+            f"status_code={self.status_code!r})"
+        )
+
+
+class CoinCircuitAuthError(CoinCircuitApiError):
+    """Raised when the API returns 401 Unauthorized or 403 Forbidden."""
+
+    def __str__(self) -> str:
+        return f"CoinCircuitAuthError({self.status_code}): {self.message}"
+
+    def __repr__(self) -> str:
+        return (
+            f"CoinCircuitAuthError(message={self.message!r}, "
+            f"status_code={self.status_code!r})"
+        )