binance-sdk-cms 1.0.0__tar.gz

binance_sdk_cms-1.0.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0 - 2026-10-15
+
+- Initial release

binance_sdk_cms-1.0.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Binance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

binance_sdk_cms-1.0.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: binance-sdk-cms
+Version: 1.0.0
+Summary: Official Binance Cms Connector - A lightweight library that provides a convenient interface to Binance's Cms REST API and WebSocket Streams.
+License: MIT
+License-File: LICENCE
+Author: Binance
+Requires-Python: >=3.10,<3.15
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: aiohttp (>=3.14.5,<4.0.0)
+Requires-Dist: binance-common (==4.6.0)
+Requires-Dist: pycryptodome (>=3.17,<5)
+Requires-Dist: pydantic (>=2.14.1)
+Requires-Dist: requests (>=2.34.2)
+Requires-Dist: urllib3 (>=2.8.0)

binance_sdk_cms-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[tool.poetry]
+name = "binance-sdk-cms"
+version = "1.0.0"
+description = "Official Binance Cms Connector - A lightweight library that provides a convenient interface to Binance's Cms REST API and WebSocket Streams."
+authors = ["Binance"]
+license = "MIT"
+include = ["CHANGELOG.md", "LICENSE"]
+packages = [
+  { include = "binance_sdk_cms", from = "src" }
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.15"
+requests = ">=2.34.2"
+urllib3 = ">=2.8.0"
+pydantic = ">=2.14.1"
+pycryptodome = ">=3.17,<5"
+aiohttp = "^3.14.5"
+binance-common = "4.6.0"
+
+[tool.poetry.group.dev.dependencies]
+tox = "^4.65.0"
+pytest-asyncio = "^1.4.0"
+black = "^26.10.1"
+ruff = "^0.17.0"
+pytest = ">=9.1.1"
+
+[tool.ruff]
+exclude = [".git", ".tox", "build", "dist"]
+lint.select = ["E4", "E7", "E9", "F"]
+lint.ignore = ["E741"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

binance_sdk_cms-1.0.0/src/binance_sdk_cms/__init__.py

@@ -0,0 +1,31 @@
+from binance_sdk_cms.cms import Cms
+from binance_common.errors import (
+    ClientError,
+    RequiredError,
+    UnauthorizedError,
+    ForbiddenError,
+    TooManyRequestsError,
+    RateLimitBanError,
+    ServerError,
+    NetworkError,
+    NotFoundError,
+    BadRequestError,
+)
+from binance_common.constants import (
+    CMS_WS_STREAMS_PROD_URL,
+)
+
+__all__ = [
+    "Cms",
+    "CMS_WS_STREAMS_PROD_URL",
+    "ClientError",
+    "RequiredError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "TooManyRequestsError",
+    "RateLimitBanError",
+    "ServerError",
+    "NetworkError",
+    "NotFoundError",
+    "BadRequestError",
+]

binance_sdk_cms-1.0.0/src/binance_sdk_cms/cms.py

@@ -0,0 +1,44 @@
+import platform
+from importlib.metadata import version
+
+from binance_common.configuration import (
+    ConfigurationWebSocketStreams,
+)
+from binance_common.constants import (
+    CMS_WS_STREAMS_PROD_URL,
+)
+from . import metadata
+from .websocket_streams import CmsWebSocketStreams
+
+LIB_NAME = metadata.NAME
+LIB_VERSION = version(LIB_NAME)
+
+
+class Cms:
+    """Cms API that exposes Stream APIs in a single interface."""
+
+    def __init__(
+        self,
+        config_ws_streams: ConfigurationWebSocketStreams = None,
+    ) -> None:
+        self._websocket_streams = None
+        self._websocket_streams_config = (
+            ConfigurationWebSocketStreams()
+            if config_ws_streams is None
+            else config_ws_streams
+        )
+
+    @property
+    def websocket_streams(self) -> CmsWebSocketStreams:
+        if self._websocket_streams is None and self._websocket_streams_config:
+            self._websocket_streams_config.user_agent = f"{LIB_NAME}/{LIB_VERSION} (Python/{platform.python_version()}; {platform.system()}; {platform.machine()})"
+            self._websocket_streams_config.stream_url = (
+                CMS_WS_STREAMS_PROD_URL
+                if self._websocket_streams_config.stream_url is None
+                else self._websocket_streams_config.stream_url
+            )
+            self._websocket_streams = CmsWebSocketStreams(
+                self._websocket_streams_config
+            )
+
+        return self._websocket_streams

binance_sdk_cms-1.0.0/src/binance_sdk_cms/metadata.py

@@ -0,0 +1 @@
+NAME = "binance-sdk-cms"

binance_sdk_cms-1.0.0/src/binance_sdk_cms/websocket_streams/__init__.py

@@ -0,0 +1,13 @@
+"""
+Prediction Trading Streams
+
+Binance Web3 Prediction pushes 14 types of per-user business events in real time via the Binance SApi WebSocket channel, covering trading (market / limit), reward claim, fund transfer and market resolution, plus order book (bid/ask) quotes broadcast per topic. Business events are routed by exact `(topic, userId)` match; order book topics are broadcast to every subscriber. Delivery is at-most-once, ordering is not guaranteed, and offline messages are not cached — pull the latest state via the REST API after reconnecting and deduplicate on `pushId` (business events) or `marketId` + `updateTimestampMs` (order book).
+The version of the OpenAPI document: 1.0.0
+Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+Do not edit the class manually.
+"""
+
+from .websocket_streams import CmsWebSocketStreams
+
+__all__ = ["CmsWebSocketStreams"]

binance_sdk_cms-1.0.0/src/binance_sdk_cms/websocket_streams/models/__init__.py

@@ -0,0 +1,13 @@
+"""
+Prediction Trading Streams
+
+Binance Web3 Prediction pushes 14 types of per-user business events in real time via the Binance SApi WebSocket channel, covering trading (market / limit), reward claim, fund transfer and market resolution, plus order book (bid/ask) quotes broadcast per topic. Business events are routed by exact `(topic, userId)` match; order book topics are broadcast to every subscriber. Delivery is at-most-once, ordering is not guaranteed, and offline messages are not cached — pull the latest state via the REST API after reconnecting and deduplicate on `pushId` (business events) or `marketId` + `updateTimestampMs` (order book).
+The version of the OpenAPI document: 1.0.0
+Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+Do not edit the class manually.
+"""
+
+from .com_announcement_en_response import (
+    ComAnnouncementEnResponse as ComAnnouncementEnResponse,
+)

binance_sdk_cms-1.0.0/src/binance_sdk_cms/websocket_streams/models/com_announcement_en_response.py

@@ -0,0 +1,126 @@
+# coding: utf-8
+
+"""
+Prediction Trading Streams
+
+Binance Web3 Prediction pushes 14 types of per-user business events in real time via the Binance SApi WebSocket channel, covering trading (market / limit), reward claim, fund transfer and market resolution, plus order book (bid/ask) quotes broadcast per topic. Business events are routed by exact `(topic, userId)` match; order book topics are broadcast to every subscriber. Delivery is at-most-once, ordering is not guaranteed, and offline messages are not cached — pull the latest state via the REST API after reconnecting and deduplicate on `pushId` (business events) or `marketId` + `updateTimestampMs` (order book).
+The version of the OpenAPI document: 1.0.0
+Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+Do not edit the class manually.
+"""
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, Field, StrictInt, StrictStr
+from typing import Any, ClassVar, Dict, List, Optional
+from typing import Set
+from typing_extensions import Self
+
+
+class ComAnnouncementEnResponse(BaseModel):
+    """
+    ComAnnouncementEnResponse
+    """  # noqa: E501
+
+    catalog_id: Optional[StrictInt] = Field(
+        default=None, description="Catalog ID", alias="catalogId"
+    )
+    catalog_name: Optional[StrictStr] = Field(
+        default=None, description="Catalog Name", alias="catalogName"
+    )
+    publish_date: Optional[StrictInt] = Field(
+        default=None,
+        description="Publish timestamp (milliseconds)",
+        alias="publishDate",
+    )
+    title: Optional[StrictStr] = Field(default=None, description="Announcement title")
+    body: Optional[StrictStr] = Field(default=None, description="Announcement body")
+    disclaimer: Optional[StrictStr] = Field(default=None, description="Disclaimer")
+    additional_properties: Dict[str, Any] = {}
+    __properties: ClassVar[List[str]] = [
+        "catalog_id",
+        "catalog_name",
+        "publish_date",
+        "title",
+        "body",
+        "disclaimer",
+    ]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of ComAnnouncementEnResponse from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        * Fields in `self.additional_properties` are added to the output dict.
+        """
+        excluded_fields: Set[str] = set(
+            [
+                "additional_properties",
+            ]
+        )
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        # puts key-value pairs in additional_properties in the top level
+        if self.additional_properties is not None:
+            for _key, _value in self.additional_properties.items():
+                _dict[_key] = _value
+
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of ComAnnouncementEnResponse from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate(
+            {
+                "catalogId": obj.get("catalogId"),
+                "catalogName": obj.get("catalogName"),
+                "publishDate": obj.get("publishDate"),
+                "title": obj.get("title"),
+                "body": obj.get("body"),
+                "disclaimer": obj.get("disclaimer"),
+            }
+        )
+        # store additional fields in additional_properties
+        for _key in obj.keys():
+            if _key not in cls.__properties:
+                _obj.additional_properties[_key] = obj.get(_key)
+
+        return _obj

binance_sdk_cms-1.0.0/src/binance_sdk_cms/websocket_streams/models/enums.py

@@ -0,0 +1,9 @@
+"""
+Prediction Trading Streams
+
+Binance Web3 Prediction pushes 14 types of per-user business events in real time via the Binance SApi WebSocket channel, covering trading (market / limit), reward claim, fund transfer and market resolution, plus order book (bid/ask) quotes broadcast per topic. Business events are routed by exact `(topic, userId)` match; order book topics are broadcast to every subscriber. Delivery is at-most-once, ordering is not guaranteed, and offline messages are not cached — pull the latest state via the REST API after reconnecting and deduplicate on `pushId` (business events) or `marketId` + `updateTimestampMs` (order book).
+The version of the OpenAPI document: 1.0.0
+Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+Do not edit the class manually.
+"""

binance_sdk_cms-1.0.0/src/binance_sdk_cms/websocket_streams/streams/__init__.py

@@ -0,0 +1,11 @@
+"""
+Prediction Trading Streams
+
+Binance Web3 Prediction pushes 14 types of per-user business events in real time via the Binance SApi WebSocket channel, covering trading (market / limit), reward claim, fund transfer and market resolution, plus order book (bid/ask) quotes broadcast per topic. Business events are routed by exact `(topic, userId)` match; order book topics are broadcast to every subscriber. Delivery is at-most-once, ordering is not guaranteed, and offline messages are not cached — pull the latest state via the REST API after reconnecting and deduplicate on `pushId` (business events) or `marketId` + `updateTimestampMs` (order book).
+The version of the OpenAPI document: 1.0.0
+Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+Do not edit the class manually.
+"""
+
+from .default_api import DefaultApi as DefaultApi

binance_sdk_cms-1.0.0/src/binance_sdk_cms/websocket_streams/streams/default_api.py

@@ -0,0 +1,64 @@
+"""
+Prediction Trading Streams
+
+Binance Web3 Prediction pushes 14 types of per-user business events in real time via the Binance SApi WebSocket channel, covering trading (market / limit), reward claim, fund transfer and market resolution, plus order book (bid/ask) quotes broadcast per topic. Business events are routed by exact `(topic, userId)` match; order book topics are broadcast to every subscriber. Delivery is at-most-once, ordering is not guaranteed, and offline messages are not cached — pull the latest state via the REST API after reconnecting and deduplicate on `pushId` (business events) or `marketId` + `updateTimestampMs` (order book).
+The version of the OpenAPI document: 1.0.0
+Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+Do not edit the class manually.
+"""
+
+from binance_common.utils import ws_streams_placeholder
+from binance_common.websocket import (
+    WebSocketStreamBase,
+    RequestStream,
+    RequestStreamHandle,
+)
+
+from ..models import ComAnnouncementEnResponse
+
+
+from typing import Optional
+
+
+class DefaultApi:
+    """Client for DefaultApi endpoints."""
+
+    def __init__(self, websocket_base: WebSocketStreamBase) -> None:
+        self.websocket_base = websocket_base
+
+    async def com_announcement_en(
+        self,
+        id: Optional[str] = None,
+    ) -> RequestStreamHandle:
+        r"""
+
+        /com_announcement_en
+        https://developers.binance.com/en/docs/products/announcements/announcement
+
+        Receive push notifications hen Binance publishes announcements in English (language code: en).
+
+        Args:
+                id (Optional[str] = None): Unique WebSocket request ID.
+
+        Returns:
+            RequestStreamHandle
+
+        Raises:
+            RequiredError: If a required parameter is missing.
+
+        """
+
+        stream = ws_streams_placeholder(
+            "/com_announcement_en".replace("/", "", 1),
+            {
+                "id": id,
+            },
+        )
+
+        return await RequestStream(
+            self.websocket_base,
+            stream=stream,
+            response_model=ComAnnouncementEnResponse,
+            stream_url="",
+        )

binance_sdk_cms-1.0.0/src/binance_sdk_cms/websocket_streams/websocket_streams.py

@@ -0,0 +1,188 @@
+"""
+Prediction Trading Streams
+
+Binance Web3 Prediction pushes 14 types of per-user business events in real time via the Binance SApi WebSocket channel, covering trading (market / limit), reward claim, fund transfer and market resolution, plus order book (bid/ask) quotes broadcast per topic. Business events are routed by exact `(topic, userId)` match; order book topics are broadcast to every subscriber. Delivery is at-most-once, ordering is not guaranteed, and offline messages are not cached — pull the latest state via the REST API after reconnecting and deduplicate on `pushId` (business events) or `marketId` + `updateTimestampMs` (order book).
+The version of the OpenAPI document: 1.0.0
+Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+Do not edit the class manually.
+"""
+
+import aiohttp
+import secrets
+from urllib.parse import quote, urlencode
+
+from pydantic import BaseModel
+from typing import Callable, Optional, TypeVar
+
+from binance_common.configuration import ConfigurationWebSocketStreams
+
+from binance_common.signature import Signers
+from binance_common.utils import get_signature, get_timestamp
+
+from binance_common.websocket import (
+    WebSocketStreamBase,
+    WebSocketConnection,
+    RequestStreamHandle,
+)
+
+
+from .streams.default_api import DefaultApi
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class CmsWebSocketStreams(WebSocketStreamBase):
+    def __init__(
+        self,
+        configuration: ConfigurationWebSocketStreams,
+    ) -> None:
+
+        stream_url = configuration.stream_url
+
+        super().__init__(configuration)
+        self.configuration = configuration
+
+        self.configuration.stream_url = stream_url
+        for attr in ("api_key", "api_secret", "private_key", "private_key_passphrase"):
+            if not hasattr(self.configuration, attr):
+                setattr(self.configuration, attr, None)
+        self._signer = (
+            Signers.get_signer(
+                self.configuration.private_key,
+                self.configuration.private_key_passphrase,
+            )
+            if self.configuration.private_key
+            else None
+        )
+
+        self._defaultApi = DefaultApi(self)
+
+    def _signed_url(self, url: str) -> str:
+        """Appends a freshly signed query string to the WebSocket URL.
+
+        Args:
+            url (str): The WebSocket URL to sign.
+        Returns:
+            str: The URL with the `random`, `recvWindow`, `timestamp` and `signature` query parameters.
+        """
+
+        query = urlencode(
+            {
+                "random": secrets.token_hex(16),
+                "recvWindow": 30000,
+                "timestamp": get_timestamp(),
+            }
+        )
+        signature = get_signature(self.configuration, query, self._signer)
+        return f"{url}?{query}&signature={quote(signature, safe='')}"
+
+    async def connect(self, url, configuration, ws_id=None, url_paths=None):
+        """Connects to the WebSocket server, sending the API key with every connection."""
+
+        if self.session is None:
+            self.session = aiohttp.ClientSession(
+                headers={"X-MBX-APIKEY": self.configuration.api_key or ""}
+            )
+        return await super().connect(
+            url, configuration, ws_id=ws_id, url_paths=url_paths
+        )
+
+    async def init_connection(self, url, configuration, url_path=None, ws_id=None):
+        """Opens a connection on a newly signed URL, so reconnects never reuse an expired signature."""
+
+        await super().init_connection(
+            self._signed_url(url), configuration, url_path=url_path, ws_id=ws_id
+        )
+
+    async def ping_server(self, connection: WebSocketConnection):
+        """Sends a ping message to the WebSocket server to check the connection status.
+
+        Args:
+            connection (WebSocketConnection): The WebSocket connection to send the ping message to.
+        """
+
+        if self.session:
+            await super().ping_ws_stream(connection=connection)
+        else:
+            raise ValueError("WebSocket session is not initialized.")
+
+    async def subscribe(
+        self,
+        streams,
+        response_model: Optional[T] = None,
+        stream_url: Optional[str] = None,
+    ):
+        """Subscribes to the specified WebSocket streams.
+
+        Args:
+            streams (list): A list of WebSocket streams to subscribe to.
+            response_model (Optional[T]): The Pydantic model to validate the response against.
+        """
+
+        await super().subscribe(
+            streams, response_model=response_model, stream_url=stream_url
+        )
+
+    async def unsubscribe(self, streams):
+        """Unsubscribes from the specified WebSocket streams.
+
+        Args:
+            streams (list): A list of WebSocket streams to unsubscribe from.
+        """
+
+        await super().unsubscribe(streams)
+
+    def on(self, event: str, callback: Callable[[T], None], stream: str):
+        """Registers a callback function for a specific WebSocket event.
+
+        Args:
+            event (str): The event type to listen for (e.g., 'message', 'error').
+            callback (Callable[[T], None]): The callback function to be called when the event occurs.
+            stream (str): The specific WebSocket stream to listen to.
+        """
+
+        super().on(event, callback, stream)
+
+    async def list_subscribe(self) -> dict:
+        """Lists all currently subscribed WebSocket streams.
+
+        Returns:
+            dict: A dictionary containing the current subscriptions.
+        """
+
+        return await super().list_subscribe()
+
+    async def close_connection(
+        self, connection: WebSocketConnection = None, close_session: bool = True
+    ):
+        """Closes the WebSocket connection and optionally the session.
+
+        Args:
+            connection (WebSocketConnection, optional): The WebSocket connection to close. If None, the current session's connection is used.
+            close_session (bool, optional): Whether to close the session after closing the connection. Defaults to True.
+        """
+
+        await super().close_connection(connection, close_session)
+
+    async def com_announcement_en(
+        self,
+        id: Optional[str] = None,
+    ) -> RequestStreamHandle:
+        r"""
+
+
+        Receive push notifications hen Binance publishes announcements in English (language code: en).
+
+        Args:
+            id (Optional[str] = None): Unique WebSocket request ID.
+
+        Returns:
+            RequestStreamHandle
+
+        Raises:
+            RequiredError: If a required parameter is missing.
+
+        """
+
+        return await self._defaultApi.com_announcement_en(id)