radion-sdk 0.2.0__tar.gz

radion_sdk-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --extra dev
+      - run: uv run ruff check
+      - run: uv run ty check

radion_sdk-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.ruff_cache/
+.DS_Store
+.env

radion_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Radion
+
+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.

radion_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: radion-sdk
+Version: 0.2.0
+Summary: Official async SDK for the Radion platform
+License: MIT
+License-File: LICENSE
+Keywords: async,polymarket,radion,realtime,sdk,websocket
+Requires-Python: >=3.10
+Requires-Dist: msgspec>=0.18.0
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: ty>=0.0.1a1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# radion-sdk
+
+[![PyPI version](https://img.shields.io/pypi/v/radion-sdk.svg)](https://pypi.org/project/radion-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/radion-sdk.svg)](https://pypi.org/project/radion-sdk/)
+[![license](https://img.shields.io/pypi/l/radion-sdk.svg)](./LICENSE)
+
+Official, async-first, fully-typed SDK for the [Radion](https://radion.app) platform.
+
+One client, one API key, every Radion product surface. Install `radion-sdk`; import it as `radion`.
+
+```python
+radion = Radion(api_key=os.getenv("RADION_API_KEY"))
+await radion.realtime.connect()
+await radion.realtime.subscribe(Subscription(id="trades", channel="trades"))
+
+@radion.realtime.on("trades")
+async def handle_trade(event):
+    print(event.id, event.data)
+```
+
+## Features
+
+- **Unified client** — `Radion(api_key=...)` is the single entry point for every product surface
+- **Auto-reconnect** — exponential backoff with jitter; stops on graceful shutdown
+- **Subscription restore** — active channels are re-subscribed after every reconnect
+- **Heartbeats** — ping/pong keep-alive that detects stale connections and reconnects
+- **Typed end-to-end** — channel names, frame models, and errors
+- **Async-first** — built on `asyncio`; handlers may be sync or async
+
+## Requirements
+
+- Python >= 3.10
+
+## Install
+
+```bash
+uv add radion-sdk
+# or: pip install radion-sdk
+```
+
+## Quick start
+
+```python
+import asyncio
+import os
+
+from radion import Radion, Subscription
+
+
+async def main() -> None:
+    radion = Radion(api_key=os.getenv("RADION_API_KEY"))
+
+    await radion.realtime.connect()
+    await radion.realtime.subscribe(Subscription(id="trades", channel="trades"))
+
+    @radion.realtime.on("trades")
+    async def handle_trade(event):
+        print(event.id, event.channel, event.data)
+
+    await asyncio.sleep(60)
+    await radion.realtime.close()
+
+
+asyncio.run(main())
+```
+
+## Usage
+
+### Configuration
+
+```python
+Radion(api_key, *, base_url=..., ws_url=..., reconnect=True, heartbeat=True,
+       heartbeat_interval=15.0, heartbeat_timeout=10.0)
+```
+
+| Argument             | Type    | Default                   | Description                                       |
+| -------------------- | ------- | ------------------------- | ------------------------------------------------- |
+| `api_key`            | `str`   | —                         | **Required.** Sent as the `X-API-Key` header.     |
+| `base_url`           | `str`   | `https://api.radion.app`  | Base URL for the Radion API.                      |
+| `ws_url`             | `str`   | `wss://api.radion.app/ws` | Override the realtime endpoint.                   |
+| `reconnect`          | `bool`  | `True`                    | Auto-reconnect on unexpected disconnect.          |
+| `heartbeat`          | `bool`  | `True`                    | Enable heartbeats / stale detection.              |
+| `heartbeat_interval` | `float` | `15.0`                    | Seconds between pings.                            |
+| `heartbeat_timeout`  | `float` | `10.0`                    | Extra grace before a quiet connection is stale.   |
+
+Extra keyword arguments are forwarded to the realtime client.
+
+### Realtime client
+
+`radion.realtime` is a `RealtimeClient`. It can also be imported and
+constructed standalone:
+
+```python
+from radion import RealtimeClient
+
+client = RealtimeClient(api_key=os.getenv("RADION_API_KEY"))
+```
+
+| Method                          | Description                                                  |
+| ------------------------------- | ------------------------------------------------------------ |
+| `await connect()`               | Open the connection. Resolves once established.             |
+| `await subscribe(subscription)` | Subscribe with `Subscription(id, channel, filters)`. Replayed on reconnect.|
+| `await unsubscribe(id)`         | Unsubscribe by subscription id.                             |
+| `on(event)`                     | Decorator for a channel, `"event"` (all), or lifecycle handler. |
+| `off(event, handler=None)`      | Remove a handler (or all for that event).                   |
+| `await close(code=1000, ...)`   | Graceful shutdown. Stops reconnect attempts.                |
+| `connected`                     | Property — whether the socket is currently open.            |
+
+### Subscriptions & filters
+
+A subscription is `Subscription(id, channel, filters=None)`. The `id` is your
+own string, echoed back on every event so you can tell subscriptions apart;
+`channel` may carry a `mempool.` prefix. Some channels require a filter:
+
+```python
+from radion import ChannelFilters, Subscription
+
+await radion.realtime.subscribe(
+    Subscription(id="whales", channel="large_trades", filters=ChannelFilters(min_usd=10_000))
+)
+
+# "event" fires for every channel; the event carries id + channel + data.
+@radion.realtime.on("event")
+async def on_any(event):
+    print(event.id, event.channel, event.data)
+```
+
+`ChannelFilters`: `wallets`, `market_ids`, `token_ids`, `min_usd`.
+
+### Channels
+
+```
+global · trades · activity · lifecycle · oracle · collateral
+combos · prices · wallets · markets · large_trades
+```
+
+Available as the `CHANNELS` tuple and the `Channel` type.
+
+```python
+from radion import CHANNELS, Subscription
+
+for channel in CHANNELS:
+    await radion.realtime.subscribe(Subscription(id=channel, channel=channel))
+```
+
+### Lifecycle events
+
+```python
+@radion.realtime.on("open")
+async def opened(_):
+    print("connected")
+
+@radion.realtime.on("close")
+async def closed(info):
+    print(info["code"], info["reason"])
+
+@radion.realtime.on("reconnect")
+async def reconnecting(info):
+    print(info["attempt"], info["delay"])
+
+@radion.realtime.on("error")
+async def errored(err):
+    print(err)
+```
+
+### Reconnect & subscription restore
+
+On an unexpected disconnect the client reconnects with exponential backoff and
+re-sends every active subscription once the socket reopens. After `close()` no
+further attempts run.
+
+### Heartbeats
+
+A ping is sent every `heartbeat_interval` seconds. Any inbound frame counts as
+liveness; if the connection goes quiet past the timeout window it is terminated
+and reconnected.
+
+### Error handling
+
+```python
+from radion import RadionConnectionError, RadionServerError
+
+@radion.realtime.on("error")
+async def errored(err):
+    if isinstance(err, RadionServerError):
+        print("server error", err.code, err.channel)
+    elif isinstance(err, RadionConnectionError):
+        print("connection error", err)
+```
+
+A throwing consumer handler is reported via the `error` event and never retried.
+
+## License
+
+MIT

radion_sdk-0.2.0/README.md

@@ -0,0 +1,195 @@
+# radion-sdk
+
+[![PyPI version](https://img.shields.io/pypi/v/radion-sdk.svg)](https://pypi.org/project/radion-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/radion-sdk.svg)](https://pypi.org/project/radion-sdk/)
+[![license](https://img.shields.io/pypi/l/radion-sdk.svg)](./LICENSE)
+
+Official, async-first, fully-typed SDK for the [Radion](https://radion.app) platform.
+
+One client, one API key, every Radion product surface. Install `radion-sdk`; import it as `radion`.
+
+```python
+radion = Radion(api_key=os.getenv("RADION_API_KEY"))
+await radion.realtime.connect()
+await radion.realtime.subscribe(Subscription(id="trades", channel="trades"))
+
+@radion.realtime.on("trades")
+async def handle_trade(event):
+    print(event.id, event.data)
+```
+
+## Features
+
+- **Unified client** — `Radion(api_key=...)` is the single entry point for every product surface
+- **Auto-reconnect** — exponential backoff with jitter; stops on graceful shutdown
+- **Subscription restore** — active channels are re-subscribed after every reconnect
+- **Heartbeats** — ping/pong keep-alive that detects stale connections and reconnects
+- **Typed end-to-end** — channel names, frame models, and errors
+- **Async-first** — built on `asyncio`; handlers may be sync or async
+
+## Requirements
+
+- Python >= 3.10
+
+## Install
+
+```bash
+uv add radion-sdk
+# or: pip install radion-sdk
+```
+
+## Quick start
+
+```python
+import asyncio
+import os
+
+from radion import Radion, Subscription
+
+
+async def main() -> None:
+    radion = Radion(api_key=os.getenv("RADION_API_KEY"))
+
+    await radion.realtime.connect()
+    await radion.realtime.subscribe(Subscription(id="trades", channel="trades"))
+
+    @radion.realtime.on("trades")
+    async def handle_trade(event):
+        print(event.id, event.channel, event.data)
+
+    await asyncio.sleep(60)
+    await radion.realtime.close()
+
+
+asyncio.run(main())
+```
+
+## Usage
+
+### Configuration
+
+```python
+Radion(api_key, *, base_url=..., ws_url=..., reconnect=True, heartbeat=True,
+       heartbeat_interval=15.0, heartbeat_timeout=10.0)
+```
+
+| Argument             | Type    | Default                   | Description                                       |
+| -------------------- | ------- | ------------------------- | ------------------------------------------------- |
+| `api_key`            | `str`   | —                         | **Required.** Sent as the `X-API-Key` header.     |
+| `base_url`           | `str`   | `https://api.radion.app`  | Base URL for the Radion API.                      |
+| `ws_url`             | `str`   | `wss://api.radion.app/ws` | Override the realtime endpoint.                   |
+| `reconnect`          | `bool`  | `True`                    | Auto-reconnect on unexpected disconnect.          |
+| `heartbeat`          | `bool`  | `True`                    | Enable heartbeats / stale detection.              |
+| `heartbeat_interval` | `float` | `15.0`                    | Seconds between pings.                            |
+| `heartbeat_timeout`  | `float` | `10.0`                    | Extra grace before a quiet connection is stale.   |
+
+Extra keyword arguments are forwarded to the realtime client.
+
+### Realtime client
+
+`radion.realtime` is a `RealtimeClient`. It can also be imported and
+constructed standalone:
+
+```python
+from radion import RealtimeClient
+
+client = RealtimeClient(api_key=os.getenv("RADION_API_KEY"))
+```
+
+| Method                          | Description                                                  |
+| ------------------------------- | ------------------------------------------------------------ |
+| `await connect()`               | Open the connection. Resolves once established.             |
+| `await subscribe(subscription)` | Subscribe with `Subscription(id, channel, filters)`. Replayed on reconnect.|
+| `await unsubscribe(id)`         | Unsubscribe by subscription id.                             |
+| `on(event)`                     | Decorator for a channel, `"event"` (all), or lifecycle handler. |
+| `off(event, handler=None)`      | Remove a handler (or all for that event).                   |
+| `await close(code=1000, ...)`   | Graceful shutdown. Stops reconnect attempts.                |
+| `connected`                     | Property — whether the socket is currently open.            |
+
+### Subscriptions & filters
+
+A subscription is `Subscription(id, channel, filters=None)`. The `id` is your
+own string, echoed back on every event so you can tell subscriptions apart;
+`channel` may carry a `mempool.` prefix. Some channels require a filter:
+
+```python
+from radion import ChannelFilters, Subscription
+
+await radion.realtime.subscribe(
+    Subscription(id="whales", channel="large_trades", filters=ChannelFilters(min_usd=10_000))
+)
+
+# "event" fires for every channel; the event carries id + channel + data.
+@radion.realtime.on("event")
+async def on_any(event):
+    print(event.id, event.channel, event.data)
+```
+
+`ChannelFilters`: `wallets`, `market_ids`, `token_ids`, `min_usd`.
+
+### Channels
+
+```
+global · trades · activity · lifecycle · oracle · collateral
+combos · prices · wallets · markets · large_trades
+```
+
+Available as the `CHANNELS` tuple and the `Channel` type.
+
+```python
+from radion import CHANNELS, Subscription
+
+for channel in CHANNELS:
+    await radion.realtime.subscribe(Subscription(id=channel, channel=channel))
+```
+
+### Lifecycle events
+
+```python
+@radion.realtime.on("open")
+async def opened(_):
+    print("connected")
+
+@radion.realtime.on("close")
+async def closed(info):
+    print(info["code"], info["reason"])
+
+@radion.realtime.on("reconnect")
+async def reconnecting(info):
+    print(info["attempt"], info["delay"])
+
+@radion.realtime.on("error")
+async def errored(err):
+    print(err)
+```
+
+### Reconnect & subscription restore
+
+On an unexpected disconnect the client reconnects with exponential backoff and
+re-sends every active subscription once the socket reopens. After `close()` no
+further attempts run.
+
+### Heartbeats
+
+A ping is sent every `heartbeat_interval` seconds. Any inbound frame counts as
+liveness; if the connection goes quiet past the timeout window it is terminated
+and reconnected.
+
+### Error handling
+
+```python
+from radion import RadionConnectionError, RadionServerError
+
+@radion.realtime.on("error")
+async def errored(err):
+    if isinstance(err, RadionServerError):
+        print("server error", err.code, err.channel)
+    elif isinstance(err, RadionConnectionError):
+        print("connection error", err)
+```
+
+A throwing consumer handler is reported via the `error` event and never retried.
+
+## License
+
+MIT

radion_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "radion-sdk"
+version = "0.2.0"
+description = "Official async SDK for the Radion platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["radion", "sdk", "realtime", "websocket", "async", "polymarket"]
+dependencies = ["websockets>=13.0", "msgspec>=0.18.0"]
+
+[project.optional-dependencies]
+dev = ["ruff>=0.8.0", "ty>=0.0.1a1"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/radion"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "SIM", "RUF"]
+
+[tool.ty.environment]
+root = ["./src"]

radion_sdk-0.2.0/src/radion/__init__.py

@@ -0,0 +1,85 @@
+"""Official async SDK for the Radion platform."""
+
+from __future__ import annotations
+
+from ._config import DEFAULT_BASE_URL, DEFAULT_WS_URL, RadionConfig
+from .client import Radion
+from .errors import RadionConnectionError, RadionError, RadionServerError
+from .realtime import (
+    CHANNELS,
+    FILTER_REQUIREMENTS,
+    ActivityPayload,
+    AnyChannelPayload,
+    AnyConfirmedPayload,
+    Channel,
+    ChannelEvent,
+    ChannelFilters,
+    CollateralPayload,
+    CombosPayload,
+    ErrorFrame,
+    EventDispatcher,
+    EventFrame,
+    FilterKey,
+    InboundFrame,
+    LifecyclePayload,
+    MempoolChannel,
+    OraclePayload,
+    PongFrame,
+    PricesPayload,
+    RealtimeClient,
+    ReconnectManager,
+    SubscribableChannel,
+    SubscribedFrame,
+    Subscription,
+    SubscriptionManager,
+    TradesPayload,
+    UnsubscribedFrame,
+    is_channel,
+    is_mempool_channel,
+    is_subscribable_channel,
+    validate_subscription_filters,
+)
+
+__all__ = [
+    "CHANNELS",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_WS_URL",
+    "FILTER_REQUIREMENTS",
+    "ActivityPayload",
+    "AnyChannelPayload",
+    "AnyConfirmedPayload",
+    "Channel",
+    "ChannelEvent",
+    "ChannelFilters",
+    "CollateralPayload",
+    "CombosPayload",
+    "ErrorFrame",
+    "EventDispatcher",
+    "EventFrame",
+    "FilterKey",
+    "InboundFrame",
+    "LifecyclePayload",
+    "MempoolChannel",
+    "OraclePayload",
+    "PongFrame",
+    "PricesPayload",
+    "Radion",
+    "RadionConfig",
+    "RadionConnectionError",
+    "RadionError",
+    "RadionServerError",
+    "RealtimeClient",
+    "ReconnectManager",
+    "SubscribableChannel",
+    "SubscribedFrame",
+    "Subscription",
+    "SubscriptionManager",
+    "TradesPayload",
+    "UnsubscribedFrame",
+    "is_channel",
+    "is_mempool_channel",
+    "is_subscribable_channel",
+    "validate_subscription_filters",
+]
+
+__version__ = "0.2.0"

radion_sdk-0.2.0/src/radion/_config.py

@@ -0,0 +1,25 @@
+"""Shared configuration for the Radion SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "https://api.radion.app"
+"""Default base URL for the Radion REST API."""
+
+DEFAULT_WS_URL = "wss://api.radion.app/ws"
+"""Default endpoint for the Radion realtime (WebSocket) API."""
+
+
+@dataclass(frozen=True, slots=True)
+class RadionConfig:
+    """Shared configuration for every Radion product surface.
+
+    ``base_url`` is reserved for the forthcoming REST resource namespaces
+    (``markets``, ``traders``, ``backtests``, …); the realtime client uses
+    ``ws_url``.
+    """
+
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+    ws_url: str = DEFAULT_WS_URL

radion_sdk-0.2.0/src/radion/client.py

@@ -0,0 +1,50 @@
+"""The unified :class:`Radion` platform client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._config import DEFAULT_BASE_URL, DEFAULT_WS_URL
+from .errors import RadionConnectionError
+from .realtime import RealtimeClient
+
+
+class Radion:
+    """Unified async entry point for the Radion platform.
+
+    Holds shared configuration and exposes each product surface as an
+    attribute. Today that is :attr:`realtime`; REST resource namespaces
+    (``markets``, ``traders``, ``backtests``, ``auth``, ``health``) attach here
+    as they ship, built from ``base_url`` over a shared HTTP transport — the
+    constructor shape stays stable so adding them is purely additive.
+
+    Extra keyword arguments are forwarded to the realtime client (for example
+    ``reconnect``, ``heartbeat``, ``heartbeat_interval``).
+
+    Example::
+
+        radion = Radion(api_key=os.getenv("RADION_API_KEY"))
+        await radion.realtime.connect()
+        await radion.realtime.subscribe("trades")
+
+        @radion.realtime.on("trades")
+        async def handle_trade(event):
+            print(event.data)
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        ws_url: str = DEFAULT_WS_URL,
+        **realtime_options: Any,
+    ) -> None:
+        if not api_key:
+            raise RadionConnectionError("api_key is required")
+        self._base_url = base_url
+        self.realtime = RealtimeClient(
+            api_key=api_key,
+            url=ws_url,
+            **realtime_options,
+        )

radion_sdk-0.2.0/src/radion/errors.py

@@ -0,0 +1,28 @@
+"""Error types raised by the SDK."""
+
+from __future__ import annotations
+
+
+class RadionError(Exception):
+    """Base class for every error surfaced by the SDK."""
+
+
+class RadionConnectionError(RadionError):
+    """Raised when the SDK is used against an invalid connection state."""
+
+
+class RadionServerError(RadionError):
+    """Raised when the server reports an ``error`` frame."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        channel: str | None = None,
+        id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.channel = channel
+        self.id = id