cryptochief-crypto-processing-python 0.2.0__tar.gz → 0.5.0__tar.gz

{cryptochief_crypto_processing_python-0.2.0 → cryptochief_crypto_processing_python-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cryptochief-crypto-processing-python
-Version: 0.2.0
+Version: 0.5.0
 Summary: Official async Python SDK for the Crypto Chief crypto payment gateway and crypto processing API. Accept crypto payments, send single and mass crypto payouts, sign on-chain transactions and smart-contract calls, manage wallets, convert fiat to crypto, and verify webhooks across Ethereum, BNB Smart Chain, Polygon, Tron, TON, Solana, Bitcoin, XRP and 20+ blockchains. USDT and USDC stablecoin support with int-precise amounts and asyncio/httpx.
 Project-URL: Homepage, https://crypto-chief.com/processing/
 Project-URL: Documentation, https://docs-sdk.crypto-chief.com/processing/python
@@ -121,7 +121,7 @@ Both credentials come from the Dashboard -> Project.
 | TON contract calls (Jetton / NFT / text) | `client.transactions` | `jetton_transfer`, `nft_transfer`, `send_ton_comment`, `sign_ton_call` |
 | Accept incoming payments | `client.pay_ins` | `create`, `select_asset`, `reset_asset`, `cancel`, `info`, `history`, `wait_for` |
 | Wallet management + RSA decrypt | `client.wallets` | `generate`, `list`, `info`, `freeze`, `decrypt_private_key` |
-| Treasury sweeps | `client.sweeps` | `force`, `history`, `wallet_history` |
+| Treasury sweeps | `client.sweeps` | `force`, `history`, `wallet_history`, `settings`, `update_settings` |
 | Withdrawals (read-only) | `client.withdrawals` | `info`, `history` |
 | Static-deposit history | `client.static_deposits` | `info`, `history` |
 | On-chain queries | `client.blockchain` | `contracts_available`, `wallet_balance`, `transaction_status` |
@@ -200,6 +200,14 @@ decimal strings round-trip exactly. Discover an asset's decimals with
 
 ## Contract calls without hand-encoding
 
+> **This snippet shows the encoder, not a complete swap.** Uniswap's router
+> moves your input token with `transferFrom`, so it needs an ERC-20
+> `approve(address,uint256)` on that token first, confirmed before the swap is
+> signed — without it the swap reverts and burns the gas. And an `amountOutMin`
+> of `0` accepts whatever the pool returns, which on a public mempool hands the
+> trade to the first sandwich bot that sees it. The runnable version, with both,
+> is in `examples/`.
+
 ```python
 from cryptochief import EvmCallRequest, Erc20TransferRequest, Chain, human_to_base
 
@@ -335,6 +343,39 @@ priv = client.wallets.decrypt_private_key(wallet.private_key_encrypted)
 - **How do I do a crypto swap?** A swap is a payout with `auto_convert=True`.
 - **How do I call a smart contract?** `client.transactions.sign_evm_call` /
   `sign_anchor_call` / `jetton_transfer`, then `transactions.execute`.
+- **How do I control when a deposit wallet is swept?**
+  `client.sweeps.settings(...)` reads the policy in force for one wallet and
+  `client.sweeps.update_settings(...)` changes it - sweep on arrival
+  (`SweepPolicyMode.MOMENTUM`), sweep once the balance reaches an amount
+  (`SweepPolicyMode.THRESHOLD` plus `threshold_amount_usd`), or never on its own
+  (`SweepPolicyMode.OFF`, force still works). The read comes back in three
+  layers - what will happen, what this wallet overrides, and what it inherits
+  from the project - so a value of your own is distinguishable from an inherited
+  one:
+
+  ```python
+  s = await client.sweeps.update_settings(
+      deposit_address,
+      type_work=SweepPolicyMode.THRESHOLD,
+      threshold_amount_usd="250",
+  )
+  # s.effective is the resolved policy; s.effective.source names the layer it came from.
+  ```
+
+  Inheritance is per field: overriding the mode leaves the fee mode inherited.
+  To stop overriding a field, pass `CLEAR` - `None` already means "leave this
+  field alone", so it cannot also mean "reset it".
+- **How do I know a sweep actually settled?** Check `status`.
+  `SweepStatus.BROADCASTED` means the transaction is out and not yet confirmed;
+  `SweepStatus.COMPLETED` means confirmed, with `sweep_confirmations` and
+  `completed_at` filled in. Earlier platform versions reported `completed` at
+  broadcast, so a sweep could read as settled while its transaction was still
+  unconfirmed.
+- **How do I keep test payments off real chains?** Set `environment` on
+  `CreatePayInRequest` to `Environment.TESTNET` or `Environment.MAINNET`. It
+  constrains the asset the platform picks when you have not named a concrete
+  network - fiat mode and `ANY` - so an unconstrained pick cannot put a real
+  payment on a test chain. Omit it to use the project's default.
 
 ## Documentation
 

{cryptochief_crypto_processing_python-0.2.0 → cryptochief_crypto_processing_python-0.5.0}/README.md

@@ -82,7 +82,7 @@ Both credentials come from the Dashboard -> Project.
 | TON contract calls (Jetton / NFT / text) | `client.transactions` | `jetton_transfer`, `nft_transfer`, `send_ton_comment`, `sign_ton_call` |
 | Accept incoming payments | `client.pay_ins` | `create`, `select_asset`, `reset_asset`, `cancel`, `info`, `history`, `wait_for` |
 | Wallet management + RSA decrypt | `client.wallets` | `generate`, `list`, `info`, `freeze`, `decrypt_private_key` |
-| Treasury sweeps | `client.sweeps` | `force`, `history`, `wallet_history` |
+| Treasury sweeps | `client.sweeps` | `force`, `history`, `wallet_history`, `settings`, `update_settings` |
 | Withdrawals (read-only) | `client.withdrawals` | `info`, `history` |
 | Static-deposit history | `client.static_deposits` | `info`, `history` |
 | On-chain queries | `client.blockchain` | `contracts_available`, `wallet_balance`, `transaction_status` |
@@ -161,6 +161,14 @@ decimal strings round-trip exactly. Discover an asset's decimals with
 
 ## Contract calls without hand-encoding
 
+> **This snippet shows the encoder, not a complete swap.** Uniswap's router
+> moves your input token with `transferFrom`, so it needs an ERC-20
+> `approve(address,uint256)` on that token first, confirmed before the swap is
+> signed — without it the swap reverts and burns the gas. And an `amountOutMin`
+> of `0` accepts whatever the pool returns, which on a public mempool hands the
+> trade to the first sandwich bot that sees it. The runnable version, with both,
+> is in `examples/`.
+
 ```python
 from cryptochief import EvmCallRequest, Erc20TransferRequest, Chain, human_to_base
 
@@ -296,6 +304,39 @@ priv = client.wallets.decrypt_private_key(wallet.private_key_encrypted)
 - **How do I do a crypto swap?** A swap is a payout with `auto_convert=True`.
 - **How do I call a smart contract?** `client.transactions.sign_evm_call` /
   `sign_anchor_call` / `jetton_transfer`, then `transactions.execute`.
+- **How do I control when a deposit wallet is swept?**
+  `client.sweeps.settings(...)` reads the policy in force for one wallet and
+  `client.sweeps.update_settings(...)` changes it - sweep on arrival
+  (`SweepPolicyMode.MOMENTUM`), sweep once the balance reaches an amount
+  (`SweepPolicyMode.THRESHOLD` plus `threshold_amount_usd`), or never on its own
+  (`SweepPolicyMode.OFF`, force still works). The read comes back in three
+  layers - what will happen, what this wallet overrides, and what it inherits
+  from the project - so a value of your own is distinguishable from an inherited
+  one:
+
+  ```python
+  s = await client.sweeps.update_settings(
+      deposit_address,
+      type_work=SweepPolicyMode.THRESHOLD,
+      threshold_amount_usd="250",
+  )
+  # s.effective is the resolved policy; s.effective.source names the layer it came from.
+  ```
+
+  Inheritance is per field: overriding the mode leaves the fee mode inherited.
+  To stop overriding a field, pass `CLEAR` - `None` already means "leave this
+  field alone", so it cannot also mean "reset it".
+- **How do I know a sweep actually settled?** Check `status`.
+  `SweepStatus.BROADCASTED` means the transaction is out and not yet confirmed;
+  `SweepStatus.COMPLETED` means confirmed, with `sweep_confirmations` and
+  `completed_at` filled in. Earlier platform versions reported `completed` at
+  broadcast, so a sweep could read as settled while its transaction was still
+  unconfirmed.
+- **How do I keep test payments off real chains?** Set `environment` on
+  `CreatePayInRequest` to `Environment.TESTNET` or `Environment.MAINNET`. It
+  constrains the asset the platform picks when you have not named a concrete
+  network - fiat mode and `ANY` - so an unconstrained pick cannot put a real
+  payment on a test chain. Omit it to use the project's default.
 
 ## Documentation
 

{cryptochief_crypto_processing_python-0.2.0 → cryptochief_crypto_processing_python-0.5.0}/pyproject.toml

@@ -110,5 +110,5 @@ target-version = "py310"
 
 [tool.mypy]
 python_version = "3.10"
+mypy_path = "src"
 warn_unused_ignores = true
-ignore_missing_imports = true

{cryptochief_crypto_processing_python-0.2.0 → cryptochief_crypto_processing_python-0.5.0}/src/cryptochief/__init__.py

@@ -80,6 +80,7 @@ from .services.currencies import ConvertRequest, ConvertResponse, CurrenciesServ
 from .services.payins import (
     CoinOption,
     CreatePayInRequest,
+    Environment,
     PayIn,
     PayInHistoryResponse,
     PayInMode,
@@ -110,13 +111,20 @@ from .services.static_deposits import (
     StaticDepositsService,
     StaticDepositStatus,
 )
+from .sentinels import CLEAR, Clear
 from .services.sweeps import (
     ForceSweepResponse,
     Sweep,
+    SweepFeeMode,
     SweepHistoryQuery,
     SweepHistoryResponse,
     SweepMode,
+    SweepOverride,
+    SweepPolicy,
+    SweepPolicyMode,
+    SweepSettings,
     SweepsService,
+    SweepStatus,
 )
 from .services.transactions import (
     AnchorCallRequest,
@@ -162,6 +170,8 @@ from .webhook import (
     PayInWebhookEvent,
     PayoutWebhookEvent,
     StaticDepositWebhookEvent,
+    SweepWebhookEvent,
+    SWEEP_EVENT_CONFIRMED,
     TransactionWebhookEvent,
     WebhookSignatureError,
     coerce_webhook_event,
@@ -171,6 +181,10 @@ from .webhook import (
 
 __all__ = [
     "__version__",
+    # Sentinels
+    "CLEAR",
+    "Clear",
+    "Environment",
     # Client
     "CryptoChiefClient",
     "VERSION",
@@ -218,6 +232,8 @@ __all__ = [
     "TransactionWebhookEvent",
     "PayInWebhookEvent",
     "StaticDepositWebhookEvent",
+    "SweepWebhookEvent",
+    "SWEEP_EVENT_CONFIRMED",
     # Services
     "PayoutsService",
     "TransactionsService",
@@ -278,10 +294,16 @@ __all__ = [
     "WalletType",
     # Sweep types
     "Sweep",
+    "SweepFeeMode",
     "SweepHistoryQuery",
     "SweepHistoryResponse",
     "ForceSweepResponse",
     "SweepMode",
+    "SweepOverride",
+    "SweepPolicy",
+    "SweepPolicyMode",
+    "SweepSettings",
+    "SweepStatus",
     # Withdrawal types
     "Withdrawal",
     "WithdrawalHistoryResponse",

{cryptochief_crypto_processing_python-0.2.0 → cryptochief_crypto_processing_python-0.5.0}/src/cryptochief/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version."""
 
-__version__ = "0.2.0"
+__version__ = "0.5.0"

cryptochief_crypto_processing_python-0.5.0/src/cryptochief/sentinels.py

@@ -0,0 +1,38 @@
+"""Sentinels for values that ``None`` cannot express.
+
+Python has one "absent" value and some APIs need two. Where an argument
+distinguishes "not supplied" from "supplied as nothing", ``None`` takes the
+first meaning and a sentinel from this module takes the second.
+"""
+
+from __future__ import annotations
+
+
+class Clear:
+    """Stop overriding a field and go back to inheriting it.
+
+    Used with :meth:`cryptochief.SweepsService.update_settings`, where the API
+    expresses "inherit this again" by naming a field and sending no value for
+    it. ``None`` already means "leave this field alone", so it cannot also mean
+    "reset it".
+
+    Use the :data:`CLEAR` singleton rather than constructing this.
+    """
+
+    _instance: "Clear | None" = None
+
+    def __new__(cls) -> "Clear":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "CLEAR"
+
+    def __bool__(self) -> bool:
+        # Truthy: `if value:` on a CLEAR must not read as "nothing was passed".
+        return True
+
+
+#: The singleton :class:`Clear`.
+CLEAR = Clear()

{cryptochief_crypto_processing_python-0.2.0 → cryptochief_crypto_processing_python-0.5.0}/src/cryptochief/services/payins.py

@@ -38,12 +38,40 @@ def is_payin_terminal(status: str) -> bool:
     return status in _PAYIN_TERMINAL
 
 
+class Environment(str, Enum):
+    """The two environments an order can belong to.
+
+    A project may be allowed one or both; asking for testnet on a project that
+    does not permit it is refused with ``TESTNET_NOT_ALLOWED`` rather than
+    quietly served on mainnet, and a value that is neither is
+    ``ENVIRONMENT_INVALID`` rather than a silent fallback.
+    """
+
+    MAINNET = "mainnet"
+    TESTNET = "testnet"
+
+
 @dataclass(kw_only=True)
 class CreatePayInRequest:
     order_id: str
     user_id: str
     mode: str
     to_address: Optional[str] = None
+    #: Pin the transit deposit wallet of THIS order to the given master wallet of
+    #: the project - the address the funds are swept to. The order's
+    #: asset/network chain family must match the master wallet's; a foreign or
+    #: mismatched address is rejected with 400. Omit for the project-default
+    #: behaviour.
+    master_wallet_address: Optional[str] = None
+    #: Constrain the asset the platform PICKS for this order to the real chains
+    #: or the test ones - ``Environment.MAINNET`` or ``Environment.TESTNET``.
+    #: Omit to use the project's own default.
+    #:
+    #: It changes nothing when ``asset`` names a concrete network - that is the
+    #: caller's choice. It matters in fiat mode and when the network is ``ANY``,
+    #: where the platform selects the asset and an unconstrained pick could put
+    #: a real payment on a test network.
+    environment: Optional[str] = None
     lifetime_sec: Optional[int] = None
     url_callback: Optional[str] = None
     url_success: Optional[str] = None
@@ -105,6 +133,10 @@ class SelectAssetRequest:
     uuid: str
     coin: str
     network: str
+    #: Pin the order's transit deposit wallet to the given project master
+    #: wallet; see :class:`CreatePayInRequest`. A value here overrides one
+    #: supplied at order create.
+    master_wallet_address: Optional[str] = None
 
 
 class PayInsService(BaseService):

cryptochief_crypto_processing_python-0.5.0/src/cryptochief/services/sweeps.py

@@ -0,0 +1,282 @@
+"""Treasury sweeps (transit -> master)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, List, Optional, Union
+
+from .._models import from_dict
+from ..sentinels import Clear
+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
+
+
+class SweepStatus(str, Enum):
+    """A sweep is broadcast first and confirmed after.
+
+    ``BROADCASTED`` means the transaction is out and not yet confirmed;
+    ``COMPLETED`` means the chain confirmed it. The platform used to report
+    ``completed`` at broadcast, so a sweep could read as settled while its
+    transaction was still unconfirmed or had been dropped.
+
+    ``SKIPPED`` is a sweep the platform decided against - almost always a
+    balance below the wallet's threshold. A normal outcome, not a failure.
+    """
+
+    PENDING = "pending"
+    WAITING_GAS = "waiting_gas"
+    BROADCASTED = "broadcasted"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+class SweepPolicyMode(str, Enum):
+    """Auto-sweep modes.
+
+    ``OFF`` is never swept on its own (:meth:`SweepsService.force` still works),
+    ``MOMENTUM`` sweeps as soon as funds arrive, and ``THRESHOLD`` sweeps once
+    the balance reaches ``threshold_amount_usd``. A held balance is re-checked
+    periodically, so a wallet that crosses the threshold through price movement
+    alone is still swept.
+    """
+
+    OFF = "turned_off"
+    MOMENTUM = "momentum"
+    THRESHOLD = "threshold"
+
+
+class SweepFeeMode(str, Enum):
+    """Who pays the gas for a sweep.
+
+    ``CLIENT`` takes it from the swept wallet, ``SERVICE`` from the platform's
+    service wallet, and ``MIX`` funds the gas from the service wallet and
+    reclaims the cost from the sweep.
+    """
+
+    CLIENT = "client"
+    SERVICE = "service"
+    MIX = "mix"
+
+
+@dataclass(kw_only=True)
+class Sweep:
+    task_id: str = ""
+    status: str = ""
+    sweep_tx_hash: Optional[str] = None
+    gas_pump_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
+    #: What triggered this sweep: momentum, threshold or force.
+    type_work: Optional[str] = None
+
+    #: Confirmations seen on the sweep transaction, and when it reached the
+    #: network's confirmation target. Read them with ``status``:
+    #: ``completed_at`` is absent while the sweep is still in flight.
+    sweep_confirmations: Optional[int] = None
+    completed_at: Optional[str] = None
+
+    #: Fees. ``total_fee_usd`` is the whole cost of the sweep; the gas-pump half
+    #: is the funding transfer that pays for it on chains needing one. The
+    #: ``real_*`` figures are what the chain actually charged, filled in once the
+    #: transaction settles; the others are the estimate made up front.
+    total_fee_usd: Optional[str] = None
+    gas_pump_source: Optional[str] = None
+    gas_pump_fee_human: Optional[str] = None
+    gas_pump_fee_usd: Optional[str] = None
+    sweep_fee_human: Optional[str] = None
+    sweep_fee_usd: Optional[str] = None
+    real_gas_pump_fee_human: Optional[str] = None
+    real_gas_pump_fee_usd: Optional[str] = None
+    real_sweep_fee_human: Optional[str] = None
+    real_sweep_fee_usd: Optional[str] = None
+
+    created_at: Optional[str] = None
+
+    #: Deprecated: never populated. The API reports fees under the names above;
+    #: these were guesses at a shape it does not send.
+    gas_fee_human: Optional[str] = None
+    gas_fee_fiat: Optional[str] = None
+    service_fee_fiat: Optional[str] = None
+    #: Deprecated: never populated - sweeps carry ``created_at`` and
+    #: ``completed_at``.
+    updated_at: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class SweepPolicy:
+    """A resolved set of sweep rules."""
+
+    type_work: str = ""
+    #: Meaningful only when ``type_work`` is ``threshold``.
+    threshold_amount_usd: Optional[str] = None
+    fee_mode: str = ""
+    #: Which layer the mode came from: ``wallet_network``, ``wallet``,
+    #: ``project`` or ``default``. Present on the effective policy, where the
+    #: question arises.
+    source: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class SweepOverride:
+    """What one wallet decides for itself.
+
+    A field of ``None`` is not overridden - it is inherited, which no ordinary
+    value can express.
+    """
+
+    #: Empty covers the address on every network it exists on; set, it covers
+    #: that one network and takes precedence over the address-wide override.
+    network_code: Optional[str] = None
+    type_work: Optional[str] = None
+    threshold_amount_usd: Optional[str] = None
+    fee_mode: Optional[str] = None
+    #: Who wrote it: ``merchant`` or ``operator``.
+    source: Optional[str] = None
+    #: An operator pinned this policy. While it is set, a merchant write answers
+    #: ``SWEEP_SETTINGS_LOCKED`` and changes nothing.
+    locked: bool = False
+
+
+@dataclass(kw_only=True)
+class SweepSettings:
+    """Three layers, on purpose.
+
+    ``effective`` is what will actually happen, ``override`` is what this wallet
+    decides for itself (``None`` if it decides nothing), and ``project_default``
+    is what it falls back to. Only the three together answer "is this value mine
+    or inherited" - the difference between changing it here and changing it on
+    the project. Inheritance is per field: a wallet can override the mode and
+    keep inheriting the fee mode.
+    """
+
+    wallet_address: Optional[str] = None
+    network_code: Optional[str] = None
+    effective: Optional[SweepPolicy] = None
+    override: Optional[SweepOverride] = None
+    project_default: Optional[SweepPolicy] = 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))
+
+    async def settings(
+        self, address: Optional[str] = None, network_code: Optional[str] = None
+    ) -> SweepSettings:
+        """The auto-sweep policy in force for one wallet.
+
+        Returns what will happen, what the wallet overrides, and what it
+        inherits. Omitting ``address`` asks for the project's own default rather
+        than any wallet's policy.
+
+        Scoped to the caller's own wallets: an address that is not the project's
+        answers ``WALLET_NOT_FOUND``.
+        """
+        body: dict[str, Any] = {}
+        if address:
+            body["address"] = address
+        if network_code:
+            body["network_code"] = network_code
+        return from_dict(SweepSettings, await self._post("/v1/sweeps/settings", body))
+
+    async def update_settings(
+        self,
+        address: str,
+        *,
+        network_code: Optional[str] = None,
+        type_work: Union[str, Clear, None] = None,
+        threshold_amount_usd: Union[str, Clear, None] = None,
+        fee_mode: Union[str, Clear, None] = None,
+    ) -> SweepSettings:
+        """Write a wallet's auto-sweep policy.
+
+        Returns the settings as they stand afterwards, so the caller sees what
+        the write resolved to without asking again.
+
+        ``None`` leaves a field alone. :data:`~cryptochief.CLEAR` stops
+        overriding it and goes back to inheriting - the only way to drop one
+        field while keeping the others. The API expresses that by naming the
+        field with no value, which ``None`` cannot say in Python because it
+        already means "not supplied".
+
+        Refusals are named: ``TYPE_WORK_INVALID``, ``FEE_MODE_INVALID``,
+        ``THRESHOLD_INVALID``, ``THRESHOLD_MUST_BE_POSITIVE``,
+        ``THRESHOLD_REQUIRED_FOR_THRESHOLD_MODE``, and
+        ``SWEEP_SETTINGS_LOCKED`` when an operator has pinned the policy.
+        """
+        body: dict[str, Any] = {"address": address}
+        if network_code:
+            body["network_code"] = network_code
+
+        fields: List[str] = []
+        for name, value in (
+            ("type_work", type_work),
+            ("threshold_amount_usd", threshold_amount_usd),
+            ("fee_mode", fee_mode),
+        ):
+            if value is None:
+                continue
+            fields.append(name)
+            if not isinstance(value, Clear):
+                body[name] = value.value if isinstance(value, Enum) else value
+        if fields:
+            body["fields"] = fields
+
+        return from_dict(SweepSettings, await self._post("/v1/sweeps/settings/update", body))

{cryptochief_crypto_processing_python-0.2.0 → cryptochief_crypto_processing_python-0.5.0}/src/cryptochief/webhook.py

@@ -175,11 +175,75 @@ class StaticDepositWebhookEvent:
     paid_at: Optional[str] = None
 
 
+#: The only sweep event the platform emits. There is deliberately no
+#: ``sweep.broadcasted``: "we sent it" is not something you can act on, and an
+#: event that means "maybe" is one more thing to reconcile.
+SWEEP_EVENT_CONFIRMED = "sweep.confirmed"
+
+
+@dataclass(kw_only=True)
+class SweepWebhookEvent:
+    """Funds swept off a deposit wallet, confirmed on chain.
+
+    A ``static_deposit.paid`` tells you a customer paid you. This tells you the
+    money has finished moving into your own custody - until it fires, the
+    balance still sits on the deposit address. Reconciliation, treasury
+    reporting and "funds available to pay out" all key off this event, not off
+    the deposit.
+
+    Sweeps run on static deposit wallets *and* on the transit wallets issued per
+    pay-in order; both deliver here, to the callback URL configured for the
+    wallet the funds left.
+    """
+
+    event: str = ""
+    #: The sweeper task. One sweep settles once - use it as your idempotency key.
+    task_id: str = ""
+    #: Always ``"completed"``. A sweep reaches you in no other state.
+    status: str = ""
+
+    #: The wallet the funds left - the address your customer paid into.
+    wallet_address: str = ""
+    #: The master wallet they landed on.
+    to_address: Optional[str] = None
+
+    network: str = ""
+    chain_family: Optional[str] = None
+    asset_symbol: str = ""
+    asset_contract: Optional[str] = None
+    #: ``"native"`` or ``"token"``.
+    asset_type: Optional[str] = None
+    amount_raw: Optional[str] = None
+    amount_human: Optional[str] = None
+
+    sweep_tx_hash: str = ""
+    #: Set when the platform had to fund gas on the wallet before it could sweep.
+    gas_pump_tx_hash: Optional[str] = None
+
+    #: What makes this event true rather than hopeful, and never zero. It
+    #: travels with the event rather than being implied by it: "confirmed" is
+    #: not the same number on every chain, so if you run your own finality
+    #: policy you need the count to apply it.
+    sweep_confirmations: int = 0
+
+    #: When the chain was observed to hold the sweep. NOT the task's completion
+    #: timestamp, which is stamped on every terminal outcome - failures
+    #: included - and so says nothing about settlement.
+    confirmed_at: Optional[str] = None
+
+    #: What triggered it: ``"momentum"``, ``"threshold"`` or ``"force"``.
+    type_work: Optional[str] = None
+    #: What the sweep cost: network fee plus any gas or energy the platform
+    #: fronted to make it possible.
+    total_fee_usd: Optional[str] = None
+
+
 WebhookEvent = Union[
     PayoutWebhookEvent,
     TransactionWebhookEvent,
     PayInWebhookEvent,
     StaticDepositWebhookEvent,
+    SweepWebhookEvent,
     Dict[str, Any],
 ]
 
@@ -188,4 +252,5 @@ _EVENT_BY_PREFIX = {
     "transaction": TransactionWebhookEvent,
     "invoice": PayInWebhookEvent,
     "static_deposit": StaticDepositWebhookEvent,
+    "sweep": SweepWebhookEvent,
 }

cryptochief_crypto_processing_python-0.2.0/src/cryptochief/services/sweeps.py

@@ -1,85 +0,0 @@
-"""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))