cryptochief-crypto-processing-python 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

cryptochief/_version.py

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

cryptochief/errors.py

@@ -19,19 +19,27 @@ class CryptoChiefError(Exception):
 class APIError(CryptoChiefError):
     """A typed Crypto Chief error response.
 
-    The API returns either ``{"error": "SERVICE_ERROR", "msg": "<CODE>", ...}``
-    (then :attr:`code` is ``<CODE>``) or ``{"error": "<CODE>", ...}`` (then
-    :attr:`code` is that value). Either way :attr:`code` is the stable
-    identifier to branch on::
+    :attr:`code` is the machine-readable identifier to branch on, whichever
+    envelope shape the refusal arrived in: the gateway's own refusals carry the
+    code in ``error`` and an English sentence in ``msg``
+    (``{"error": "LABEL_TOO_LONG", "msg": "label is longer than 255 characters"}``),
+    while a relayed upstream refusal carries the generic ``SERVICE_ERROR``
+    marker in ``error`` and the code in ``msg``
+    (``{"error": "SERVICE_ERROR", "msg": "wallet_not_found"}``). Both resolve to
+    :attr:`code`::
 
         try:
             await client.payouts.execute(req)
         except APIError as e:
             if e.code == ErrorCode.INSUFFICIENT_FUNDS:
                 ...  # top up and retry
+
+    :attr:`message` is the human-readable half - the sentence when the gateway
+    sent one - and :attr:`raw` is the untouched response body.
     """
 
     code: str
+    message: str
     http_status: int
     raw: Optional[str]
 
@@ -46,6 +54,7 @@ class APIError(CryptoChiefError):
         # Normalize an ErrorCode member to its wire string ("NETWORK_ERROR"),
         # not its enum repr ("ErrorCode.NETWORK_ERROR").
         self.code = code.value if isinstance(code, Enum) else str(code)
+        self.message = message or ""
         self.http_status = http_status
         self.raw = raw
         super().__init__(self._format(http_status, self.code, message))
@@ -75,6 +84,11 @@ class ErrorCode(str, Enum):
     ORDER_NOT_LIVE = "ORDER_NOT_LIVE"
     ASSET_ALREADY_SELECTED = "ASSET_ALREADY_SELECTED"
     INVALID_PARAMS = "INVALID_PARAMS"
+    #: A wallet label over 255 characters.
+    LABEL_TOO_LONG = "LABEL_TOO_LONG"
+    #: The gateway's marker for a refusal relayed from an upstream service; the
+    #: machine code then travels in ``msg`` and is what :attr:`APIError.code`
+    #: reports, so this member is rarely what you compare against.
     SERVICE_ERROR = "SERVICE_ERROR"
     UNAUTHORIZED = "UNAUTHORIZED"
     URL_CALLBACK_REQUIRED = "URL_CALLBACK_REQUIRED"

cryptochief/services/wallets.py

@@ -7,6 +7,7 @@ from enum import Enum
 from typing import List, Optional
 
 from .._models import from_dict
+from ..errors import CryptoChiefError
 from .base import BaseService
 
 
@@ -22,6 +23,14 @@ class GenerateWalletRequest:
     chain_family: str
     master_wallet_address: Optional[str] = None  # transit/static wallets only
     callback_url: Optional[str] = None  # static wallets only - per-deposit webhook URL
+    #: A name for the wallet, for people reading a list of them. Applies to
+    #: every wallet type - it names the wallet, it is not a property of its
+    #: role - and is yours alone: nothing on chain and nothing in routing
+    #: depends on it. Up to 255 characters, longer answers ``LABEL_TOO_LONG``.
+    #: Leave it ``None`` to omit it; the endpoint rejects unknown fields, and an
+    #: empty string is a name rather than the absence of one.
+    #: :meth:`WalletsService.set_label` renames the wallet afterwards.
+    label: Optional[str] = None
 
 
 @dataclass(kw_only=True)
@@ -44,8 +53,21 @@ class Wallet:
     type: Optional[str] = None
     wallet_type: Optional[str] = None
     frozen: Optional[bool] = None
+    #: The master this wallet sweeps into, ``None`` when it has none - a master
+    #: wallet has no master of its own. The API always sends the key and sends
+    #: ``null`` rather than an empty string, so ``None`` here means "no master",
+    #: not "not reported". :meth:`WalletsService.rebind_master` changes it.
     master_wallet_address: Optional[str] = None
+    #: Where deposits to this address are announced, ``None`` when nowhere. Only
+    #: a static wallet has one: a master or transit always reads ``None``.
+    #: :meth:`WalletsService.set_callback_url` changes it.
     callback_url: Optional[str] = None
+    #: The wallet's name, ``None`` when it has none. Every wallet type can carry
+    #: one, and every response that describes a wallet reports it. The API
+    #: always sends the key and sends ``null`` rather than an empty string, so
+    #: ``None`` here means "unnamed" - a cleared label reads back as ``None``,
+    #: never as ``""``. :meth:`WalletsService.set_label` changes it.
+    label: Optional[str] = None
     #: Base64 RSA-OAEP/SHA-256 ciphertext - decrypt with ``decrypt_private_key``.
     private_key_encrypted: Optional[str] = None
     created_at: Optional[str] = None
@@ -75,6 +97,120 @@ class WalletsService(BaseService):
         """Toggle the frozen flag - the response's ``frozen`` field is the new state."""
         return from_dict(Wallet, await self._post("/v1/wallets/freeze", {"address": address}))
 
+    async def rebind_master(self, address: str, master_wallet_address: str) -> Wallet:
+        """Re-point a transit or static wallet at another master of the project.
+
+        The master link is decided when the wallet is created - at the master
+        named on that request, or, when none was named, at the project's *oldest*
+        master of that chain family, which on a project with more than one master
+        is rarely the one you meant. This is the way back.
+
+        It moves no money. It changes where the *next* sweep settles, including
+        sweeps already queued, because the destination is resolved when the sweep
+        runs; anything already swept sits on the previous master and has to be
+        sent from there as an ordinary payout.
+
+        Idempotent - a wallet already bound to that master answers 200 unchanged,
+        so re-running the same list is safe. A master wallet cannot be
+        re-pointed at all (``only transit and static wallets have a master``);
+        naming something that is not a master as the TARGET is a different
+        refusal (``not_a_master_wallet``). The target master must be the same
+        chain family (``chain_family_mismatch``) and not frozen
+        (``master_wallet_frozen``), since sweeping into a frozen master would
+        strand the funds there.
+
+        The gateway relays every upstream refusal as
+        ``{"error": "SERVICE_ERROR", "msg": "<token>"}``, and the SDK reports
+        that token as ``APIError.code`` - so branch on the code, not on the
+        message text. These tokens are per-endpoint and are not
+        :class:`~cryptochief.ErrorCode` members. Memo/tag-based families share one deposit
+        account across orders and are excluded
+        (``shared_transit_cannot_be_rebound``). Both addresses resolve against
+        the authenticated project, so one that is not yours answers
+        ``wallet_not_found`` / ``master_wallet_not_found`` rather than revealing
+        that it exists elsewhere.
+
+        Returns the wallet as it now stands.
+        """
+        return from_dict(
+            Wallet,
+            await self._post(
+                "/v1/wallets/rebind-master",
+                {"address": address, "master_wallet_address": master_wallet_address},
+            ),
+        )
+
+    async def set_callback_url(self, address: str, callback_url: str) -> Wallet:
+        """Set or clear a static wallet's deposit webhook after creation.
+
+        Deposits are announced to the callback URL the *address* carries, which
+        is fixed when the address is minted - so an address you did not create
+        through your own integration, or one minted before your endpoint moved,
+        keeps announcing its deposits somewhere else, or nowhere. This corrects
+        it, from the next deposit on: one already announced is not re-announced
+        to the new URL.
+
+        Pass ``""`` to clear it and stop announcing deposits for the address.
+        That is a real instruction rather than a missing field, so the SDK sends
+        the empty string instead of dropping it the way it drops unset optional
+        fields; the wallet then reads back ``callback_url=None``. ``None`` is
+        not that instruction and is refused here rather than silently leaving
+        the field off the body.
+
+        Static wallets only - a master or transit has no per-deposit callback
+        and answers 400. The address resolves against the authenticated project,
+        so one that is not yours answers ``wallet_not_found``.
+
+        Returns the wallet as it now stands.
+        """
+        if callback_url is None:
+            raise CryptoChiefError(
+                'cryptochief: set_callback_url: callback_url is required; pass "" to clear it'
+            )
+        return from_dict(
+            Wallet,
+            await self._post(
+                "/v1/wallets/callback-url",
+                {"address": address, "callback_url": callback_url},
+            ),
+        )
+
+    async def set_label(self, address: str, label: str) -> Wallet:
+        """Set or clear a wallet's label - the name it is read by.
+
+        A label is yours alone: nothing on chain and nothing in routing depends
+        on it. It is also the only thing telling one freshly minted address
+        apart from the next in a list, so a wallet created before the label was
+        supported, or minted somewhere other than your own integration, is worth
+        naming after the fact. This is how.
+
+        Every wallet type can be renamed - master, transit and static alike,
+        because a label names the wallet rather than describing its role. That
+        is unlike :meth:`set_callback_url`, which only a static wallet has.
+
+        Pass ``""`` to clear the name and leave the wallet unnamed. That is a
+        real instruction rather than a missing field, so the SDK sends the empty
+        string instead of dropping it the way it drops unset optional fields;
+        the wallet then reads back ``label=None``. ``None`` is not that
+        instruction and is refused here rather than silently leaving the field
+        off the body.
+
+        Up to 255 characters, longer answers ``LABEL_TOO_LONG``. The address
+        resolves against the authenticated project, so one that is not yours
+        answers ``wallet_not_found`` rather than revealing that it exists
+        elsewhere.
+
+        Returns the wallet as it now stands.
+        """
+        if label is None:
+            raise CryptoChiefError(
+                'cryptochief: set_label: label is required; pass "" to clear it'
+            )
+        return from_dict(
+            Wallet,
+            await self._post("/v1/wallets/label", {"address": address, "label": label}),
+        )
+
     def decrypt_private_key(self, encrypted: str) -> str:
         """Decrypt a generated wallet's ``private_key_encrypted`` field locally.
 

cryptochief/transport.py

@@ -8,11 +8,26 @@ import random
 from .errors import APIError, ErrorCode
 
 
+def _field(env: dict, key: str) -> str:
+    """Read ``key`` from an error envelope as a trimmed string (``""`` if absent)."""
+    value = env.get(key)
+    return value.strip() if isinstance(value, str) else ""
+
+
 def parse_api_error(status: int, body: str) -> APIError:
     """Parse a non-2xx response body into an :class:`APIError` with a stable code.
 
-    The code is ``msg or error or HTTP_<status>``, and the message prefers
-    ``msg`` when it differs from ``error``.
+    Refusals arrive in two envelope shapes. When the gateway itself refuses, the
+    machine code is in ``error`` and ``msg`` holds an English sentence
+    (``{"error": "LABEL_TOO_LONG", "msg": "label is longer than 255 characters"}``).
+    When it relays an upstream refusal, ``error`` is the generic
+    ``SERVICE_ERROR`` marker and the machine code is in ``msg``
+    (``{"error": "SERVICE_ERROR", "msg": "wallet_not_found"}``).
+
+    So the code is ``error`` unless that is ``SERVICE_ERROR``, in which case it
+    is ``msg``; an empty result falls back to ``error`` and then
+    ``HTTP_<status>``. The human-readable message prefers ``msg`` and falls back
+    to ``error``.
     """
     env: dict = {}
     try:
@@ -21,11 +36,16 @@ def parse_api_error(status: int, body: str) -> APIError:
             env = parsed
     except ValueError:
         pass  # non-JSON error body -> fall back to HTTP_<status>
-    code = env.get("msg") or env.get("error") or f"HTTP_{status}"
-    message = env.get("error") or ""
-    if env.get("msg") and env.get("msg") != env.get("error"):
-        message = env.get("msg")
-    return APIError(code, http_status=status, message=message, raw=body)
+
+    error = _field(env, "error")
+    msg = _field(env, "msg")
+    code = error if error and error != ErrorCode.SERVICE_ERROR else (msg or error)
+    return APIError(
+        code or f"HTTP_{status}",
+        http_status=status,
+        message=msg or error,
+        raw=body,
+    )
 
 
 def backoff_delay(attempt: int, base_ms: float, max_ms: float) -> float:

{cryptochief_crypto_processing_python-0.5.0.dist-info → cryptochief_crypto_processing_python-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cryptochief-crypto-processing-python
-Version: 0.5.0
+Version: 0.6.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
@@ -120,7 +120,7 @@ Both credentials come from the Dashboard -> Project.
 | Solana programs | `client.transactions` | `sign_anchor_call`, `sign_solana_call` |
 | 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` |
+| Wallet management + RSA decrypt | `client.wallets` | `generate`, `list`, `info`, `freeze`, `rebind_master`, `set_callback_url`, `set_label`, `decrypt_private_key` |
 | 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` |
@@ -302,8 +302,11 @@ the sender IPs in `WEBHOOK_SENDER_IPS` at your edge for defense in depth.
 ## Errors
 
 Everything the SDK raises derives from `CryptoChiefError`. API failures are
-`APIError` with a stable `.code` (and `.http_status`); branch on `ErrorCode`
-rather than parsing messages. 5xx and network errors are retried automatically;
+`APIError` with a stable `.code` (plus `.message`, `.http_status` and the
+untouched `.raw` body); branch on `ErrorCode` rather than parsing messages. Both
+envelope shapes the gateway sends - its own refusals, which carry the code in
+`error`, and refusals relayed from upstream as `SERVICE_ERROR` with the code in
+`msg` - resolve to `.code`. 5xx and network errors are retried automatically;
 4xx is raised immediately.
 
 ```python
@@ -371,6 +374,35 @@ priv = client.wallets.decrypt_private_key(wallet.private_key_encrypted)
   `completed_at` filled in. Earlier platform versions reported `completed` at
   broadcast, so a sweep could read as settled while its transaction was still
   unconfirmed.
+- **My deposits are settling on the wrong master wallet.**
+  `client.wallets.rebind_master(address, master_wallet_address)` re-points a
+  transit or static wallet at another master of the project - the link is
+  otherwise decided at creation, falling back to the project's *oldest* master
+  of that chain family when none was named. It moves no money: it changes where
+  the **next** sweep settles, including sweeps already queued, and anything
+  already swept sits on the previous master and has to be sent from there as an
+  ordinary payout. It is idempotent, so re-running the same list is safe.
+- **A static address is announcing deposits to the wrong URL.** Deposits go to
+  the callback the *address* carries, fixed when it was minted - so an address
+  you did not create through your own integration, or one minted before your
+  endpoint moved, keeps notifying somewhere else.
+  `client.wallets.set_callback_url(address, url)` corrects it, from the next
+  deposit on (one already announced is not re-announced). Pass `""` to clear it
+  and stop the announcements - the SDK sends the empty string rather than
+  dropping it the way it drops unset optional fields, and the wallet then reads
+  back `callback_url=None`. Static wallets only.
+- **How do I name a wallet?** Pass `label` on
+  `client.wallets.generate(GenerateWalletRequest(..., label="EU shop"))`. It
+  applies to every wallet type, is up to 255 characters, and is yours alone -
+  nothing on chain and nothing in routing depends on it.
+- **How do I rename a wallet I already have?**
+  `client.wallets.set_label(address, "EU shop")` - every wallet type, master
+  and transit included, unlike the deposit callback. Pass `""` to clear the
+  name: as with `set_callback_url`, the empty string is sent rather than
+  dropped, and the wallet then reads back `label=None`. The name comes back on
+  every response that describes a wallet - generation, `info`, `list`, and the
+  answers of `rebind_master` / `set_callback_url` / `set_label` itself - as
+  `wallet.label`, `None` when the wallet is unnamed.
 - **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

{cryptochief_crypto_processing_python-0.5.0.dist-info → cryptochief_crypto_processing_python-0.6.0.dist-info}/RECORD

@@ -1,18 +1,18 @@
 cryptochief/__init__.py,sha256=m0OZc9U4-u1PwE5kTgjjr9NXEecmhU34P2LyZw4_wTA,8780
 cryptochief/_models.py,sha256=I5jbRtC4Asnr0eZP1IUYcgQqXE-HMhXIq4zGabvMGO4,3195
-cryptochief/_version.py,sha256=aXKYEI71vj6vduzqBIScXXhDOhcLyP47gZgaBFSv7Y8,77
+cryptochief/_version.py,sha256=tzyKZxjKttfSIiX7h4cocHDuzHZ96CNTxW8tByv-Ens,77
 cryptochief/amount.py,sha256=UzIc1ZEJYYH8Zj5rUdnnLC01fS5ICKUSQ_rRxF0oeWI,3168
 cryptochief/assets.py,sha256=f4PaC60qoYloLlegWa61bXeG0qmk8j3Hcq4YjVrUVHw,889
 cryptochief/chains.py,sha256=FJ-QplCjf6qNc9frJYF7mJWMpB_DZ3SizI91kYTBNO0,3713
 cryptochief/client.py,sha256=bGgvXwQz6h4EwSYn408vvETofhqbKlck6DgH1ZyX2X8,7359
-cryptochief/errors.py,sha256=iFCiTpXbXwLa1nJTT57SKdtQEhUdbxAI-Lcnd8p3OA0,4052
+cryptochief/errors.py,sha256=02C6-KxBc8OocMHsF1NZ99MuoXLL2hgpHXDeM5vq85g,4819
 cryptochief/pagination.py,sha256=pJIzZNjN2mCbmYz66l1E-rUz8fsShZyNZecUncbcXtU,771
 cryptochief/poll.py,sha256=CfWb4OI1CN0gmS-ktt1SIN0yvNu9JQVhOlfi65WCsD8,1817
 cryptochief/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cryptochief/rsa.py,sha256=VvXJOJxE_GEdZ5cK4u0dRPkXWVs4GJnTnYHiFWpOhiM,2712
 cryptochief/sentinels.py,sha256=yVe6AK1ImLgXOHPjMVmp9CU8uUnOrQ1C_pF7K0x7oBc,1136
 cryptochief/sign.py,sha256=ghILWz9AEe_jy2JSgdOU2CpYlWGKrsZxJWjg-P9mgcs,3687
-cryptochief/transport.py,sha256=mGQ95JgVpRJposxmVXFhtI2Rkt-G2GRsBtQg2MlPEyw,1578
+cryptochief/transport.py,sha256=m8GKFLM5cyzVyzHbnG6N9fYWxeDvzeJmPtycDE8gMFo,2359
 cryptochief/webhook.py,sha256=-LwFzTImVt2y15Ij5mKri7qqY6NQKQxEk_4Lcb8an_8,8737
 cryptochief/contract/__init__.py,sha256=LF3fAvJOv0pnFeK7XOA69CwnM8GM_McqUiRvmZGj7f8,1398
 cryptochief/contract/base58.py,sha256=Rr-bcqBAHgr-q9_pV-KEwPrOjEGow3qiDUwZ_kicUH8,1172
@@ -30,13 +30,13 @@ cryptochief/services/payouts.py,sha256=QkqnxyXgTqDnh7epZQCgcvhxWnalpxNSZdR1QMl7v
 cryptochief/services/static_deposits.py,sha256=8uVM7c4rXb5HPj5n7q0K8bri0Kbxa3d442Uwo4iAMuM,2329
 cryptochief/services/sweeps.py,sha256=36wXPJg_gon8hsF-pgHzx5A5amzgN51iWGRSZfefrr4,10163
 cryptochief/services/transactions.py,sha256=EnVWTlbu04GJovI8PMBkxpO438dOny7E58GX_65I9MQ,16788
-cryptochief/services/wallets.py,sha256=g19wqwatVTRY-Zr_JFumQdbjY4Eit8hyEnZC2aerPpw,2956
+cryptochief/services/wallets.py,sha256=c-H37GczNS09YomoLnPk8jLgsrQG9iT6lOrt0JLkKcM,10202
 cryptochief/services/withdrawals.py,sha256=8UEXSr1VpvYSJl11vTBDOHq9qN96jP-i9p5USezKLHc,1540
 cryptochief/ton/__init__.py,sha256=z5VnZ5zXJkGaWUvOPdxC1YL6LJHz4TfhItVhBRVGKpA,392
 cryptochief/ton/address.py,sha256=Xo9cASWxTAK5-BLZ7ZwZcPEgobnh5fcwGj_gPzK2jz0,3731
 cryptochief/ton/messages.py,sha256=GCAn6TdyHewIwHb6V9HCjRx7BFHq9i1Cl243kDl6JNs,3341
 cryptochief/ton/rpc.py,sha256=fccQG2hecmLDIXyZs_6SzUIVzPb9huJnFFLp3HMrOuc,6109
-cryptochief_crypto_processing_python-0.5.0.dist-info/METADATA,sha256=M0wskTyjLNQLxra0-IjsU9kPJYs03R63ZTsKeevIq0I,17127
-cryptochief_crypto_processing_python-0.5.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-cryptochief_crypto_processing_python-0.5.0.dist-info/licenses/LICENSE,sha256=OkQRmg655nJmf2CYF2rYZNq-W961sWnsIPgYPJ5uuE4,1069
-cryptochief_crypto_processing_python-0.5.0.dist-info/RECORD,,
+cryptochief_crypto_processing_python-0.6.0.dist-info/METADATA,sha256=CGKoxySrIZmmGRwHps6-L0phhfP4sQo4IaGp0RMavF8,19473
+cryptochief_crypto_processing_python-0.6.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+cryptochief_crypto_processing_python-0.6.0.dist-info/licenses/LICENSE,sha256=OkQRmg655nJmf2CYF2rYZNq-W961sWnsIPgYPJ5uuE4,1069
+cryptochief_crypto_processing_python-0.6.0.dist-info/RECORD,,