pyXRocketAPI 0.2.0__tar.gz → 1.0.0__tar.gz

{pyxrocketapi-0.2.0 → pyxrocketapi-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyXRocketAPI
-Version: 0.2.0
+Version: 1.0.0
 Summary: Python client for the xRocket Pay API
 Author: Badiboy
 License-Expression: MIT
@@ -8,10 +8,9 @@ Project-URL: Homepage, https://github.com/Badiboy/pyXRocketAPI
 Project-URL: Documentation, https://docs.xrocket.exchange/api/pay/pay-api-overview
 Project-URL: Repository, https://github.com/Badiboy/pyXRocketAPI
 Keywords: xrocket,pay,crypto,payments,api
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.28
@@ -47,6 +46,40 @@ For integration testing, use the xRocket testnet instead of production:
 client = xRocketPayAPI(token="testnet-token", testnet=True)
 ```
 
+## Nested request models
+
+Known nested API objects are passed as model instances, not dictionaries. The
+same models deserialize API responses and implement `to_dict()` for request
+bodies.
+
+```python
+from pyXRocketAPI import InvoiceCallback, InvoiceCustomer, InvoiceUrl, xRocketPayAPI
+
+client = xRocketPayAPI(token="your-pay-api-token")
+invoice = client.create_invoice(
+    price_currency="USDT",
+    price_amount="10.00",
+    callback=InvoiceCallback(
+        callbackUrl="https://example.com/webhooks/invoice",
+        payload={"order_id": "123"},
+    ),
+    url=InvoiceUrl(
+        successUrl="https://example.com/success",
+        cancelUrl="https://example.com/cancel",
+    ),
+    customer=InvoiceCustomer(
+        id="customer-123",
+        email="customer@example.com",
+        telegramId="123456789",
+    ),
+    data={"internal_order_id": "123"},
+)
+```
+
+`payload` and `data` remain ordinary dictionaries because xRocket defines them
+as arbitrary JSON objects without a fixed schema. Use `MassPayout` instances
+for every item passed to `create_mass_payouts()`.
+
 ## Safety
 
 The token grants access to the application and must not be committed to source control. Financial POST operations are not retried automatically. Supply and retain the relevant client identifier (`client_invoice_id`, `client_payout_id`, `client_cheque_id`, or `client_withdrawal_id`) so that a timed-out operation can be reconciled safely.

{pyxrocketapi-0.2.0 → pyxrocketapi-1.0.0}/README.md

@@ -28,6 +28,40 @@ For integration testing, use the xRocket testnet instead of production:
 client = xRocketPayAPI(token="testnet-token", testnet=True)
 ```
 
+## Nested request models
+
+Known nested API objects are passed as model instances, not dictionaries. The
+same models deserialize API responses and implement `to_dict()` for request
+bodies.
+
+```python
+from pyXRocketAPI import InvoiceCallback, InvoiceCustomer, InvoiceUrl, xRocketPayAPI
+
+client = xRocketPayAPI(token="your-pay-api-token")
+invoice = client.create_invoice(
+    price_currency="USDT",
+    price_amount="10.00",
+    callback=InvoiceCallback(
+        callbackUrl="https://example.com/webhooks/invoice",
+        payload={"order_id": "123"},
+    ),
+    url=InvoiceUrl(
+        successUrl="https://example.com/success",
+        cancelUrl="https://example.com/cancel",
+    ),
+    customer=InvoiceCustomer(
+        id="customer-123",
+        email="customer@example.com",
+        telegramId="123456789",
+    ),
+    data={"internal_order_id": "123"},
+)
+```
+
+`payload` and `data` remain ordinary dictionaries because xRocket defines them
+as arbitrary JSON objects without a fixed schema. Use `MassPayout` instances
+for every item passed to `create_mass_payouts()`.
+
 ## Safety
 
 The token grants access to the application and must not be committed to source control. Financial POST operations are not retried automatically. Supply and retain the relevant client identifier (`client_invoice_id`, `client_payout_id`, `client_cheque_id`, or `client_withdrawal_id`) so that a timed-out operation can be reconciled safely.

{pyxrocketapi-0.2.0 → pyxrocketapi-1.0.0}/pyXRocketAPI/api.py

@@ -4,23 +4,11 @@ from typing import Any
 import requests
 
 from .exceptions import xRocketAPIException
-from .models import App, Balance, Cheque, ChequesList, Currency, Invoice, InvoicePaymentAddress, InvoicePaymentsList, InvoicesList, MassPayouts, xPage, Payout, PayoutsList, Rate, Withdrawal, WithdrawalLink, WithdrawalQuotas, WithdrawalsList, xRocketObject
+from .models import App, Balance, Cheque, ChequeCallback, ChequeUrl, ChequesList, Currency, Health, Invoice, InvoiceCallback, InvoiceCustomer, InvoicePaymentAddress, InvoicePaymentsList, InvoiceUrl, InvoicesList, MassPayout, MassPayouts, Payout, PayoutCallback, PayoutsList, Rate, Swap, SwapAsset, SwapEstimate, SwapRoute, SwapsList, Withdrawal, WithdrawalCallback, WithdrawalLink, WithdrawalQuotas, WithdrawalsList, xPage, xRocketObject
 
 PRODUCTION_API_URL = "https://pay.api.xrocket.exchange"
 TESTNET_API_URL = "https://pay.api.testnet.xrocket.exchange"
 
-
-def _without_none(**values: Any) -> dict[str, Any]:
-    """Keep valid falsey API values while omitting arguments not supplied."""
-    return {key: value for key, value in values.items() if value is not None}
-
-
-def _identifier(first_name: str, first_value: str | None, second_name: str, second_value: str | None) -> dict[str, str]:
-    if first_value is None and second_value is None:
-        raise ValueError(f"Specify {first_name} or {second_name}.")
-    return _without_none(**{first_name: first_value, second_name: second_value})
-
-
 class xRocketPayAPI:
     """Client for the current xRocket Pay API.
 
@@ -28,20 +16,64 @@ class xRocketPayAPI:
     ----------
     token:
         App-specific Pay API Bearer token. Public calls such as
-        ``health_check()`` and ``get_available_currencies()`` do not require
-        one.
+        ``health_check()`` and ``get_available_currencies()`` do not require one.
     testnet:
         Select the xRocket Pay testnet URL. A testnet token is required.
     timeout:
-        Timeout passed to every request, in seconds. ``None`` uses requests'
-        default behaviour.
+        Timeout passed to every request, in seconds.
+        ``None`` uses requests' default behaviour.
+        Default is 30 seconds.
+        A tuple of ``(connect, read)`` timeouts can be passed to override the default for each phase.
     """
 
+    @staticmethod
+    def __without_none(**values: Any) -> dict[str, Any]:
+        """Keep valid falsey API values while omitting arguments not supplied."""
+        return {key: value for key, value in values.items() if value is not None}
+
+    @staticmethod
+    def __identifier(first_name: str, first_value: str | None,
+                     second_name: str, second_value: str | None) -> dict[str, str]:
+        """Return identifier query parameters after validating their presence."""
+        if first_value is None and second_value is None:
+            raise ValueError(f"Specify {first_name} or {second_name}.")
+        return xRocketPayAPI.__without_none(**{first_name: first_value, second_name: second_value})
+
+    @staticmethod
+    def __request_model(value: Any, model_type: type, parameter_name: str) -> dict[str, Any] | None:
+        """Serialize one known nested request model or reject a plain mapping."""
+        if value is None:
+            return None
+        if not isinstance(value, model_type):
+            raise TypeError("{} must be an instance of {}.".format(parameter_name, model_type.__name__))
+        return value.to_dict()
+
+    @staticmethod
+    def __number_as_string(value: str | int | float | None, parameter_name: str) -> str | None:
+        """Encode one numeric API field whose wire type is string."""
+        if value is None:
+            return None
+        if isinstance(value, bool):
+            raise TypeError("{} must be a string or number, not bool.".format(parameter_name))
+        return str(value)
+
+    @staticmethod
+    def __swap_amount_mode(
+        amount: str | int | float | None, receive_amount: str | int | float | None
+    ) -> dict[str, str]:
+        """Validate and serialize one exact-in or exact-out swap amount."""
+        if (amount is None) == (receive_amount is None):
+            raise ValueError("Specify exactly one of amount or receive_amount.")
+        return xRocketPayAPI.__without_none(
+            amount=xRocketPayAPI.__number_as_string(amount, "amount"),
+            receiveAmount=xRocketPayAPI.__number_as_string(receive_amount, "receive_amount"),
+        )
+
     def __init__(
         self,
         token: str | None = None,
         testnet: bool = False,
-        timeout: float | tuple[float, float] | None = 10,
+        timeout: float | tuple[float, float] | None = 30,
     ) -> None:
         self.token = token
         self.timeout = timeout
@@ -113,14 +145,14 @@ class xRocketPayAPI:
         except ValueError as error:
             raise xRocketAPIException("xRocket Pay returned invalid JSON.", status=response.status_code) from error
 
-    def health_check(self) -> xRocketObject:
+    def health_check(self) -> Health:
         """Run the public health check.
 
         API: https://docs.xrocket.exchange/api/pay/reference/http/health-controller-health
 
-        :return: ``xRocketObject``.
+        :return: ``Health``.
         """
-        return xRocketObject.de_json(self._request("GET", "/health", auth_required=False), process_mode=2)
+        return Health.de_json(self._request("GET", "/health", auth_required=False))
 
     def get_app_info(self) -> App:
         """Get information about your application.
@@ -150,7 +182,7 @@ class xRocketPayAPI:
         :return: ``list[Currency]``.
         """
         data = self._request(
-            "GET", "/api/v1/currencies", params=_without_none(kind=kind), auth_required=False
+            "GET", "/api/v1/currencies", params=self.__without_none(kind=kind), auth_required=False
         )
         return [Currency.de_json(item) for item in data]
 
@@ -170,21 +202,124 @@ class xRocketPayAPI:
         )
         return [Rate.de_json(item) for item in data]
 
+    def create_swap(
+        self, from_asset: str, to_asset: str, client_order_id: str,
+        amount: str | int | float | None = None, receive_amount: str | int | float | None = None,
+    ) -> Swap:
+        """Create swap.
+
+        API: https://docs.xrocket.exchange/api/pay/reference/http/swap-controller-create-swap
+
+        :param from_asset: Asset to swap from.
+        :param to_asset: Asset to swap to.
+        :param client_order_id: Merchant-provided idempotency key. Re-using a
+            value returns a conflict.
+        :param amount: Exact-in amount: how much of ``from_asset`` to spend.
+            Provide exactly one of ``amount`` or ``receive_amount``. A numeric
+            value is encoded as an API string.
+        :param receive_amount: Exact-out amount: how much of ``to_asset`` to
+            receive. Provide exactly one of ``amount`` or ``receive_amount``.
+            A numeric value is encoded as an API string.
+        :return: ``Swap``.
+        """
+        body = {"fromAsset": from_asset, "toAsset": to_asset, "clientOrderId": client_order_id}
+        body.update(self.__swap_amount_mode(amount, receive_amount))
+        return Swap.de_json(self._request("POST", "/api/v1/swap", body=body))
+
+    def estimate_swap(
+        self, from_asset: str, to_asset: str,
+        amount: str | int | float | None = None, receive_amount: str | int | float | None = None,
+    ) -> SwapEstimate:
+        """Estimate swap amounts and rate without creating it.
+
+        API: https://docs.xrocket.exchange/api/pay/reference/http/swap-controller-estimate
+
+        :param from_asset: Asset to swap from.
+        :param to_asset: Asset to swap to.
+        :param amount: Exact-in amount: how much of ``from_asset`` to spend.
+            Provide exactly one of ``amount`` or ``receive_amount``. A numeric
+            value is encoded as an API string.
+        :param receive_amount: Exact-out amount: how much of ``to_asset`` to
+            receive. Provide exactly one of ``amount`` or ``receive_amount``.
+            A numeric value is encoded as an API string.
+        :return: ``SwapEstimate``.
+        """
+        body = {"fromAsset": from_asset, "toAsset": to_asset}
+        body.update(self.__swap_amount_mode(amount, receive_amount))
+        return SwapEstimate.de_json(self._request("POST", "/api/v1/swap/estimate", body=body))
+
+    def get_swaps_list(self, cursor: str | None = None, limit: int | None = None) -> SwapsList:
+        """Get application swaps.
+
+        API: https://docs.xrocket.exchange/api/pay/reference/http/swap-controller-get-swaps
+
+        :param cursor: Cursor for pagination.
+        :param limit: No description is provided.
+        :return: ``SwapsList``.
+        """
+        return SwapsList.de_json(self._request(
+            "GET", "/api/v1/swaps", params=self.__without_none(cursor=cursor, limit=limit)
+        ))
+
+    def get_swap_info(self, swap_id: str) -> Swap:
+        """Get application swap info by id.
+
+        API: https://docs.xrocket.exchange/api/pay/reference/http/swap-controller-get-swap
+
+        :param swap_id: Swap id (track id).
+        :return: ``Swap``.
+        """
+        return Swap.de_json(self._request("GET", "/api/v1/swap/{}".format(swap_id)))
+
+    def get_swap_input_assets(self, asset_out: str | None = None) -> list[SwapAsset]:
+        """Get available input assets, optionally filtered by a target asset.
+
+        API: https://docs.xrocket.exchange/api/pay/reference/http/swap-controller-get-assets-in
+
+        :param asset_out: Target asset used to filter the result.
+        :return: ``list[SwapAsset]``.
+        """
+        data = self._request("GET", "/api/v1/swap/assets-in", params=self.__without_none(assetOut=asset_out))
+        return [SwapAsset.de_json(item) for item in data.get("items", [])]
+
+    def get_swap_output_assets(self, asset_in: str | None = None) -> list[SwapAsset]:
+        """Get available output assets, optionally filtered by a source asset.
+
+        API: https://docs.xrocket.exchange/api/pay/reference/http/swap-controller-get-assets-out
+
+        :param asset_in: Source asset used to filter the result.
+        :return: ``list[SwapAsset]``.
+        """
+        data = self._request("GET", "/api/v1/swap/assets-out", params=self.__without_none(assetIn=asset_in))
+        return [SwapAsset.de_json(item) for item in data.get("items", [])]
+
+    def get_swap_route_params(self, asset_in: str, asset_out: str) -> SwapRoute:
+        """Get swap route params (min/max amounts) for an asset pair.
+
+        API: https://docs.xrocket.exchange/api/pay/reference/http/swap-controller-get-params
+
+        :param asset_in: Source asset.
+        :param asset_out: Target asset.
+        :return: ``SwapRoute``.
+        """
+        return SwapRoute.de_json(self._request(
+            "GET", "/api/v1/swap/params", params={"assetIn": asset_in, "assetOut": asset_out}
+        ))
+
     def create_invoice(
         self,
         price_currency: str,
-        price_amount: str | None = None,
-        min_payment: str | None = None,
+        price_amount: str | int | float | None = None,
+        min_payment: str | int | float | None = None,
         num_payments: int | None = None,
         payout_currency: str | None = None,
         pay_currencies: Iterable[str] | None = None,
         client_invoice_id: str | None = None,
         description: str | None = None,
         expires_in: int | None = None,
-        callback: Mapping[str, Any] | None = None,
-        url: Mapping[str, Any] | None = None,
-        customer: Mapping[str, Any] | None = None,
-        is_fee_paid_by_user: bool | None = None,
+        callback: InvoiceCallback | None = None,
+        url: InvoiceUrl | None = None,
+        customer: InvoiceCustomer | None = None,
         data: Mapping[str, Any] | None = None,
         platform_id: str | None = None,
     ) -> Invoice:
@@ -193,27 +328,31 @@ class xRocketPayAPI:
         API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-create-invoice
 
         :param price_currency: Invoice price currency (crypto or fiat).
-        :param price_amount: Invoice price amount.
-        :param min_payment: Minimum payment amount (for open-amount invoices).
+        :param price_amount: Invoice price amount. A numeric value is encoded as an API string.
+        :param min_payment: Minimum payment amount (for open-amount invoices). A numeric value is encoded as an API string.
         :param num_payments: Num payments for invoice.
         :param payout_currency: Invoice payout crypto currency.
         :param pay_currencies: Crypto currencies which can be used to pay the invoice.
         :param client_invoice_id: Client Invoice ID as assigned by the client.
         :param description: Description for invoice.
         :param expires_in: Payment expires in milliseconds.
-        :param callback: Callback data.
-        :param url: User redirect urls.
-        :param customer: Customer info.
-        :param is_fee_paid_by_user: If true, the user pays a commission.
+        :param callback: Callback data as an ``InvoiceCallback`` instance.
+        :param url: User redirect urls as an ``InvoiceUrl`` instance.
+        :param customer: Customer info as an ``InvoiceCustomer`` instance.
         :param data: Custom user data passed through and returned in callbacks/webhooks (max size 4KB).
         :param platform_id: Platform identifier.
         :return: ``Invoice``.
         """
-        body = _without_none(
-            priceCurrency=price_currency, priceAmount=price_amount, minPayment=min_payment, numPayments=num_payments,
+        body = self.__without_none(
+            priceCurrency=price_currency,
+            priceAmount=self.__number_as_string(price_amount, "price_amount"),
+            minPayment=self.__number_as_string(min_payment, "min_payment"), numPayments=num_payments,
             payoutCurrency=payout_currency, payCurrencies=list(pay_currencies) if pay_currencies is not None else None,
-            clientInvoiceId=client_invoice_id, description=description, expiresIn=expires_in, callback=callback, url=url,
-            customer=customer, isFeePaidByUser=is_fee_paid_by_user, data=data, platformId=platform_id,
+            clientInvoiceId=client_invoice_id, description=description, expiresIn=expires_in,
+            callback=self.__request_model(callback, InvoiceCallback, "callback"),
+            url=self.__request_model(url, InvoiceUrl, "url"),
+            customer=self.__request_model(customer, InvoiceCustomer, "customer"),
+            data=data, platformId=platform_id,
         )
         return Invoice.de_json(self._request("POST", "/api/v1/invoices", body=body))
 
@@ -231,7 +370,7 @@ class xRocketPayAPI:
         :param limit: No description is provided.
         :return: ``InvoicesList``.
         """
-        params = _without_none(asset=asset, fiat=fiat, ids=list(ids) if ids is not None else None, status=status, cursor=cursor, limit=limit)
+        params = self.__without_none(asset=asset, fiat=fiat, ids=list(ids) if ids is not None else None, status=status, cursor=cursor, limit=limit)
         return InvoicesList.de_json(self._request("GET", "/api/v1/invoices", params=params))
 
     def get_invoice_info(self, invoice_id: str | None = None, client_invoice_id: str | None = None) -> Invoice:
@@ -244,7 +383,7 @@ class xRocketPayAPI:
         :param client_invoice_id: Client Invoice ID assigned by the client. Either invoiceId or clientInvoiceId is required.
         :return: ``Invoice``.
         """
-        return Invoice.de_json(self._request("GET", "/api/v1/invoice", params=_identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id)))
+        return Invoice.de_json(self._request("GET", "/api/v1/invoice", params=self.__identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id)))
 
     def delete_invoice(self, invoice_id: str | None = None, client_invoice_id: str | None = None) -> None:
         """Delete invoice.
@@ -256,7 +395,7 @@ class xRocketPayAPI:
         :param client_invoice_id: Client Invoice ID assigned by the client. Either invoiceId or clientInvoiceId is required.
         :return: ``None``.
         """
-        self._request("DELETE", "/api/v1/invoice", params=_identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id))
+        self._request("DELETE", "/api/v1/invoice", params=self.__identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id))
 
     def get_invoice_payments(self, invoice_id: str | None = None, client_invoice_id: str | None = None,
                          cursor: str | None = None, limit: int | None = None) -> InvoicePaymentsList:
@@ -271,8 +410,8 @@ class xRocketPayAPI:
         :param limit: No description is provided.
         :return: ``InvoicePaymentsList``.
         """
-        params = _identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id)
-        params.update(_without_none(cursor=cursor, limit=limit))
+        params = self.__identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id)
+        params.update(self.__without_none(cursor=cursor, limit=limit))
         return InvoicePaymentsList.de_json(self._request("GET", "/api/v1/invoice/payments", params=params))
 
     def create_invoice_payment_address(self, pay_network: str, invoice_id: str | None = None,
@@ -288,11 +427,11 @@ class xRocketPayAPI:
         """
         return InvoicePaymentAddress.de_json(self._request(
             "POST", "/api/v1/invoices/payments/address",
-            params=_identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id), body={"payNetwork": pay_network},
+            params=self.__identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id), body={"payNetwork": pay_network},
         ))
 
-    def create_cheque(self, asset: str, amount: str, client_cheque_id: str | None = None, password: str | None = None,
-                      description: str | None = None, callback: Mapping[str, Any] | None = None, url: Mapping[str, Any] | None = None,
+    def create_cheque(self, asset: str, amount: str | int | float, client_cheque_id: str | None = None, password: str | None = None,
+                      description: str | None = None, callback: ChequeCallback | None = None, url: ChequeUrl | None = None,
                       target_type: str | None = None, target: str | None = None) -> Cheque:
         """Create cheque.
 
@@ -300,19 +439,20 @@ class xRocketPayAPI:
         Issue a personal cheque to perform an accept-type payout. The amount is reserved from the application balance and can be redeemed by the recipient or cancelled before redemption. When targetType and target are set, only the addressed user is allowed to redeem the cheque.
 
         :param asset: Currency of transfer.
-        :param amount: Cheque amount.
+        :param amount: Cheque amount. A numeric value is encoded as an API string.
         :param client_cheque_id: Unique cheque ID in your system to prevent double spends.
         :param password: Cheque password, the recipient has to enter it to redeem the cheque.
         :param description: Description for cheque.
-        :param callback: Webhook settings for cheque activation updates.
-        :param url: User redirect urls after cheque activation.
+        :param callback: Webhook settings for cheque activation updates as a ``ChequeCallback`` instance.
+        :param url: User redirect urls after cheque activation as a ``ChequeUrl`` instance.
         :param target_type: Target type for cheque, has to be passed together with target.
         :param target: Target for cheque, has to be passed together with targetType.
         :return: ``Cheque``.
         """
-        return Cheque.de_json(self._request("POST", "/api/v1/cheques", body=_without_none(
-            asset=asset, amount=str(amount), clientChequeId=client_cheque_id, password=password, description=description,
-            callback=callback, url=url, targetType=target_type, target=target,
+        return Cheque.de_json(self._request("POST", "/api/v1/cheques", body=self.__without_none(
+            asset=asset, amount=self.__number_as_string(amount, "amount"), clientChequeId=client_cheque_id, password=password, description=description,
+            callback=self.__request_model(callback, ChequeCallback, "callback"),
+            url=self.__request_model(url, ChequeUrl, "url"), targetType=target_type, target=target,
         )))
 
     def get_cheques_list(self, from_date: str | None = None, to_date: str | None = None, target_type: str | None = None,
@@ -331,7 +471,7 @@ class xRocketPayAPI:
         :param limit: No description is provided.
         :return: ``ChequesList``.
         """
-        return ChequesList.de_json(self._request("GET", "/api/v1/cheques", params=_without_none(
+        return ChequesList.de_json(self._request("GET", "/api/v1/cheques", params=self.__without_none(
             fromDate=from_date, toDate=to_date, targetType=target_type, target=target, state=state, cursor=cursor, limit=limit,
         )))
 
@@ -345,7 +485,7 @@ class xRocketPayAPI:
         :param client_cheque_id: Unique cheque id in your system.
         :return: ``Cheque``.
         """
-        return Cheque.de_json(self._request("GET", "/api/v1/cheque", params=_identifier("chequeId", cheque_id, "clientChequeId", client_cheque_id)))
+        return Cheque.de_json(self._request("GET", "/api/v1/cheque", params=self.__identifier("chequeId", cheque_id, "clientChequeId", client_cheque_id)))
 
     def update_cheque(self, description: str, cheque_id: str | None = None, client_cheque_id: str | None = None) -> Cheque:
         """Update cheque.
@@ -358,7 +498,7 @@ class xRocketPayAPI:
         :param client_cheque_id: Unique cheque id in your system.
         :return: ``Cheque``.
         """
-        return Cheque.de_json(self._request("PUT", "/api/v1/cheques", params=_identifier("chequeId", cheque_id, "clientChequeId", client_cheque_id), body={"description": description}))
+        return Cheque.de_json(self._request("PUT", "/api/v1/cheques", params=self.__identifier("chequeId", cheque_id, "clientChequeId", client_cheque_id), body={"description": description}))
 
     def delete_cheque(self, cheque_id: str | None = None, client_cheque_id: str | None = None) -> None:
         """Delete cheque.
@@ -370,10 +510,10 @@ class xRocketPayAPI:
         :param client_cheque_id: Unique cheque id in your system.
         :return: ``None``.
         """
-        self._request("DELETE", "/api/v1/cheques", params=_identifier("chequeId", cheque_id, "clientChequeId", client_cheque_id))
+        self._request("DELETE", "/api/v1/cheques", params=self.__identifier("chequeId", cheque_id, "clientChequeId", client_cheque_id))
 
-    def payout_funds_to_user(self, target: str, target_type: str, asset: str, amount: str, client_payout_id: str | None = None,
-                      description: str | None = None, callback: Mapping[str, Any] | None = None) -> Payout:
+    def create_payout(self, target: str, target_type: str, asset: str, amount: str | int | float, client_payout_id: str | None = None,
+                      description: str | None = None, callback: PayoutCallback | None = None) -> Payout:
         """Payout funds to user.
 
         API: https://docs.xrocket.exchange/api/pay/reference/http/payout-controller-payout
@@ -381,15 +521,15 @@ class xRocketPayAPI:
         :param target: Target.
         :param target_type: Target type.
         :param asset: Asset of transfer.
-        :param amount: Payout amount.
+        :param amount: Payout amount. A numeric value is encoded as an API string.
         :param client_payout_id: Unique payout ID in your system to prevent double spends.
         :param description: Payout description.
-        :param callback: Webhook settings for payout status updates.
+        :param callback: Webhook settings for payout status updates as a ``PayoutCallback`` instance.
         :return: ``Payout``.
         """
-        return Payout.de_json(self._request("POST", "/api/v1/payouts", body=_without_none(
-            target=target, targetType=target_type, asset=asset, amount=str(amount), clientPayoutId=client_payout_id,
-            description=description, callback=callback,
+        return Payout.de_json(self._request("POST", "/api/v1/payouts", body=self.__without_none(
+            target=target, targetType=target_type, asset=asset, amount=self.__number_as_string(amount, "amount"), clientPayoutId=client_payout_id,
+            description=description, callback=self.__request_model(callback, PayoutCallback, "callback"),
         )))
 
     def get_payouts_list(self, from_date: str | None = None, to_date: str | None = None, cursor: str | None = None,
@@ -404,7 +544,7 @@ class xRocketPayAPI:
         :param limit: No description is provided.
         :return: ``PayoutsList``.
         """
-        return PayoutsList.de_json(self._request("GET", "/api/v1/payouts", params=_without_none(fromDate=from_date, toDate=to_date, cursor=cursor, limit=limit)))
+        return PayoutsList.de_json(self._request("GET", "/api/v1/payouts", params=self.__without_none(fromDate=from_date, toDate=to_date, cursor=cursor, limit=limit)))
 
     def get_payout_info(self, payout_id: str | None = None, client_payout_id: str | None = None) -> Payout:
         """Get payout info.
@@ -415,21 +555,26 @@ class xRocketPayAPI:
         :param client_payout_id: Unique payout ID in your system to prevent double spends.
         :return: ``Payout``.
         """
-        return Payout.de_json(self._request("GET", "/api/v1/payout", params=_identifier("payoutId", payout_id, "clientPayoutId", client_payout_id)))
+        return Payout.de_json(self._request("GET", "/api/v1/payout", params=self.__identifier("payoutId", payout_id, "clientPayoutId", client_payout_id)))
 
-    def create_mass_payouts(self, asset: str, payouts: Iterable[Mapping[str, Any]]) -> MassPayouts:
+    def create_mass_payouts(self, asset: str, payouts: Iterable[MassPayout]) -> MassPayouts:
         """Create mass payouts (Telegram users only).
 
         API: https://docs.xrocket.exchange/api/pay/reference/http/mass-payouts-controller-create-mass-payouts
 
         :param asset: Asset of payouts.
-        :param payouts: List of payouts to process.
+        :param payouts: List of ``MassPayout`` instances to process.
         :return: ``MassPayouts``.
         """
-        return MassPayouts.de_json(self._request("POST", "/api/v1/mass-payouts", body={"asset": asset, "payouts": list(payouts)}))
-
-    def withdrawal_funds(self, client_withdrawal_id: str, network: str, address: str, asset: str, amount: str,
-                         comment: str | None = None, callback: Mapping[str, Any] | None = None) -> Withdrawal:
+        payout_data = []
+        for payout in payouts:
+            if not isinstance(payout, MassPayout):
+                raise TypeError("payouts must contain only MassPayout instances.")
+            payout_data.append(payout.to_dict())
+        return MassPayouts.de_json(self._request("POST", "/api/v1/mass-payouts", body={"asset": asset, "payouts": payout_data}))
+
+    def create_withdrawal(self, client_withdrawal_id: str, network: str, address: str, asset: str, amount: str | int | float,
+                         comment: str | None = None, callback: WithdrawalCallback | None = None) -> Withdrawal:
         """Withdrawal funds from application to external wallet.
 
         API: https://docs.xrocket.exchange/api/pay/reference/http/withdrawal-controller-create-withdrawal
@@ -438,14 +583,14 @@ class xRocketPayAPI:
         :param network: Network code.
         :param address: Withdrawal address.
         :param asset: Asset code.
-        :param amount: Withdrawal amount.
+        :param amount: Withdrawal amount. A numeric value is encoded as an API string.
         :param comment: Withdrawal comment.
-        :param callback: Webhook settings for withdrawal status updates.
+        :param callback: Webhook settings for withdrawal status updates as a ``WithdrawalCallback`` instance.
         :return: ``Withdrawal``.
         """
-        return Withdrawal.de_json(self._request("POST", "/api/v1/withdrawals", body=_without_none(
-            clientWithdrawalId=client_withdrawal_id, network=network, address=address, asset=asset, amount=str(amount),
-            comment=comment, callback=callback,
+        return Withdrawal.de_json(self._request("POST", "/api/v1/withdrawals", body=self.__without_none(
+            clientWithdrawalId=client_withdrawal_id, network=network, address=address, asset=asset, amount=self.__number_as_string(amount, "amount"),
+            comment=comment, callback=self.__request_model(callback, WithdrawalCallback, "callback"),
         )))
 
     def get_withdrawals_list(self, from_date: str | None = None, to_date: str | None = None, status: str | None = None,
@@ -461,7 +606,7 @@ class xRocketPayAPI:
         :param limit: No description is provided.
         :return: ``WithdrawalsList``.
         """
-        return WithdrawalsList.de_json(self._request("GET", "/api/v1/withdrawals", params=_without_none(
+        return WithdrawalsList.de_json(self._request("GET", "/api/v1/withdrawals", params=self.__without_none(
             fromDate=from_date, toDate=to_date, status=status, cursor=cursor, limit=limit,
         )))
 
@@ -474,7 +619,7 @@ class xRocketPayAPI:
         :param client_withdrawal_id: Unique withdrawal ID in your system to prevent double spends.
         :return: ``Withdrawal``.
         """
-        return Withdrawal.de_json(self._request("GET", "/api/v1/withdrawal", params=_identifier("withdrawalId", withdrawal_id, "clientWithdrawalId", client_withdrawal_id)))
+        return Withdrawal.de_json(self._request("GET", "/api/v1/withdrawal", params=self.__identifier("withdrawalId", withdrawal_id, "clientWithdrawalId", client_withdrawal_id)))
 
     def get_withdrawal_quotas(self, network: str, asset: str) -> WithdrawalQuotas:
         """Get application withdrawal quotas.
@@ -487,7 +632,7 @@ class xRocketPayAPI:
         """
         return WithdrawalQuotas.de_json(self._request("GET", "/api/v1/withdrawal-quotas", params={"network": network, "asset": asset}))
 
-    def create_withdrawal_link(self, network: str, address: str, asset: str, amount: str, comment: str | None = None,
+    def create_withdrawal_link(self, network: str, address: str, asset: str, amount: str | int | float, comment: str | None = None,
                                platform: str | None = None) -> WithdrawalLink:
         """Create withdrawal link.
 
@@ -496,11 +641,11 @@ class xRocketPayAPI:
         :param network: Network code.
         :param address: Withdrawal address.
         :param asset: Asset code.
-        :param amount: Withdrawal amount.
+        :param amount: Withdrawal amount. A numeric value is encoded as an API string.
         :param comment: Withdrawal comment.
         :param platform: Platform identifier (optional, use only if provided by xRocket).
         :return: ``WithdrawalLink``.
         """
-        return WithdrawalLink.de_json(self._request("POST", "/api/v1/withdrawal-link", body=_without_none(
-            network=network, address=address, asset=asset, amount=str(amount), comment=comment, platform=platform,
+        return WithdrawalLink.de_json(self._request("POST", "/api/v1/withdrawal-link", body=self.__without_none(
+            network=network, address=address, asset=asset, amount=self.__number_as_string(amount, "amount"), comment=comment, platform=platform,
         )))