pytonapi 2.1.0__tar.gz → 2.2.0__tar.gz

{pytonapi-2.1.0/pytonapi.egg-info → pytonapi-2.2.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: pytonapi
-Version: 2.1.0
+Version: 2.2.0
 Summary: Python SDK for TONAPI — REST API, streaming, and webhooks for TON blockchain.
 Author: nessshon
 Maintainer: nessshon
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/nessshon/tonapi/
 Project-URL: Examples, https://github.com/nessshon/tonapi/tree/main/examples/
+Project-URL: Documentation, https://tonapi.ness.su/
 Keywords: AsyncIO,REST API,SDK,TON,TON blockchain,TONAPI,The Open Network,blockchain,crypto,streaming,webhooks
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
@@ -25,6 +26,16 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: environs>=11.0.0; extra == "dev"
+Requires-Dist: fastapi>=0.115.0; extra == "dev"
+Requires-Dist: jinja2>=3.1; extra == "dev"
+Requires-Dist: mypy>=1.19.0; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Requires-Dist: uvicorn>=0.34.0; extra == "dev"
 Dynamic: license-file
 
 # 📦 TON API
@@ -80,9 +91,20 @@ pip install pytonapi
 
 - [Get account info](https://github.com/nessshon/tonapi/blob/main/examples/get_account_info.py)
 - [Get account transactions](https://github.com/nessshon/tonapi/blob/main/examples/get_account_transactions.py)
+- [Get jetton info](https://github.com/nessshon/tonapi/blob/main/examples/get_jetton_info.py)
 - [Get NFTs by owner](https://github.com/nessshon/tonapi/blob/main/examples/get_nft_by_owner.py)
 - [Get NFTs by collection](https://github.com/nessshon/tonapi/blob/main/examples/get_nft_by_collection.py)
 
+**Emulation & Sending**
+
+- [Send message](https://github.com/nessshon/tonapi/blob/main/examples/send_message.py)
+- [Emulate message](https://github.com/nessshon/tonapi/blob/main/examples/emulate_message.py)
+
+**Transfers** (requires [tonutils](https://github.com/nessshon/tonutils))
+
+- [Transfer TON](https://github.com/nessshon/tonapi/blob/main/examples/transfer_ton.py)
+- [Gasless transfer](https://github.com/nessshon/tonapi/blob/main/examples/transfer_gasless.py)
+
 **Streaming** (SSE & WebSocket)
 
 - [SSE subscriptions](https://github.com/nessshon/tonapi/blob/main/examples/streaming_sse.py)
@@ -93,11 +115,6 @@ pip install pytonapi
 - [FastAPI webhook server](https://github.com/nessshon/tonapi/blob/main/examples/webhook_fastapi.py)
 - [aiohttp webhook server](https://github.com/nessshon/tonapi/blob/main/examples/webhook_aiohttp.py)
 
-**Transfers** (requires [tonutils](https://github.com/nessshon/tonutils))
-
-- [Transfer TON](https://github.com/nessshon/tonapi/blob/main/examples/transfer_ton.py)
-- [Gasless transfer](https://github.com/nessshon/tonapi/blob/main/examples/transfer_gasless.py)
-
 ## License
 
 This repository is distributed under the [MIT License](https://github.com/nessshon/tonapi/blob/main/LICENSE).

{pytonapi-2.1.0 → pytonapi-2.2.0}/README.md

@@ -51,9 +51,20 @@ pip install pytonapi
 
 - [Get account info](https://github.com/nessshon/tonapi/blob/main/examples/get_account_info.py)
 - [Get account transactions](https://github.com/nessshon/tonapi/blob/main/examples/get_account_transactions.py)
+- [Get jetton info](https://github.com/nessshon/tonapi/blob/main/examples/get_jetton_info.py)
 - [Get NFTs by owner](https://github.com/nessshon/tonapi/blob/main/examples/get_nft_by_owner.py)
 - [Get NFTs by collection](https://github.com/nessshon/tonapi/blob/main/examples/get_nft_by_collection.py)
 
+**Emulation & Sending**
+
+- [Send message](https://github.com/nessshon/tonapi/blob/main/examples/send_message.py)
+- [Emulate message](https://github.com/nessshon/tonapi/blob/main/examples/emulate_message.py)
+
+**Transfers** (requires [tonutils](https://github.com/nessshon/tonutils))
+
+- [Transfer TON](https://github.com/nessshon/tonapi/blob/main/examples/transfer_ton.py)
+- [Gasless transfer](https://github.com/nessshon/tonapi/blob/main/examples/transfer_gasless.py)
+
 **Streaming** (SSE & WebSocket)
 
 - [SSE subscriptions](https://github.com/nessshon/tonapi/blob/main/examples/streaming_sse.py)
@@ -64,11 +75,6 @@ pip install pytonapi
 - [FastAPI webhook server](https://github.com/nessshon/tonapi/blob/main/examples/webhook_fastapi.py)
 - [aiohttp webhook server](https://github.com/nessshon/tonapi/blob/main/examples/webhook_aiohttp.py)
 
-**Transfers** (requires [tonutils](https://github.com/nessshon/tonutils))
-
-- [Transfer TON](https://github.com/nessshon/tonapi/blob/main/examples/transfer_ton.py)
-- [Gasless transfer](https://github.com/nessshon/tonapi/blob/main/examples/transfer_gasless.py)
-
 ## License
 
 This repository is distributed under the [MIT License](https://github.com/nessshon/tonapi/blob/main/LICENSE).

{pytonapi-2.1.0 → pytonapi-2.2.0}/pyproject.toml

@@ -53,6 +53,20 @@ pytonapi = "pytonapi.cli:main"
 [project.urls]
 Homepage = "https://github.com/nessshon/tonapi/"
 Examples = "https://github.com/nessshon/tonapi/tree/main/examples/"
+Documentation = "https://tonapi.ness.su/"
+
+[project.optional-dependencies]
+dev = [
+    "environs>=11.0.0",
+    "fastapi>=0.115.0",
+    "jinja2>=3.1",
+    "mypy>=1.19.0",
+    "pyyaml>=6.0",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8.0",
+    "uvicorn>=0.34.0",
+]
 
 [tool.setuptools.packages.find]
 include = ["pytonapi", "pytonapi.*"]
@@ -128,10 +142,10 @@ ignore = [
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
 "pytonapi/rest/models/*" = ["D101"]
-"tests/*" = ["D101", "D102", "T20"]
-"tests/rest/fixtures.py" = ["E501"]
 "codegen/*" = ["T20"]
 "examples/*" = ["D", "T20", "RUF006", "RUF059"]
+"tests/*" = ["D101", "D102", "D103", "T20"]
+"tests/rest/fixtures.py" = ["E501"]
 
 [tool.ruff.lint.isort]
 known-first-party = ["pytonapi"]
@@ -158,4 +172,7 @@ enable_error_code = [
 [[tool.mypy.overrides]]
 module = "tests.*"
 disallow_untyped_defs = false
-disallow_incomplete_defs = false
+disallow_incomplete_defs = false
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

{pytonapi-2.1.0 → pytonapi-2.2.0}/pytonapi/__meta__.py

@@ -3,6 +3,6 @@
 # This source code is licensed under the MIT License found in the
 # LICENSE file in the root directory of this source tree.
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 __author__ = "nessshon"
 __url__ = "https://github.com/nessshon/tonapi"

pytonapi-2.2.0/pytonapi/streaming/__init__.py

@@ -0,0 +1,35 @@
+from pytonapi.streaming.models import (
+    AccountState,
+    AccountStateNotification,
+    ActionsNotification,
+    ActionType,
+    ConnectionState,
+    EventType,
+    Finality,
+    JettonsNotification,
+    JettonWallet,
+    StreamNotification,
+    TraceInvalidatedNotification,
+    TraceNotification,
+    TransactionsNotification,
+)
+from pytonapi.streaming.sse import TonapiSSE
+from pytonapi.streaming.ws import TonapiWebSocket
+
+__all__ = [
+    "AccountState",
+    "AccountStateNotification",
+    "ActionType",
+    "ActionsNotification",
+    "ConnectionState",
+    "EventType",
+    "Finality",
+    "JettonWallet",
+    "JettonsNotification",
+    "StreamNotification",
+    "TonapiSSE",
+    "TonapiWebSocket",
+    "TraceInvalidatedNotification",
+    "TraceNotification",
+    "TransactionsNotification",
+]

pytonapi-2.2.0/pytonapi/streaming/base.py

@@ -0,0 +1,492 @@
+from __future__ import annotations
+
+import abc
+import asyncio
+import inspect
+import typing as t
+from dataclasses import dataclass
+
+import aiohttp
+
+from pytonapi.client import BaseClient
+from pytonapi.exceptions import (
+    STREAMING_RECOVERABLE,
+    TONAPIConnectionLostError,
+    TONAPIError,
+)
+from pytonapi.streaming.models import (
+    NOTIFICATION_MODEL_MAP,
+    ActionsNotification,
+    ConnectionState,
+    EventType,
+    Finality,
+    StreamNotification,
+    _FinalityMixin,
+)
+from pytonapi.types import (
+    DEFAULT_RECONNECT_POLICY,
+    NETWORK_BASE_URLS,
+    Network,
+    ReconnectPolicy,
+)
+
+_F = t.TypeVar("_F", bound=t.Callable[..., t.Any])
+
+_FINALITY_ORDER: t.Final[dict[str, int]] = {
+    "pending": 0,
+    "confirmed": 1,
+    "finalized": 2,
+}
+
+_SUBSCRIBABLE: t.Final[frozenset[str]] = frozenset(
+    {
+        EventType.TRANSACTIONS,
+        EventType.ACTIONS,
+        EventType.TRACE,
+        EventType.ACCOUNT_STATE_CHANGE,
+        EventType.JETTONS_CHANGE,
+    }
+)
+
+
+@dataclass(slots=True)
+class _Handler:
+    callback: t.Callable[..., t.Any]
+    min_finality: Finality | None = None
+    action_types: list[str] | None = None
+
+
+class StreamingBase(BaseClient, abc.ABC):
+    """Abstract base for streaming transports (SSE / WebSocket)."""
+
+    def __init__(
+        self,
+        api_key: str,
+        network: Network,
+        *,
+        base_url: str | None = None,
+        session: aiohttp.ClientSession | None = None,
+        headers: dict[str, str] | None = None,
+        reconnect_policy: ReconnectPolicy | None = None,
+        on_state_change: t.Callable[[ConnectionState], t.Any] | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url or NETWORK_BASE_URLS[network],
+            session=session,
+            headers=headers,
+            timeout=0.0,
+            retry_policy=None,
+        )
+        self._reconnect_policy = reconnect_policy or DEFAULT_RECONNECT_POLICY
+        self._on_state_change = on_state_change
+        self._handlers: dict[str, list[_Handler]] = {}
+        self._stop: asyncio.Event | None = None
+        self._state: ConnectionState = ConnectionState.IDLE
+        self._subscribed_event = asyncio.Event()
+
+    @property
+    def state(self) -> ConnectionState:
+        """Current connection state."""
+        return self._state
+
+    @property
+    def is_subscribed(self) -> bool:
+        """``True`` if currently subscribed and receiving notifications."""
+        return self._state == ConnectionState.SUBSCRIBED
+
+    @property
+    def is_connecting(self) -> bool:
+        """``True`` if establishing initial connection."""
+        return self._state == ConnectionState.CONNECTING
+
+    @property
+    def is_reconnecting(self) -> bool:
+        """``True`` if reconnecting after a connection loss."""
+        return self._state == ConnectionState.RECONNECTING
+
+    async def wait_subscribed(self, timeout: float | None = None) -> None:
+        """Wait until the transport reaches ``SUBSCRIBED`` state.
+
+        :param timeout: Maximum seconds to wait, or ``None`` for no limit.
+        :raises asyncio.TimeoutError: If *timeout* is reached before subscribing.
+        """
+        if self._state == ConnectionState.SUBSCRIBED:
+            return
+        await asyncio.wait_for(self._subscribed_event.wait(), timeout=timeout)
+
+    async def _set_state(self, new: ConnectionState) -> None:
+        if self._state == new:
+            return
+        if self._state == ConnectionState.SUBSCRIBED:
+            self._subscribed_event.clear()
+        self._state = new
+        if new == ConnectionState.SUBSCRIBED:
+            self._subscribed_event.set()
+        if self._on_state_change is not None:
+            result = self._on_state_change(new)
+            if inspect.isawaitable(result):
+                await result
+
+    @t.overload
+    def _register(
+        self,
+        notification_type: str,
+        callback: _F,
+        *,
+        min_finality: Finality | str | None = ...,
+        action_types: list[str] | None = ...,
+    ) -> _F: ...
+
+    @t.overload
+    def _register(
+        self,
+        notification_type: str,
+        callback: None = ...,
+        *,
+        min_finality: Finality | str | None = ...,
+        action_types: list[str] | None = ...,
+    ) -> t.Callable[[_F], _F]: ...
+
+    def _register(
+        self,
+        notification_type: str,
+        callback: _F | None = None,
+        *,
+        min_finality: Finality | str | None = None,
+        action_types: list[str] | None = None,
+    ) -> _F | t.Callable[[_F], _F]:
+        def decorator(fn: _F) -> _F:
+            parsed = Finality(min_finality) if isinstance(min_finality, str) else min_finality
+            self._handlers.setdefault(notification_type, []).append(
+                _Handler(
+                    callback=fn,
+                    min_finality=parsed,
+                    action_types=(
+                        [a.value if hasattr(a, "value") else a for a in action_types] if action_types else None
+                    ),
+                ),
+            )
+            return fn
+
+        return decorator(callback) if callback is not None else decorator
+
+    @t.overload
+    def on_transactions(self, callback: _F, *, min_finality: Finality | str | None = ...) -> _F: ...
+
+    @t.overload
+    def on_transactions(
+        self, callback: None = ..., *, min_finality: Finality | str | None = ...
+    ) -> t.Callable[[_F], _F]: ...
+
+    def on_transactions(
+        self,
+        callback: _F | None = None,
+        *,
+        min_finality: Finality | str | None = None,
+    ) -> _F | t.Callable[[_F], _F]:
+        """Register a handler for ``transactions`` notifications."""
+        return self._register(EventType.TRANSACTIONS, callback, min_finality=min_finality)
+
+    @t.overload
+    def on_actions(
+        self, callback: _F, *, min_finality: Finality | str | None = ..., action_types: list[str] | None = ...
+    ) -> _F: ...
+
+    @t.overload
+    def on_actions(
+        self, callback: None = ..., *, min_finality: Finality | str | None = ..., action_types: list[str] | None = ...
+    ) -> t.Callable[[_F], _F]: ...
+
+    def on_actions(
+        self,
+        callback: _F | None = None,
+        *,
+        min_finality: Finality | str | None = None,
+        action_types: list[str] | None = None,
+    ) -> _F | t.Callable[[_F], _F]:
+        """Register a handler for ``actions`` notifications."""
+        return self._register(
+            EventType.ACTIONS,
+            callback,
+            min_finality=min_finality,
+            action_types=action_types,
+        )
+
+    @t.overload
+    def on_traces(self, callback: _F, *, min_finality: Finality | str | None = ...) -> _F: ...
+
+    @t.overload
+    def on_traces(self, callback: None = ..., *, min_finality: Finality | str | None = ...) -> t.Callable[[_F], _F]: ...
+
+    def on_traces(
+        self,
+        callback: _F | None = None,
+        *,
+        min_finality: Finality | str | None = None,
+    ) -> _F | t.Callable[[_F], _F]:
+        """Register a handler for ``trace`` notifications."""
+        return self._register(EventType.TRACE, callback, min_finality=min_finality)
+
+    @t.overload
+    def on_account_states(self, callback: _F, *, min_finality: Finality | str | None = ...) -> _F: ...
+
+    @t.overload
+    def on_account_states(
+        self, callback: None = ..., *, min_finality: Finality | str | None = ...
+    ) -> t.Callable[[_F], _F]: ...
+
+    def on_account_states(
+        self,
+        callback: _F | None = None,
+        *,
+        min_finality: Finality | str | None = None,
+    ) -> _F | t.Callable[[_F], _F]:
+        """Register a handler for ``account_state_change`` notifications."""
+        if min_finality is not None:
+            raw = min_finality.value if isinstance(min_finality, Finality) else min_finality
+            if raw == Finality.PENDING:
+                raise ValueError(
+                    "account_state_change events are only emitted at confirmed and finalized finality levels"
+                )
+        return self._register(EventType.ACCOUNT_STATE_CHANGE, callback, min_finality=min_finality)
+
+    @t.overload
+    def on_jettons(self, callback: _F, *, min_finality: Finality | str | None = ...) -> _F: ...
+
+    @t.overload
+    def on_jettons(
+        self, callback: None = ..., *, min_finality: Finality | str | None = ...
+    ) -> t.Callable[[_F], _F]: ...
+
+    def on_jettons(
+        self,
+        callback: _F | None = None,
+        *,
+        min_finality: Finality | str | None = None,
+    ) -> _F | t.Callable[[_F], _F]:
+        """Register a handler for ``jettons_change`` notifications."""
+        if min_finality is not None:
+            raw = min_finality.value if isinstance(min_finality, Finality) else min_finality
+            if raw == Finality.PENDING:
+                raise ValueError("jettons_change events are only emitted at confirmed and finalized finality levels")
+        return self._register(EventType.JETTONS_CHANGE, callback, min_finality=min_finality)
+
+    @t.overload
+    def on_trace_invalidated(self, callback: _F) -> _F: ...
+
+    @t.overload
+    def on_trace_invalidated(self, callback: None = ...) -> t.Callable[[_F], _F]: ...
+
+    def on_trace_invalidated(
+        self,
+        callback: _F | None = None,
+    ) -> _F | t.Callable[[_F], _F]:
+        """Register a handler for ``trace_invalidated`` notifications."""
+        return self._register(EventType.TRACE_INVALIDATED, callback)
+
+    def _build_subscription(
+        self,
+        addresses: list[str] | None,
+        trace_external_hash_norms: list[str] | None,
+    ) -> dict[str, t.Any]:
+        types = sorted(k for k in self._handlers if k in _SUBSCRIBABLE)
+        if not types:
+            raise ValueError("No subscribable notification handlers registered")
+
+        fin = Finality.FINALIZED
+        for handlers in self._handlers.values():
+            for h in handlers:
+                if h.min_finality is not None and _FINALITY_ORDER[h.min_finality] < _FINALITY_ORDER[fin]:
+                    fin = h.min_finality
+
+        action_types: list[str] | None = None
+        ah = self._handlers.get(EventType.ACTIONS, [])
+        if ah and all(h.action_types is not None for h in ah):
+            merged = {at for h in ah for at in (h.action_types or [])}
+            action_types = sorted(merged) if merged else None
+
+        non_trace = [et for et in types if et != EventType.TRACE]
+        if non_trace and not addresses:
+            raise ValueError(
+                f"addresses are required for event types: {non_trace}. Only 'trace' subscriptions can omit addresses.",
+            )
+        if EventType.TRACE in types and not trace_external_hash_norms:
+            raise ValueError("trace_external_hash_norms are required for trace subscriptions")
+
+        result: dict[str, t.Any] = {"types": types, "min_finality": fin}
+        if addresses:
+            result["addresses"] = addresses
+        if trace_external_hash_norms:
+            result["trace_external_hash_norms"] = trace_external_hash_norms
+        if action_types:
+            result["action_types"] = action_types
+        return result
+
+    async def _dispatch(self, notification: StreamNotification) -> None:
+        for handler in self._handlers.get(notification.type, []):
+            if handler.min_finality is not None and isinstance(notification, _FinalityMixin):
+                n_order = _FINALITY_ORDER.get(getattr(notification, "finality", ""), -1)
+                if n_order < 0:
+                    continue
+                h_order = _FINALITY_ORDER.get(handler.min_finality.value, 0)
+                if n_order < h_order:
+                    continue
+
+            if isinstance(notification, ActionsNotification) and handler.action_types is not None:
+                wanted = set(handler.action_types)
+                if not any(a.get("type") in wanted for a in notification.actions):
+                    continue
+
+            result = handler.callback(notification)
+            if inspect.isawaitable(result):
+                await result
+
+    async def subscribe(
+        self,
+        *,
+        addresses: list[str] | None = None,
+        trace_external_hash_norms: list[str] | None = None,
+        types: list[str] | None = None,
+        min_finality: Finality | str = Finality.FINALIZED,
+        include_address_book: bool = False,
+        include_metadata: bool = False,
+        action_types: list[str] | None = None,
+        supported_action_types: list[str] | None = None,
+        stop: asyncio.Event | None = None,
+    ) -> t.AsyncGenerator[StreamNotification, None]:
+        """Low-level subscription generator.
+
+        Opens one connection, yields typed notifications. Reconnects automatically.
+        For high-level usage prefer ``on_*()`` decorators + ``start()``.
+        """
+        non_trace = [et for et in (types or []) if et != "trace"]
+        if non_trace and not addresses:
+            raise ValueError(
+                f"addresses are required for event types: {non_trace}. Only 'trace' subscriptions can omit addresses.",
+            )
+
+        params: dict[str, t.Any] = {
+            "min_finality": min_finality.value if isinstance(min_finality, Finality) else min_finality,
+            "include_address_book": include_address_book,
+            "include_metadata": include_metadata,
+        }
+        if addresses:
+            params["addresses"] = addresses
+        if trace_external_hash_norms:
+            params["trace_external_hash_norms"] = trace_external_hash_norms
+        if types:
+            params["types"] = [et.value if hasattr(et, "value") else et for et in types]
+        if action_types:
+            params["action_types"] = [a.value if hasattr(a, "value") else a for a in action_types]
+        if supported_action_types:
+            params["supported_action_types"] = supported_action_types
+
+        async for data in self._stream_with_reconnect(params, stop):
+            model = NOTIFICATION_MODEL_MAP.get(data.get("type", ""))
+            if model is not None:
+                yield model.model_validate(data)  # type: ignore[misc]
+
+    async def _stream_with_reconnect(
+        self,
+        params: dict[str, t.Any],
+        stop: asyncio.Event | None = None,
+    ) -> t.AsyncGenerator[dict[str, t.Any], None]:
+        attempt = 0
+        await self._set_state(ConnectionState.CONNECTING)
+
+        while not (stop and stop.is_set()):
+            try:
+                async for data in self._open_stream(params, stop):
+                    attempt = 0
+                    yield data
+            except TONAPIError as exc:
+                if not isinstance(exc, STREAMING_RECOVERABLE):
+                    await self._set_state(ConnectionState.IDLE)
+                    raise
+            except (aiohttp.ClientError, OSError):
+                pass
+
+            if stop and stop.is_set():
+                await self._set_state(ConnectionState.IDLE)
+                return
+
+            attempt += 1
+            if self._reconnect_policy.max_reconnects != -1 and attempt > self._reconnect_policy.max_reconnects:
+                await self._set_state(ConnectionState.IDLE)
+                raise TONAPIConnectionLostError(attempts=attempt)
+
+            await self._set_state(ConnectionState.RECONNECTING)
+            await asyncio.sleep(self._reconnect_policy.delay_for_attempt(attempt - 1))
+
+    @abc.abstractmethod
+    async def _open_stream(
+        self,
+        params: dict[str, t.Any],
+        stop: asyncio.Event | None = None,
+    ) -> t.AsyncGenerator[dict[str, t.Any], None]:
+        """Open a transport-specific streaming connection and yield raw notification dicts."""
+        raise NotImplementedError
+        yield  # type: ignore[unreachable]
+
+    async def start(
+        self,
+        addresses: list[str] | None = None,
+        *,
+        trace_external_hash_norms: list[str] | None = None,
+        include_address_book: bool = False,
+        include_metadata: bool = False,
+        supported_action_types: list[str] | None = None,
+    ) -> None:
+        """Start the streaming transport: create session, subscribe, and dispatch.
+
+        Blocks until ``stop()`` is called or a fatal error occurs.
+        Creates an internal aiohttp session on entry and closes it on exit
+        (unless an external session was provided via the constructor).
+
+        :param addresses: Wallet/contract addresses to monitor, in any form.
+        :param trace_external_hash_norms: Trace hashes for trace subscriptions.
+        :param include_address_book: Include DNS-resolved names in notifications.
+        :param include_metadata: Include token metadata in notifications.
+        :param supported_action_types: Advertise client-supported action types.
+        """
+        if self._stop is not None:
+            raise RuntimeError("start() is already active")
+
+        sub = self._build_subscription(addresses, trace_external_hash_norms)
+        self._stop = asyncio.Event()
+        await self.create_session()
+        try:
+            async for notification in self.subscribe(
+                addresses=sub.get("addresses"),
+                trace_external_hash_norms=sub.get("trace_external_hash_norms"),
+                types=sub.get("types"),
+                min_finality=sub["min_finality"],
+                action_types=sub.get("action_types"),
+                include_address_book=include_address_book,
+                include_metadata=include_metadata,
+                supported_action_types=supported_action_types,
+                stop=self._stop,
+            ):
+                await self._dispatch(notification)
+        finally:
+            self._stop = None
+            await self.close_session()
+
+    async def stop(self) -> None:
+        """Stop the streaming transport and release resources.
+
+        Signals the dispatch loop to exit, closes the aiohttp session
+        (unless externally provided), and resets the connection state.
+        Safe to call multiple times.
+        """
+        if self._stop is not None:
+            self._stop.set()
+        await self.close_session()
+        await self._set_state(ConnectionState.IDLE)
+
+    async def __aenter__(self) -> t.NoReturn:
+        raise TypeError("Streaming transports do not support 'async with'. Use start() and stop() instead.")
+
+    async def __aexit__(self, *args: t.Any) -> None:
+        pass