cryptochief-crypto-processing-python 0.1.0__py3-none-any.whl

cryptochief/services/base.py

@@ -0,0 +1,24 @@
+"""Shared base for the domain services."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .._models import to_payload
+
+if TYPE_CHECKING:
+    from ..client import CryptoChiefClient
+
+
+class BaseService:
+    """Holds the client reference and a signed-POST helper.
+
+    Request bodies are serialized with :func:`to_payload` (drops ``None``); the
+    field names already match the wire, so there is no case conversion.
+    """
+
+    def __init__(self, client: "CryptoChiefClient") -> None:
+        self._client = client
+
+    async def _post(self, path: str, body: Any = None) -> Any:
+        return await self._client.request(path, to_payload(body))

cryptochief/services/blockchain.py

@@ -0,0 +1,76 @@
+"""Read-only on-chain queries: enabled assets, balances, tx status."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, List, Optional
+
+from .._models import from_dict
+from .base import BaseService
+
+
+@dataclass(kw_only=True)
+class AvailableContract:
+    network: Optional[str] = None
+    coin: Optional[str] = None
+    contract: Optional[str] = None
+    type: Optional[str] = None  # "native" or "token"
+    decimals: int = 0
+
+
+@dataclass(kw_only=True)
+class AvailableContractsResponse:
+    items: Optional[List[AvailableContract]] = None
+
+
+@dataclass(kw_only=True)
+class WalletBalanceRow:
+    address: str = ""
+    value: Optional[str] = None
+    human_value: Optional[str] = None
+    decimals: int = 0
+    contract: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class TxStatusRow:
+    confirmations: int = 0
+    fee: Optional[str] = None
+    human_fee: Optional[str] = None
+    block_number: Optional[int] = None
+    status: Optional[str] = None
+
+
+class BlockchainService(BaseService):
+    async def contracts_available(
+        self, network: Optional[str] = None
+    ) -> AvailableContractsResponse:
+        """Coins/tokens this project may use.
+
+        Pass a ``network`` to scope to one chain, or omit for the full set. Each
+        row's ``decimals`` is what ``human_to_base`` / ``base_to_human`` need.
+        """
+        body = {"network": network} if network else {}
+        return from_dict(
+            AvailableContractsResponse, await self._post("/v1/blockchain/contracts/available", body)
+        )
+
+    async def wallet_balance(
+        self,
+        chain: str,
+        addresses: List[str],
+        contracts: Optional[List[str]] = None,
+    ) -> List[WalletBalanceRow]:
+        """Native + token balances for one or more addresses."""
+        body: dict[str, Any] = {"chain": chain, "addresses": addresses}
+        if contracts:
+            body["contracts"] = contracts
+        raw = await self._post("/v1/blockchain/wallet/balance", body)
+        return [from_dict(WalletBalanceRow, r) for r in (raw or [])]
+
+    async def transaction_status(self, chain: str, tx_hash: str) -> List[TxStatusRow]:
+        """Current on-chain state of a transaction by hash."""
+        raw = await self._post(
+            "/v1/blockchain/transaction/status", {"chain": chain, "hash": tx_hash}
+        )
+        return [from_dict(TxStatusRow, r) for r in (raw or [])]

cryptochief/services/currencies.py

@@ -0,0 +1,55 @@
+"""Fiat <-> crypto rate calculator.
+
+These quote rates only - they do NOT move funds (a swap is a payout with
+``auto_convert=True``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .._models import from_dict
+from .base import BaseService
+
+
+@dataclass(kw_only=True)
+class ConvertRequest:
+    from_: str  # source ticker (`from` is a Python keyword - serialized below)
+    to: str
+    amount: str
+    provider: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class ConvertResponse:
+    amount_crypto: float = 0.0
+    amount_fiat: float = 0.0
+    crypto: Optional[str] = None
+    crypto_to_usdt: float = 0.0
+    exchange: Optional[str] = None
+    fiat: Optional[str] = None
+    fiat_to_usd: float = 0.0
+    timestamp_crypto: int = 0
+    timestamp_fiat: int = 0
+
+
+def _body(req: ConvertRequest) -> dict:
+    body = {"from": req.from_, "to": req.to, "amount": req.amount}
+    if req.provider is not None:
+        body["provider"] = req.provider
+    return body
+
+
+class CurrenciesService(BaseService):
+    async def fiat_to_crypto(self, req: ConvertRequest) -> ConvertResponse:
+        """Quote how much crypto the given fiat amount is worth."""
+        return from_dict(
+            ConvertResponse, await self._post("/v1/currencies/convert/fiat-crypto", _body(req))
+        )
+
+    async def crypto_to_fiat(self, req: ConvertRequest) -> ConvertResponse:
+        """Quote how much fiat the given crypto amount is worth."""
+        return from_dict(
+            ConvertResponse, await self._post("/v1/currencies/convert/crypto-fiat", _body(req))
+        )

cryptochief/services/payins.py

@@ -0,0 +1,145 @@
+"""Incoming-payment (invoice) endpoints."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Optional
+
+from .._models import from_dict
+from ..assets import Asset, AssetsPolicy
+from ..pagination import HistoryMeta, HistoryQuery
+from ..poll import wait_for_terminal
+from .base import BaseService
+
+
+class PayInMode(str, Enum):
+    """``fiat`` fixes a stable fiat price; ``crypto`` fixes the crypto amount."""
+
+    FIAT = "fiat"
+    CRYPTO = "crypto"
+
+
+class PayInStatus(str, Enum):
+    WAITING_ASSET_SELECT = "waiting_asset_select"
+    PENDING = "pending"
+    PROCESSING = "processing"
+    PROCESS = "process"
+    PAID = "paid"
+    CANCEL = "cancel"
+    EXPIRED = "expired"
+
+
+_PAYIN_TERMINAL = frozenset({"paid", "cancel", "expired"})
+
+
+def is_payin_terminal(status: str) -> bool:
+    """Whether a pay-in status is final."""
+    return status in _PAYIN_TERMINAL
+
+
+@dataclass(kw_only=True)
+class CreatePayInRequest:
+    order_id: str
+    user_id: str
+    mode: str
+    to_address: Optional[str] = None
+    lifetime_sec: Optional[int] = None
+    url_callback: Optional[str] = None
+    url_success: Optional[str] = None
+    url_error: Optional[str] = None
+    additional_data: Optional[str] = None
+    accuracy_payment_percent: Optional[int] = None
+    # FIAT mode.
+    amount_fiat: Optional[str] = None
+    currency: Optional[str] = None
+    course_source: Optional[str] = None
+    assets: Optional[AssetsPolicy] = None
+    # CRYPTO mode.
+    amount_crypto: Optional[str] = None
+    asset: Optional[Asset] = None
+
+
+@dataclass(kw_only=True)
+class CoinOption:
+    coin: Optional[str] = None
+    network: Optional[str] = None
+    chain_family: Optional[str] = None
+    contract: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class PayIn:
+    uuid: str = ""
+    status: str = ""
+    type: Optional[str] = None
+    order_id: Optional[str] = None
+    user_id: Optional[str] = None
+    mode: Optional[str] = None
+    amount_crypto: Optional[str] = None
+    amount_fiat: Optional[str] = None
+    currency: Optional[str] = None
+    payment_coin: Optional[str] = None
+    payment_network: Optional[str] = None
+    to_address: Optional[str] = None
+    coins: Optional[List[CoinOption]] = None
+    payment_link: Optional[str] = None
+    url_callback: Optional[str] = None
+    url_success: Optional[str] = None
+    url_error: Optional[str] = None
+    additional_data: Optional[str] = None
+    can_cancel: Optional[bool] = None
+    expired_at: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class PayInHistoryResponse:
+    items: Optional[List[PayIn]] = None
+    meta: Optional[HistoryMeta] = None
+
+
+@dataclass(kw_only=True)
+class SelectAssetRequest:
+    uuid: str
+    coin: str
+    network: str
+
+
+class PayInsService(BaseService):
+    async def create(self, req: CreatePayInRequest) -> PayIn:
+        """Open a new pay-in order."""
+        return from_dict(PayIn, await self._post("/v1/payments/order/create", req))
+
+    async def select_asset(self, req: SelectAssetRequest) -> PayIn:
+        """Commit the customer's coin/network choice on a ``waiting_asset_select`` order."""
+        return from_dict(PayIn, await self._post("/v1/payments/asset/select", req))
+
+    async def reset_asset(self, uuid: str) -> PayIn:
+        """Revert a pending order to ``waiting_asset_select`` (H2H only)."""
+        return from_dict(PayIn, await self._post("/v1/payments/asset/reset", {"uuid": uuid}))
+
+    async def cancel(self, uuid: str) -> PayIn:
+        """Cancel an open order."""
+        return from_dict(PayIn, await self._post("/v1/payments/order/cancel", {"uuid": uuid}))
+
+    async def info(self, uuid: str) -> PayIn:
+        """Fetch the current state of one pay-in by uuid."""
+        return from_dict(PayIn, await self._post("/v1/payments/order/info", {"uuid": uuid}))
+
+    async def history(self, query: Optional[HistoryQuery] = None) -> PayInHistoryResponse:
+        """Paged list of pay-ins."""
+        return from_dict(
+            PayInHistoryResponse, await self._post("/v1/payments/history", query or HistoryQuery())
+        )
+
+    async def wait_for(self, uuid: str, *, interval: float = 5.0, timeout: float = 600.0) -> PayIn:
+        """Poll ``info`` until the pay-in reaches a terminal state (or timeout)."""
+
+        async def fetch() -> PayIn:
+            return await self.info(uuid)
+
+        return await wait_for_terminal(
+            fetch, lambda p: is_payin_terminal(p.status), interval=interval, timeout=timeout
+        )

cryptochief/services/payouts.py

@@ -0,0 +1,175 @@
+"""Single and mass payout endpoints (including auto-convert swaps)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from .._models import from_dict
+from ..assets import AssetsPolicy
+from ..pagination import HistoryMeta, HistoryQuery
+from ..poll import wait_for_terminal
+from .base import BaseService
+
+
+class PayoutStatus(str, Enum):
+    QUEUE = "queue"
+    PROCESS = "process"
+    PAID = "paid"
+    FAILED = "failed"
+    SYSTEM_FAIL = "system_fail"
+    EXPIRED = "expired"
+    CANCEL = "cancel"
+
+
+_PAYOUT_TERMINAL = frozenset({"paid", "failed", "system_fail", "expired", "cancel"})
+
+
+def is_payout_terminal(status: str) -> bool:
+    """Whether a payout status is final (no further transitions)."""
+    return status in _PAYOUT_TERMINAL
+
+
+@dataclass(kw_only=True)
+class EstimatePayoutRequest:
+    network: str
+    coin: str
+    amount: str
+    to_address: str
+    from_addresses: Optional[List[str]] = None
+    allow_multiple_sources: Optional[bool] = None
+    auto_convert: Optional[bool] = None
+    auto_convert_policy: Optional[AssetsPolicy] = None
+    max_fee_amount_fiat: Optional[str] = None
+    memo: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class ExecutePayoutRequest(EstimatePayoutRequest):
+    """``order_id`` is the idempotency key - resubmitting returns the same ``uuid``."""
+
+    order_id: str
+    user_id: str
+    url_callback: str
+
+
+@dataclass(kw_only=True)
+class PayoutFeeInfo:
+    fee_mode: Optional[str] = None
+    estimated_fiat: Optional[str] = None
+    estimated_coin: Optional[str] = None
+    estimated_asset: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class PayoutSource:
+    address: Optional[str] = None
+    amount: Optional[str] = None
+    coin: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class EstimatePayoutResponse:
+    network: Optional[str] = None
+    coin: Optional[str] = None
+    amount: Optional[str] = None
+    amount_to_receive: Optional[str] = None
+    to_address: Optional[str] = None
+    fee_info: Optional[PayoutFeeInfo] = None
+    sources: Optional[List[PayoutSource]] = None
+    service_operations: Optional[List[Dict[str, Any]]] = None
+    auto_convert_applied: Optional[bool] = None
+
+
+@dataclass(kw_only=True)
+class PayoutInfo:
+    uuid: str = ""
+    status: str = ""
+    order_id: Optional[str] = None
+    network: Optional[str] = None
+    coin: Optional[str] = None
+    amount: Optional[str] = None
+    to_address: Optional[str] = None
+    txid: Optional[str] = None
+    sources: Optional[List[PayoutSource]] = None
+    url_callback: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    error: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class BatchPayoutRequest:
+    """Batch body for ``/payout/batch/{estimate,execute}``. Up to 50 items per call."""
+
+    items: List[ExecutePayoutRequest]
+    url_callback: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class BatchItemResult:
+    index: int = 0
+    order_id: Optional[str] = None
+    status: Optional[str] = None
+    uuid: Optional[str] = None
+    error: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class BatchPayoutResponse:
+    total: int = 0
+    accepted: int = 0
+    rejected: int = 0
+    items: Optional[List[BatchItemResult]] = None
+    batch_uuid: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class PayoutHistoryResponse:
+    items: Optional[List[PayoutInfo]] = None
+    meta: Optional[HistoryMeta] = None
+
+
+class PayoutsService(BaseService):
+    async def estimate(self, req: EstimatePayoutRequest) -> EstimatePayoutResponse:
+        """Preview fees and selected source(s) without locking funds."""
+        return from_dict(EstimatePayoutResponse, await self._post("/v1/payout/estimate", req))
+
+    async def execute(self, req: ExecutePayoutRequest) -> PayoutInfo:
+        """Create and dispatch a payout. Funds lock immediately; idempotent on ``order_id``."""
+        return from_dict(PayoutInfo, await self._post("/v1/payout/execute", req))
+
+    async def info(self, uuid: str) -> PayoutInfo:
+        """Fetch the current state of one payout by uuid."""
+        return from_dict(PayoutInfo, await self._post("/v1/payout/info", {"uuid": uuid}))
+
+    async def history(self, query: Optional[HistoryQuery] = None) -> PayoutHistoryResponse:
+        """Paged list of payouts matching the filter."""
+        return from_dict(
+            PayoutHistoryResponse, await self._post("/v1/payout/history", query or HistoryQuery())
+        )
+
+    async def batch_estimate(self, req: BatchPayoutRequest) -> BatchPayoutResponse:
+        """Preview fees for up to 50 payouts in one call."""
+        return from_dict(BatchPayoutResponse, await self._post("/v1/payout/batch/estimate", req))
+
+    async def batch_execute(self, req: BatchPayoutRequest) -> BatchPayoutResponse:
+        """Create up to 50 payouts in one call.
+
+        Bad items return their code in ``items[].error`` without blocking the
+        rest; funds lock sequentially so an intra-batch double-spend cannot occur.
+        """
+        return from_dict(BatchPayoutResponse, await self._post("/v1/payout/batch/execute", req))
+
+    async def wait_for(
+        self, uuid: str, *, interval: float = 5.0, timeout: float = 600.0
+    ) -> PayoutInfo:
+        """Poll ``info`` until the payout reaches a terminal state (or timeout)."""
+
+        async def fetch() -> PayoutInfo:
+            return await self.info(uuid)
+
+        return await wait_for_terminal(
+            fetch, lambda p: is_payout_terminal(p.status), interval=interval, timeout=timeout
+        )

cryptochief/services/static_deposits.py

@@ -0,0 +1,77 @@
+"""Read endpoints for deposits on per-customer static wallets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Optional
+
+from .._models import from_dict
+from ..pagination import HistoryMeta
+from .base import BaseService
+
+
+class StaticDepositStatus(str, Enum):
+    IN_MEMPOOL = "in_mempool"
+    CONFIRM_CHECK = "confirm_check"
+    PAID = "paid"
+    DROPPED = "dropped"
+    REORGED = "reorged"
+
+
+@dataclass(kw_only=True)
+class StaticDeposit:
+    uuid: str = ""
+    status: str = ""
+    network: Optional[str] = None
+    chain_family: Optional[str] = None
+    coin: Optional[str] = None
+    contract: Optional[str] = None
+    decimals: Optional[int] = None
+    to_address: Optional[str] = None
+    from_address: Optional[str] = None
+    tx_hash: Optional[str] = None
+    block_number: Optional[int] = None
+    amount: Optional[str] = None
+    amount_fiat: Optional[str] = None
+    confirmations: Optional[int] = None
+    required_confirmations: Optional[int] = None
+    found_in_mempool: Optional[bool] = None
+    log_type: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    confirmed_at: Optional[str] = None
+    paid_at: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class StaticDepositHistoryQuery:
+    address: Optional[str] = None
+    status: Optional[str] = None
+    coin: Optional[str] = None
+    network: Optional[str] = None
+    date_from: Optional[str] = None
+    date_to: Optional[str] = None
+    page: Optional[int] = None
+    page_size: Optional[int] = None
+
+
+@dataclass(kw_only=True)
+class StaticDepositHistoryResponse:
+    items: Optional[List[StaticDeposit]] = None
+    meta: Optional[HistoryMeta] = None
+
+
+class StaticDepositsService(BaseService):
+    async def info(self, uuid: str) -> StaticDeposit:
+        """Fetch one deposit by uuid."""
+        return from_dict(StaticDeposit, await self._post("/v1/static-deposit/info", {"uuid": uuid}))
+
+    async def history(
+        self, query: Optional[StaticDepositHistoryQuery] = None
+    ) -> StaticDepositHistoryResponse:
+        """Paged list of static deposits."""
+        return from_dict(
+            StaticDepositHistoryResponse,
+            await self._post("/v1/static-deposit/history", query or StaticDepositHistoryQuery()),
+        )

cryptochief/services/sweeps.py

@@ -0,0 +1,85 @@
+"""Treasury sweeps (transit -> master)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, List, Optional
+
+from .._models import from_dict
+from ..pagination import HistoryMeta
+from .base import BaseService
+
+
+class SweepMode(str, Enum):
+    AUTO = "auto"
+    FORCE = "force"
+
+
+@dataclass(kw_only=True)
+class SweepHistoryQuery:
+    mode: Optional[str] = None
+    page: Optional[int] = None
+    page_size: Optional[int] = None
+
+
+@dataclass(kw_only=True)
+class Sweep:
+    task_id: str = ""
+    status: str = ""
+    sweep_tx_hash: Optional[str] = None
+    wallet_address: Optional[str] = None
+    chain: Optional[str] = None
+    chain_family: Optional[str] = None
+    asset_symbol: Optional[str] = None
+    asset_type: Optional[str] = None
+    amount_human: Optional[str] = None
+    gas_fee_human: Optional[str] = None
+    gas_fee_fiat: Optional[str] = None
+    service_fee_fiat: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class SweepHistoryResponse:
+    items: Optional[List[Sweep]] = None
+    meta: Optional[HistoryMeta] = None
+
+
+@dataclass(kw_only=True)
+class ForceSweepResponse:
+    status: str = ""
+
+
+class SweepsService(BaseService):
+    async def force(self, address: str, network: str) -> ForceSweepResponse:
+        """Trigger an immediate transit->master sweep for one address.
+
+        The status acknowledges acceptance; the resulting :class:`Sweep` record
+        appears via :meth:`wallet_history` once the on-chain tx is built.
+        """
+        return from_dict(
+            ForceSweepResponse,
+            await self._post("/v1/sweeps/force", {"address": address, "network_code": network}),
+        )
+
+    async def history(self, query: Optional[SweepHistoryQuery] = None) -> SweepHistoryResponse:
+        """Recent sweeps across the whole project."""
+        return from_dict(
+            SweepHistoryResponse, await self._post("/v1/sweeps/history", query or SweepHistoryQuery())
+        )
+
+    async def wallet_history(
+        self, address: str, query: Optional[SweepHistoryQuery] = None
+    ) -> SweepHistoryResponse:
+        """Recent sweeps scoped to one wallet."""
+        body: dict[str, Any] = {"address": address}
+        if query is not None:
+            if query.mode is not None:
+                body["mode"] = query.mode
+            if query.page is not None:
+                body["page"] = query.page
+            if query.page_size is not None:
+                body["page_size"] = query.page_size
+        return from_dict(SweepHistoryResponse, await self._post("/v1/sweeps/wallet/history", body))