anaxer 0.1.0__tar.gz

anaxer-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+*.whl
+*.tar.gz

anaxer-0.1.0/LICENSE

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

anaxer-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: anaxer
+Version: 0.1.0
+Summary: Official Python SDK for the Anaxer Solana real-time data API.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Requires-Dist: websockets<14,>=12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# anaxer
+
+Official Python SDK for the [Anaxer](https://anaxer.com) Solana real-time data API.
+
+```bash
+pip install anaxer
+```
+
+Requires Python 3.10+.
+
+## Quickstart — async streaming
+
+```python
+import asyncio
+import anaxer
+
+async def main():
+    async with anaxer.connect(api_key="...") as client:
+        # Plan limits from the server `connected` frame
+        print(client.connected.connections_per_stream)
+
+        async with client.stream("creations", exclude_mayhem=True) as sub:
+            async for event in sub:
+                print("new launch:", event.symbol, event.mint)
+                break
+
+asyncio.run(main())
+```
+
+`stream()` returns a `Subscription[T]` handle (async-iterable + async context manager).
+Prefer `async with client.stream(...) as sub:` so leaving the block always sends
+`unsubscribe`. Bare `async for` / `break` also unsubscribes (via `GeneratorExit`).
+
+### Channels
+
+| Channel | Yields | Filters (keyword-only, snake_case) |
+|---|---|---|
+| `trades` | `SwapV1` | `sources`, `mints`, `wallets`, `min_volume_usd`, `max_volume_usd`, `sol_only` |
+| `creations` | `CreatedV1` | `sources`, `enriched`, `exclude_mayhem` |
+| `graduations` | `GraduatedV1` | `sources`, `exclude_mayhem`, `min_liquidity_sol` |
+| `prices` | `PriceUpdateV1` | `sources`, `mints` |
+
+`transfers` is not wired in v1 (server ingestion deferred). `TransferV1` is still
+exported as a type.
+
+### Side-channel errors
+
+Reconnect-triggering / non-fatal codes (e.g. `slow_consumer`) are delivered on
+`client.on_error(callback)` and/or `async for err in client.errors` — they never
+interrupt an open `Subscription`'s `async for`. Subscription-fatal codes
+(`invalid_filters`, …) raise from that subscription only. `unauthorized` is
+terminal.
+
+## Quickstart — sync REST
+
+```python
+from anaxer import Client
+
+client = Client(api_key="...")
+price = client.tokens.price("3PFaeFMXiRVYueDCnHHSKndKDDpKZhbhFjQ13JXYpump")
+print(price.price.usd)
+client.close()
+```
+
+`Client` is REST-only — it has no `stream()` method. Use it when you do not want a
+WebSocket. `AsyncClient` (from `anaxer.connect`) also exposes the same REST surface
+via `await`.
+
+### REST surface
+
+- `tokens.get` / `batch` / `price` / `batch_price` / `trades`
+- `creations` / `iter_creations`
+- `graduations` / `iter_graduations`
+- `iter_trades(mint, ...)`
+- `launchpads.stats`
+
+`programs()` is omitted in v1 (response type not in the public schemas).
+
+List endpoints return a `Page` (`data`, `next`, `window`). Use `iter_*` to walk
+`next` across pages. Wire field `from` is exposed in Python as `from_`
+(reserved word) with a Pydantic alias so round-trips keep the wire key.
+
+Auth is always `Authorization: Bearer <api_key>` (same as the TypeScript SDK).
+
+## No gap recovery in v1
+
+The WebSocket protocol has no sequence/cursor. After a disconnect the client
+reconnects and re-subscribes, but events during the gap are not replayed.
+
+## Config
+
+```python
+from anaxer import Reconnect, connect
+
+async with connect(
+    api_key="...",
+    base_url="https://api.anaxer.com",  # local: http://localhost:3010
+    reconnect=Reconnect(base_delay=0.5, max_delay=30.0, max_retries=None),
+    heartbeat_interval=15.0,  # 0 disables
+    rest_max_retries=2,
+) as client:
+    ...
+```
+
+## Errors
+
+All failures surface as `anaxer.AnaxerError` with `.code`, `.message`, `.status`
+(HTTP only), and `.subscription_id` (subscription-fatal WS errors only).
+
+SDK-local codes: `connection_closed`, `timeout`, `invalid_payload` (client-side
+parse failure — distinct from the wire's `invalid_message`).
+
+## Links
+
+- Wire contracts: [`docs/api/ws-v1.md`](../../docs/api/ws-v1.md), [`docs/api/rest-v1.md`](../../docs/api/rest-v1.md)
+- System doc: [`docs/system/sdk-py.md`](../../docs/system/sdk-py.md)
+- TypeScript sibling: [`@anaxer/sdk`](../../packages/sdk/README.md)

anaxer-0.1.0/README.md

@@ -0,0 +1,117 @@
+# anaxer
+
+Official Python SDK for the [Anaxer](https://anaxer.com) Solana real-time data API.
+
+```bash
+pip install anaxer
+```
+
+Requires Python 3.10+.
+
+## Quickstart — async streaming
+
+```python
+import asyncio
+import anaxer
+
+async def main():
+    async with anaxer.connect(api_key="...") as client:
+        # Plan limits from the server `connected` frame
+        print(client.connected.connections_per_stream)
+
+        async with client.stream("creations", exclude_mayhem=True) as sub:
+            async for event in sub:
+                print("new launch:", event.symbol, event.mint)
+                break
+
+asyncio.run(main())
+```
+
+`stream()` returns a `Subscription[T]` handle (async-iterable + async context manager).
+Prefer `async with client.stream(...) as sub:` so leaving the block always sends
+`unsubscribe`. Bare `async for` / `break` also unsubscribes (via `GeneratorExit`).
+
+### Channels
+
+| Channel | Yields | Filters (keyword-only, snake_case) |
+|---|---|---|
+| `trades` | `SwapV1` | `sources`, `mints`, `wallets`, `min_volume_usd`, `max_volume_usd`, `sol_only` |
+| `creations` | `CreatedV1` | `sources`, `enriched`, `exclude_mayhem` |
+| `graduations` | `GraduatedV1` | `sources`, `exclude_mayhem`, `min_liquidity_sol` |
+| `prices` | `PriceUpdateV1` | `sources`, `mints` |
+
+`transfers` is not wired in v1 (server ingestion deferred). `TransferV1` is still
+exported as a type.
+
+### Side-channel errors
+
+Reconnect-triggering / non-fatal codes (e.g. `slow_consumer`) are delivered on
+`client.on_error(callback)` and/or `async for err in client.errors` — they never
+interrupt an open `Subscription`'s `async for`. Subscription-fatal codes
+(`invalid_filters`, …) raise from that subscription only. `unauthorized` is
+terminal.
+
+## Quickstart — sync REST
+
+```python
+from anaxer import Client
+
+client = Client(api_key="...")
+price = client.tokens.price("3PFaeFMXiRVYueDCnHHSKndKDDpKZhbhFjQ13JXYpump")
+print(price.price.usd)
+client.close()
+```
+
+`Client` is REST-only — it has no `stream()` method. Use it when you do not want a
+WebSocket. `AsyncClient` (from `anaxer.connect`) also exposes the same REST surface
+via `await`.
+
+### REST surface
+
+- `tokens.get` / `batch` / `price` / `batch_price` / `trades`
+- `creations` / `iter_creations`
+- `graduations` / `iter_graduations`
+- `iter_trades(mint, ...)`
+- `launchpads.stats`
+
+`programs()` is omitted in v1 (response type not in the public schemas).
+
+List endpoints return a `Page` (`data`, `next`, `window`). Use `iter_*` to walk
+`next` across pages. Wire field `from` is exposed in Python as `from_`
+(reserved word) with a Pydantic alias so round-trips keep the wire key.
+
+Auth is always `Authorization: Bearer <api_key>` (same as the TypeScript SDK).
+
+## No gap recovery in v1
+
+The WebSocket protocol has no sequence/cursor. After a disconnect the client
+reconnects and re-subscribes, but events during the gap are not replayed.
+
+## Config
+
+```python
+from anaxer import Reconnect, connect
+
+async with connect(
+    api_key="...",
+    base_url="https://api.anaxer.com",  # local: http://localhost:3010
+    reconnect=Reconnect(base_delay=0.5, max_delay=30.0, max_retries=None),
+    heartbeat_interval=15.0,  # 0 disables
+    rest_max_retries=2,
+) as client:
+    ...
+```
+
+## Errors
+
+All failures surface as `anaxer.AnaxerError` with `.code`, `.message`, `.status`
+(HTTP only), and `.subscription_id` (subscription-fatal WS errors only).
+
+SDK-local codes: `connection_closed`, `timeout`, `invalid_payload` (client-side
+parse failure — distinct from the wire's `invalid_message`).
+
+## Links
+
+- Wire contracts: [`docs/api/ws-v1.md`](../../docs/api/ws-v1.md), [`docs/api/rest-v1.md`](../../docs/api/rest-v1.md)
+- System doc: [`docs/system/sdk-py.md`](../../docs/system/sdk-py.md)
+- TypeScript sibling: [`@anaxer/sdk`](../../packages/sdk/README.md)

anaxer-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "anaxer"
+version = "0.1.0"
+description = "Official Python SDK for the Anaxer Solana real-time data API."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = [
+    "websockets>=12,<14",
+    "httpx>=0.27",
+    "pydantic>=2.6",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.9",
+    "ruff>=0.4",
+    "build>=1.2",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/anaxer"]
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
+packages = ["anaxer"]
+plugins = ["pydantic.mypy"]
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+module = "websockets.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = [
+    "test_ws",
+    "test_reconnect",
+    "test_rest",
+    "test_contract_examples",
+    "test_models_compat",
+    "mock_ws",
+]
+disallow_untyped_defs = false
+check_untyped_defs = false
+allow_untyped_defs = true
+disable_error_code = ["type-arg", "no-untyped-def"]
+
+# test_types.py intentionally uses type: ignore on negative cases — keep it under
+# strict + warn_unused_ignores (do not loosen this module).
+
+[tool.ruff]
+line-length = 100
+src = ["src", "test"]
+
+[tool.ruff.lint]
+ignore = ["S110", "PYI034"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["test"]
+pythonpath = ["src"]

anaxer-0.1.0/scripts/assert_wheel_deps.py

@@ -0,0 +1,37 @@
+"""Assert built wheel runtime Requires-Dist is exactly websockets/httpx/pydantic."""
+
+from __future__ import annotations
+
+import glob
+import re
+import sys
+import zipfile
+
+
+def main() -> int:
+    wheels = sorted(glob.glob("dist/*.whl"))
+    if not wheels:
+        print("no wheel in dist/", file=sys.stderr)
+        return 1
+    wheel = wheels[-1]
+    zf = zipfile.ZipFile(wheel)
+    meta_name = next(n for n in zf.namelist() if n.endswith("METADATA"))
+    meta = zf.read(meta_name).decode()
+    deps: set[str] = set()
+    for line in meta.splitlines():
+        if not line.startswith("Requires-Dist:"):
+            continue
+        if "extra ==" in line:
+            continue
+        rest = line.split(":", 1)[1].strip()
+        deps.add(re.split(r"[><=!~; ]", rest)[0])
+    expected = {"websockets", "httpx", "pydantic"}
+    if deps != expected:
+        print(f"expected {expected}, got {deps}", file=sys.stderr)
+        return 1
+    print("OK", deps)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

anaxer-0.1.0/src/anaxer/__init__.py

@@ -0,0 +1,46 @@
+"""Official Python SDK for the Anaxer Solana real-time data API."""
+
+from anaxer._client_async import AsyncClient
+from anaxer._client_sync import Client
+from anaxer._config import Reconnect
+from anaxer._connect import connect
+from anaxer.errors import AnaxerError, AnaxerErrorCode
+from anaxer.models import (
+    WIRE_VERSION,
+    ConnectedInfo,
+    CreatedV1,
+    GraduatedV1,
+    LaunchpadStatsV1,
+    PriceUpdateV1,
+    SubscriptionFiltersV1,
+    SwapV1,
+    TokenMetadataV1,
+    TransferV1,
+    Window,
+)
+from anaxer.rest._pagination import Page
+from anaxer.ws._subscription import Subscription
+
+__all__ = [
+    "WIRE_VERSION",
+    "AnaxerError",
+    "AnaxerErrorCode",
+    "AsyncClient",
+    "Client",
+    "ConnectedInfo",
+    "CreatedV1",
+    "GraduatedV1",
+    "LaunchpadStatsV1",
+    "Page",
+    "PriceUpdateV1",
+    "Reconnect",
+    "Subscription",
+    "SubscriptionFiltersV1",
+    "SwapV1",
+    "TokenMetadataV1",
+    "TransferV1",
+    "Window",
+    "connect",
+]
+
+__version__ = "0.1.0"

anaxer-0.1.0/src/anaxer/_client_async.py

@@ -0,0 +1,175 @@
+"""AsyncClient: eager WS + REST namespaces."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from typing import Any, Literal, overload
+
+from anaxer._config import ClientConfig
+from anaxer.errors import AnaxerError
+from anaxer.models import (
+    ConnectedInfo,
+    CreatedV1,
+    GraduatedV1,
+    PriceUpdateV1,
+    SubscriptionFiltersV1,
+    SwapV1,
+)
+from anaxer.rest._endpoints import (
+    LaunchpadsAsyncApi,
+    TokensAsyncApi,
+    async_creations,
+    async_graduations,
+    iter_creations_async,
+    iter_graduations_async,
+    iter_trades_async,
+)
+from anaxer.rest._http import AsyncHttpClient
+from anaxer.rest._pagination import Page
+from anaxer.ws._connection import ErrorHub, WsConnection
+from anaxer.ws._subscription import Subscription
+
+
+class _ErrorsAsyncIterator:
+    def __init__(self, hub: ErrorHub) -> None:
+        self._q = hub.subscribe()
+
+    def __aiter__(self) -> _ErrorsAsyncIterator:
+        return self
+
+    async def __anext__(self) -> AnaxerError:
+        item = await self._q.get()
+        if item is None:
+            raise StopAsyncIteration
+        return item
+
+
+class AsyncClient:
+    def __init__(
+        self,
+        config: ClientConfig,
+        *,
+        http_transport: Any = None,
+        open_transport_fn: Any = None,
+    ) -> None:
+        self._config = config
+        self._error_hub = ErrorHub()
+        self._conn = WsConnection(
+            config, self._error_hub, open_transport_fn=open_transport_fn
+        )
+        self._http = AsyncHttpClient(
+            base_url=config.base_url,
+            api_key=config.api_key,
+            max_retries=config.rest_max_retries,
+            transport=http_transport,
+        )
+        self.tokens = TokensAsyncApi(self._http)
+        self.launchpads = LaunchpadsAsyncApi(self._http)
+        self._entered = False
+
+    @property
+    def connected(self) -> ConnectedInfo:
+        info = self._conn.connected
+        if info is None:
+            raise AnaxerError("connection_closed", "Client is not connected")
+        return info
+
+    @property
+    def errors(self) -> AsyncIterator[AnaxerError]:
+        """Side-channel errors. Each access returns a new subscriber iterator."""
+        return _ErrorsAsyncIterator(self._error_hub)
+
+    def on_error(self, callback: Callable[[AnaxerError], None]) -> None:
+        self._error_hub.on_error(callback)
+
+    async def __aenter__(self) -> AsyncClient:
+        await self._conn.open()
+        self._entered = True
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._conn.close()
+        await self._http.aclose()
+        self._entered = False
+
+    @overload
+    def stream(
+        self,
+        channel: Literal["trades"],
+        *,
+        sources: list[str] | None = None,
+        mints: list[str] | None = None,
+        wallets: list[str] | None = None,
+        min_volume_usd: float | None = None,
+        max_volume_usd: float | None = None,
+        sol_only: bool | None = None,
+    ) -> Subscription[SwapV1]: ...
+
+    @overload
+    def stream(
+        self,
+        channel: Literal["creations"],
+        *,
+        sources: list[str] | None = None,
+        enriched: bool | None = None,
+        exclude_mayhem: bool | None = None,
+    ) -> Subscription[CreatedV1]: ...
+
+    @overload
+    def stream(
+        self,
+        channel: Literal["graduations"],
+        *,
+        sources: list[str] | None = None,
+        exclude_mayhem: bool | None = None,
+        min_liquidity_sol: float | None = None,
+    ) -> Subscription[GraduatedV1]: ...
+
+    @overload
+    def stream(
+        self,
+        channel: Literal["prices"],
+        *,
+        sources: list[str] | None = None,
+        mints: list[str] | None = None,
+    ) -> Subscription[PriceUpdateV1]: ...
+
+    def stream(self, channel: str, **filters: Any) -> Subscription[Any]:
+        if not self._entered and self._conn.state != "open":
+            # Allow stream() only after successful __aenter__ (eager open).
+            raise AnaxerError(
+                "connection_closed",
+                "Call stream() inside `async with anaxer.connect(...)`",
+            )
+        model = SubscriptionFiltersV1.model_validate(
+            {
+                "sources": filters.get("sources"),
+                "mints": filters.get("mints"),
+                "wallets": filters.get("wallets"),
+                "minVolumeUsd": filters.get("min_volume_usd"),
+                "maxVolumeUsd": filters.get("max_volume_usd"),
+                "enriched": filters.get("enriched"),
+                "excludeMayhem": filters.get("exclude_mayhem"),
+                "minLiquiditySol": filters.get("min_liquidity_sol"),
+                "solOnly": filters.get("sol_only"),
+            }
+        )
+        return self._conn.stream(channel, model)  # type: ignore[arg-type]
+
+    async def creations(self, **opts: Any) -> Page[CreatedV1]:
+        return await async_creations(self._http, **opts)
+
+    def iter_creations(self, **opts: Any) -> AsyncIterator[CreatedV1]:
+        return iter_creations_async(self._http, **opts)
+
+    async def graduations(self, **opts: Any) -> Page[GraduatedV1]:
+        return await async_graduations(self._http, **opts)
+
+    def iter_graduations(self, **opts: Any) -> AsyncIterator[GraduatedV1]:
+        return iter_graduations_async(self._http, **opts)
+
+    def iter_trades(self, mint: str, **opts: Any) -> AsyncIterator[SwapV1]:
+        return iter_trades_async(self._http, mint, **opts)

anaxer-0.1.0/src/anaxer/_client_sync.py

@@ -0,0 +1,62 @@
+"""Sync Client — REST only."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from anaxer.models import CreatedV1, GraduatedV1, SwapV1
+from anaxer.rest._endpoints import (
+    LaunchpadsApi,
+    TokensApi,
+    iter_creations_sync,
+    iter_graduations_sync,
+    iter_trades_sync,
+    sync_creations,
+    sync_graduations,
+)
+from anaxer.rest._http import SyncHttpClient
+from anaxer.rest._pagination import Page
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.anaxer.com",
+        rest_max_retries: int = 2,
+        http_transport: Any = None,
+    ) -> None:
+        self._http = SyncHttpClient(
+            base_url=base_url,
+            api_key=api_key,
+            max_retries=rest_max_retries,
+            transport=http_transport,
+        )
+        self.tokens = TokensApi(self._http)
+        self.launchpads = LaunchpadsApi(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def creations(self, **opts: Any) -> Page[CreatedV1]:
+        return sync_creations(self._http, **opts)
+
+    def iter_creations(self, **opts: Any) -> Iterator[CreatedV1]:
+        return iter_creations_sync(self._http, **opts)
+
+    def graduations(self, **opts: Any) -> Page[GraduatedV1]:
+        return sync_graduations(self._http, **opts)
+
+    def iter_graduations(self, **opts: Any) -> Iterator[GraduatedV1]:
+        return iter_graduations_sync(self._http, **opts)
+
+    def iter_trades(self, mint: str, **opts: Any) -> Iterator[SwapV1]:
+        return iter_trades_sync(self._http, mint, **opts)