pyth-hermes 0.1.0__py3-none-any.whl

pyth_hermes/__init__.py

@@ -0,0 +1,31 @@
+"""pyth-hermes: a Python client for the Pyth Network Hermes price-oracle API."""
+
+from __future__ import annotations
+
+from pyth_hermes.async_client import AsyncHermesClient
+from pyth_hermes.client import HermesClient
+from pyth_hermes.models import (
+    BinaryUpdate,
+    FeedAttributes,
+    ParsedPriceUpdate,
+    PriceFeed,
+    PriceFeedMetadata,
+    PriceUpdateResponse,
+    RpcPrice,
+    price_to_decimal,
+)
+
+__all__ = [
+    "AsyncHermesClient",
+    "BinaryUpdate",
+    "FeedAttributes",
+    "HermesClient",
+    "ParsedPriceUpdate",
+    "PriceFeed",
+    "PriceFeedMetadata",
+    "PriceUpdateResponse",
+    "RpcPrice",
+    "price_to_decimal",
+]
+
+__version__ = "0.1.0"

pyth_hermes/_config.py

@@ -0,0 +1,97 @@
+"""Shared configuration, constants and retry helpers."""
+
+from __future__ import annotations
+
+import random
+import warnings
+from dataclasses import dataclass
+from typing import Optional
+
+import httpx
+
+PRODUCTION_URL = "https://hermes.pyth.network"
+BETA_URL = "https://hermes-beta.pyth.network"
+
+#: Sentinel for ``base_url`` so we can tell "left at default" from "explicitly
+#: passed" (needed to warn when an injected client makes base_url a no-op).
+_BASE_URL_UNSET = "\x00__pyth_hermes_base_url_unset__"
+
+
+def warn_if_base_url_ignored(base_url: str, client_injected: bool) -> None:
+    """Warn when an explicit ``base_url`` cannot take effect.
+
+    Auth headers are applied per-request and so are honored even with a
+    caller-supplied httpx client, but the request URL is resolved against that
+    client's own ``base_url``. Passing both an explicit ``base_url`` and a
+    ``client`` therefore silently drops the former; make that loud instead.
+    """
+    if client_injected and base_url is not _BASE_URL_UNSET:
+        warnings.warn(
+            "base_url is ignored when a custom httpx client is supplied; the "
+            "request host is taken from the injected client. Set base_url on "
+            "the client itself (httpx.Client(base_url=...)) or omit the client.",
+            UserWarning,
+            stacklevel=3,
+        )
+
+
+def resolve_base_url(base_url: str) -> str:
+    """Map the sentinel back to the production default."""
+    return PRODUCTION_URL if base_url is _BASE_URL_UNSET else base_url
+
+
+# Rate limit: 10 requests / 10s per IP; exceeding -> HTTP 429 for the next 60s.
+RATE_LIMIT_WINDOW_SECONDS = 60.0
+
+#: Status codes worth retrying. 429 is rate limiting; 5xx are transient.
+RETRY_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Connection + retry settings shared by the sync and async clients."""
+
+    base_url: str = PRODUCTION_URL
+    api_key: Optional[str] = None
+    api_key_header: str = "Authorization"
+    api_key_scheme: str = "Bearer"
+    timeout: float = 30.0
+    max_retries: int = 3
+    backoff_base: float = 1.0
+    backoff_cap: float = 60.0
+
+    def normalized_base_url(self) -> str:
+        return self.base_url.rstrip("/")
+
+    def auth_headers(self) -> dict[str, str]:
+        if not self.api_key:
+            return {}
+        value = (
+            f"{self.api_key_scheme} {self.api_key}".strip() if self.api_key_scheme else self.api_key
+        )
+        return {self.api_key_header: value}
+
+
+def retry_delay(attempt: int, response: Optional[httpx.Response], config: ClientConfig) -> float:
+    """Compute how long to sleep before the next attempt.
+
+    Honors a ``Retry-After`` header when present (cap-limited), otherwise uses
+    exponential backoff with full jitter. For 429 responses without a header we
+    do not exceed the 60s rate-limit window per delay.
+    """
+    if response is not None and "Retry-After" in response.headers:
+        try:
+            # Clamp to >= 0: a negative Retry-After would make time.sleep() raise.
+            return max(0.0, min(float(response.headers["Retry-After"]), config.backoff_cap))
+        except ValueError:
+            pass
+
+    exp = config.backoff_base * (2**attempt)
+    cap = config.backoff_cap
+    if response is not None and response.status_code == 429:
+        cap = min(cap, RATE_LIMIT_WINDOW_SECONDS)
+    return min(cap, random.uniform(0, exp)) if exp > 0 else 0.0
+
+
+def should_retry(response: httpx.Response) -> bool:
+    return response.status_code in RETRY_STATUS_CODES

pyth_hermes/async_client.py

@@ -0,0 +1,189 @@
+"""Asynchronous Pyth Hermes client with SSE price streaming."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from decimal import Decimal
+from types import TracebackType
+from typing import Any, Optional
+
+import httpx
+from httpx_sse import aconnect_sse
+
+from pyth_hermes._config import (
+    _BASE_URL_UNSET,
+    ClientConfig,
+    resolve_base_url,
+    retry_delay,
+    should_retry,
+    warn_if_base_url_ignored,
+)
+from pyth_hermes.client import _price_params
+from pyth_hermes.models import PriceFeed, PriceUpdateResponse
+
+
+class AsyncHermesClient:
+    """Asynchronous client for the Pyth Network Hermes API.
+
+    Adds :meth:`stream_prices`, an async iterator over the SSE price stream
+    with automatic reconnect + backoff. Mirrors :class:`HermesClient` for the
+    request/response endpoints.
+    """
+
+    def __init__(
+        self,
+        base_url: str = _BASE_URL_UNSET,
+        *,
+        api_key: Optional[str] = None,
+        api_key_header: str = "Authorization",
+        api_key_scheme: str = "Bearer",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        backoff_base: float = 1.0,
+        backoff_cap: float = 60.0,
+        client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        warn_if_base_url_ignored(base_url, client is not None)
+        self._config = ClientConfig(
+            base_url=resolve_base_url(base_url),
+            api_key=api_key,
+            api_key_header=api_key_header,
+            api_key_scheme=api_key_scheme,
+            timeout=timeout,
+            max_retries=max_retries,
+            backoff_base=backoff_base,
+            backoff_cap=backoff_cap,
+        )
+        self._http = client or httpx.AsyncClient(
+            base_url=self._config.normalized_base_url(), timeout=timeout
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._config.normalized_base_url()
+
+    def _auth_headers(self) -> dict[str, str]:
+        return self._config.auth_headers()
+
+    async def __aenter__(self) -> AsyncHermesClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _request(self, method: str, path: str, *, params: Any = None) -> httpx.Response:
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = await self._http.request(
+                    method, path, params=params, headers=self._auth_headers()
+                )
+            except httpx.TransportError:
+                if attempt >= self._config.max_retries:
+                    raise
+                await asyncio.sleep(retry_delay(attempt, None, self._config))
+                continue
+
+            if should_retry(response) and attempt < self._config.max_retries:
+                await asyncio.sleep(retry_delay(attempt, response, self._config))
+                continue
+            response.raise_for_status()
+            return response
+
+        raise RuntimeError("unreachable")  # pragma: no cover
+
+    async def list_price_feeds(
+        self, *, query: Optional[str] = None, asset_type: Optional[str] = None
+    ) -> list[PriceFeed]:
+        params: dict[str, str] = {}
+        if query is not None:
+            params["query"] = query
+        if asset_type is not None:
+            params["asset_type"] = asset_type
+        response = await self._request("GET", "/v2/price_feeds", params=params)
+        return [PriceFeed.model_validate(item) for item in response.json()]
+
+    async def get_feed_id(self, symbol: str) -> Optional[str]:
+        """Resolve a canonical feed id by EXACT ``attributes.symbol`` match."""
+        feeds = await self.list_price_feeds(query=symbol)
+        for feed in feeds:
+            if feed.symbol == symbol:
+                return feed.id
+        return None
+
+    async def get_latest_price(
+        self, ids: list[str], *, parsed: bool = True, encoding: str = "hex"
+    ) -> PriceUpdateResponse:
+        params = _price_params(ids, parsed=parsed, encoding=encoding)
+        response = await self._request("GET", "/v2/updates/price/latest", params=params)
+        return PriceUpdateResponse.model_validate(response.json())
+
+    async def get_price_at(
+        self,
+        publish_time: int,
+        ids: list[str],
+        *,
+        parsed: bool = True,
+        encoding: str = "hex",
+    ) -> PriceUpdateResponse:
+        params = _price_params(ids, parsed=parsed, encoding=encoding)
+        response = await self._request("GET", f"/v2/updates/price/{publish_time}", params=params)
+        return PriceUpdateResponse.model_validate(response.json())
+
+    async def get_price_decimal(self, feed_id: str) -> Decimal:
+        resp = await self.get_latest_price([feed_id])
+        if not resp.parsed:
+            raise ValueError(f"no parsed price returned for {feed_id!r}")
+        return resp.parsed[0].to_decimal()
+
+    async def stream_prices(
+        self,
+        ids: list[str],
+        *,
+        parsed: bool = True,
+        reconnect: bool = True,
+    ) -> AsyncIterator[PriceUpdateResponse]:
+        """Yield :class:`PriceUpdateResponse` objects from the SSE price stream.
+
+        With ``reconnect=True`` (default) the stream transparently re-opens
+        after a disconnect, applying exponential backoff between attempts. Set
+        ``reconnect=False`` to stop once the server closes the connection.
+        """
+        params: list[tuple[str, str]] = [("ids[]", fid) for fid in ids]
+        params.append(("parsed", "true" if parsed else "false"))
+
+        attempt = 0
+        while True:
+            try:
+                async with aconnect_sse(
+                    self._http,
+                    "GET",
+                    "/v2/updates/price/stream",
+                    params=params,
+                    headers=self._auth_headers(),
+                ) as event_source:
+                    event_source.response.raise_for_status()
+                    attempt = 0  # reset backoff after a successful connect
+                    async for sse in event_source.aiter_sse():
+                        if not sse.data:
+                            continue
+                        yield PriceUpdateResponse.model_validate_json(sse.data)
+            except (httpx.TransportError, httpx.HTTPStatusError):
+                if not reconnect:
+                    raise
+                await asyncio.sleep(retry_delay(attempt, None, self._config))
+                attempt += 1
+                continue
+
+            if not reconnect:
+                return
+            await asyncio.sleep(retry_delay(attempt, None, self._config))
+            attempt += 1

pyth_hermes/client.py

@@ -0,0 +1,173 @@
+"""Synchronous Pyth Hermes client."""
+
+from __future__ import annotations
+
+import time
+from decimal import Decimal
+from types import TracebackType
+from typing import Any, Optional
+
+import httpx
+
+from pyth_hermes._config import (
+    _BASE_URL_UNSET,
+    ClientConfig,
+    resolve_base_url,
+    retry_delay,
+    should_retry,
+    warn_if_base_url_ignored,
+)
+from pyth_hermes.models import PriceFeed, PriceUpdateResponse
+
+
+class HermesClient:
+    """Synchronous client for the Pyth Network Hermes API.
+
+    Get a BTC/USD price in a few lines::
+
+        from pyth_hermes import HermesClient
+        client = HermesClient()
+        feed_id = client.get_feed_id("Crypto.BTC/USD")
+        print(client.get_price_decimal(feed_id))
+
+    An ``api_key`` and custom ``base_url`` may be supplied for paid providers
+    and for the mandatory-key requirement landing 2026-07-31.
+    """
+
+    def __init__(
+        self,
+        base_url: str = _BASE_URL_UNSET,
+        *,
+        api_key: Optional[str] = None,
+        api_key_header: str = "Authorization",
+        api_key_scheme: str = "Bearer",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        backoff_base: float = 1.0,
+        backoff_cap: float = 60.0,
+        client: Optional[httpx.Client] = None,
+    ) -> None:
+        warn_if_base_url_ignored(base_url, client is not None)
+        self._config = ClientConfig(
+            base_url=resolve_base_url(base_url),
+            api_key=api_key,
+            api_key_header=api_key_header,
+            api_key_scheme=api_key_scheme,
+            timeout=timeout,
+            max_retries=max_retries,
+            backoff_base=backoff_base,
+            backoff_cap=backoff_cap,
+        )
+        self._http = client or httpx.Client(
+            base_url=self._config.normalized_base_url(), timeout=timeout
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._config.normalized_base_url()
+
+    def _auth_headers(self) -> dict[str, str]:
+        return self._config.auth_headers()
+
+    def __enter__(self) -> HermesClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _request(self, method: str, path: str, *, params: Any = None) -> httpx.Response:
+        last: Optional[httpx.Response] = None
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = self._http.request(
+                    method, path, params=params, headers=self._auth_headers()
+                )
+            except httpx.TransportError:
+                if attempt >= self._config.max_retries:
+                    raise
+                time.sleep(retry_delay(attempt, None, self._config))
+                continue
+
+            if should_retry(response) and attempt < self._config.max_retries:
+                time.sleep(retry_delay(attempt, response, self._config))
+                last = response
+                continue
+            response.raise_for_status()
+            return response
+
+        assert last is not None
+        last.raise_for_status()
+        return last  # pragma: no cover
+
+    def list_price_feeds(
+        self, *, query: Optional[str] = None, asset_type: Optional[str] = None
+    ) -> list[PriceFeed]:
+        """Return the feed catalog, optionally filtered by ``query``/``asset_type``."""
+        params: dict[str, str] = {}
+        if query is not None:
+            params["query"] = query
+        if asset_type is not None:
+            params["asset_type"] = asset_type
+        response = self._request("GET", "/v2/price_feeds", params=params)
+        return [PriceFeed.model_validate(item) for item in response.json()]
+
+    def get_feed_id(self, symbol: str) -> Optional[str]:
+        """Resolve a canonical feed id by EXACT ``attributes.symbol`` match.
+
+        ``/v2/price_feeds?query=...`` returns deprecated/variant feeds (MBTC,
+        XBTC, ...) first and matches substrings, so we filter on an exact symbol
+        equality. Returns ``None`` if no feed matches exactly.
+        """
+        feeds = self.list_price_feeds(query=symbol)
+        for feed in feeds:
+            if feed.symbol == symbol:
+                return feed.id
+        return None
+
+    def get_latest_price(
+        self,
+        ids: list[str],
+        *,
+        parsed: bool = True,
+        encoding: str = "hex",
+    ) -> PriceUpdateResponse:
+        """Latest price update for one or more feed ids."""
+        params = _price_params(ids, parsed=parsed, encoding=encoding)
+        response = self._request("GET", "/v2/updates/price/latest", params=params)
+        return PriceUpdateResponse.model_validate(response.json())
+
+    def get_price_at(
+        self,
+        publish_time: int,
+        ids: list[str],
+        *,
+        parsed: bool = True,
+        encoding: str = "hex",
+    ) -> PriceUpdateResponse:
+        """Historical price update at (or first after) a unix ``publish_time``."""
+        params = _price_params(ids, parsed=parsed, encoding=encoding)
+        response = self._request("GET", f"/v2/updates/price/{publish_time}", params=params)
+        return PriceUpdateResponse.model_validate(response.json())
+
+    def get_price_decimal(self, feed_id: str) -> Decimal:
+        """Convenience: latest human-readable spot price for one feed id."""
+        resp = self.get_latest_price([feed_id])
+        if not resp.parsed:
+            raise ValueError(f"no parsed price returned for {feed_id!r}")
+        return resp.parsed[0].to_decimal()
+
+
+def _price_params(ids: list[str], *, parsed: bool, encoding: str) -> list[tuple[str, str]]:
+    """Build repeatable ``ids[]`` query params plus flags."""
+    params: list[tuple[str, str]] = [("ids[]", fid) for fid in ids]
+    params.append(("parsed", "true" if parsed else "false"))
+    params.append(("encoding", encoding))
+    return params

pyth_hermes/models.py

@@ -0,0 +1,115 @@
+"""Pydantic v2 models for Pyth Hermes API responses."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+def price_to_decimal(price: Union[int, str], expo: int) -> Decimal:
+    """Convert a raw Pyth price + exponent into a real ``Decimal`` value.
+
+    Real price = ``price * 10 ** expo``. Computed with ``Decimal`` to avoid
+    binary float imprecision.
+
+    Example: ``price=6395282153102, expo=-8`` -> ``Decimal("63952.82153102")``.
+    """
+    return Decimal(str(price)) * (Decimal(10) ** expo)
+
+
+class RpcPrice(BaseModel):
+    """A single price reading with its exponent and publish time."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    price: int
+    conf: int
+    expo: int
+    publish_time: int
+
+    def to_decimal(self) -> Decimal:
+        """Return the human-readable price as a ``Decimal``."""
+        return price_to_decimal(self.price, self.expo)
+
+    def conf_to_decimal(self) -> Decimal:
+        """Return the confidence interval as a ``Decimal`` (same exponent)."""
+        return price_to_decimal(self.conf, self.expo)
+
+
+class PriceFeedMetadata(BaseModel):
+    """Metadata attached to a parsed price update."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    slot: Optional[int] = None
+    proof_available_time: Optional[int] = None
+    prev_publish_time: Optional[int] = None
+
+
+class ParsedPriceUpdate(BaseModel):
+    """A single parsed price update for one feed id."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: str
+    price: RpcPrice
+    ema_price: RpcPrice
+    metadata: PriceFeedMetadata = Field(default_factory=PriceFeedMetadata)
+
+    def to_decimal(self) -> Decimal:
+        """Convenience: human-readable spot price as a ``Decimal``."""
+        return self.price.to_decimal()
+
+
+class BinaryUpdate(BaseModel):
+    """The encoded binary VAA/update payload."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    encoding: str
+    data: list[str]
+
+
+class PriceUpdateResponse(BaseModel):
+    """Response from the latest / historical price update endpoints."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    binary: BinaryUpdate
+    parsed: Optional[list[ParsedPriceUpdate]] = None
+
+
+class FeedAttributes(BaseModel):
+    """Attributes block of a price feed catalog entry.
+
+    The Hermes ``attributes`` object is an open string map; the well-known
+    keys are surfaced as typed fields and any extras are preserved.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    asset_type: Optional[str] = None
+    base: Optional[str] = None
+    quote_currency: Optional[str] = None
+    country: Optional[str] = None
+    description: Optional[str] = None
+    display_symbol: Optional[str] = None
+    publish_interval: Optional[str] = None
+    schedule: Optional[str] = None
+    symbol: Optional[str] = None
+
+
+class PriceFeed(BaseModel):
+    """A single price feed catalog entry from ``/v2/price_feeds``."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: str
+    attributes: FeedAttributes = Field(default_factory=FeedAttributes)
+
+    @property
+    def symbol(self) -> Optional[str]:
+        """Shortcut to ``attributes.symbol`` (e.g. ``"Crypto.BTC/USD"``)."""
+        return self.attributes.symbol

pyth_hermes/pandas.py

@@ -0,0 +1,38 @@
+"""Optional pandas helpers. Requires the ``pandas`` extra: ``pip install pyth-hermes[pandas]``."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+try:
+    import pandas as pd
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "pandas is required for pyth_hermes.pandas; install with 'pip install pyth-hermes[pandas]'"
+    ) from exc
+
+from pyth_hermes.models import PriceUpdateResponse
+
+_COLUMNS = ["id", "publish_time", "price", "conf", "expo", "price_decimal"]
+
+
+def updates_to_dataframe(responses: Iterable[PriceUpdateResponse]) -> pd.DataFrame:
+    """Flatten a sequence of price-update responses into a tidy DataFrame.
+
+    One row per parsed update with the raw integer ``price``/``conf``/``expo``
+    plus a ``price_decimal`` column carrying the human-readable ``Decimal``.
+    """
+    rows: list[dict[str, object]] = []
+    for response in responses:
+        for update in response.parsed or []:
+            rows.append(
+                {
+                    "id": update.id,
+                    "publish_time": update.price.publish_time,
+                    "price": update.price.price,
+                    "conf": update.price.conf,
+                    "expo": update.price.expo,
+                    "price_decimal": update.price.to_decimal(),
+                }
+            )
+    return pd.DataFrame(rows, columns=_COLUMNS)

pyth_hermes-0.1.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: pyth-hermes
+Version: 0.1.0
+Summary: Python client for the Pyth Network Hermes price-oracle API (sync + async, SSE streaming).
+Project-URL: Homepage, https://github.com/robertruben98/pyth-hermes
+Project-URL: Repository, https://github.com/robertruben98/pyth-hermes
+Project-URL: Documentation, https://docs.pyth.network/price-feeds/core/how-pyth-works/hermes
+Project-URL: Issues, https://github.com/robertruben98/pyth-hermes/issues
+Author: Robert Ruben
+License: MIT
+License-File: LICENSE
+Keywords: defi,hermes,oracle,price-feed,pyth,solana
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx-sse>=0.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pandas-stubs; extra == 'dev'
+Requires-Dist: pandas>=2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# pyth-hermes
+
+A typed Python client for the [Pyth Network](https://pyth.network) **Hermes** price-oracle API. Sync **and** async clients, Pydantic v2 models, Server-Sent-Events price streaming with auto-reconnect, and a `Decimal` price helper.
+
+- Sync (`HermesClient`) and async (`AsyncHermesClient`) APIs over `httpx`
+- SSE streaming with reconnect + backoff
+- Graceful 429 rate-limit handling (retries that respect the 60s window)
+- Configurable `base_url` (production, beta, or paid providers) and optional API key from day one
+- `mypy --strict` clean, fully type-hinted, ships `py.typed`
+
+## Install
+
+```bash
+pip install pyth-hermes
+# with the optional pandas helper:
+pip install "pyth-hermes[pandas]"
+```
+
+## Quickstart — BTC/USD price in under 5 lines
+
+```python
+from pyth_hermes import HermesClient
+
+client = HermesClient()
+feed_id = client.get_feed_id("Crypto.BTC/USD")   # exact-symbol lookup
+print(client.get_price_decimal(feed_id))         # -> Decimal("63952.82...")
+```
+
+### Async + streaming
+
+```python
+import asyncio
+from pyth_hermes import AsyncHermesClient
+
+BTC = "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43"
+
+async def main():
+    async with AsyncHermesClient() as client:
+        async for update in client.stream_prices([BTC]):
+            print(update.parsed[0].to_decimal())
+
+asyncio.run(main())
+```
+
+### Historical price
+
+```python
+resp = client.get_price_at(1718900000, [BTC])   # unix timestamp
+print(resp.parsed[0].to_decimal())
+```
+
+### pandas
+
+```python
+from pyth_hermes.pandas import updates_to_dataframe
+df = updates_to_dataframe([client.get_latest_price([BTC])])
+```
+
+## Prices and exponents
+
+Pyth returns integer prices plus an exponent. The real value is `price * 10**expo`, computed exactly as a `Decimal`:
+
+```python
+from pyth_hermes import price_to_decimal
+price_to_decimal(6395282153102, -8)   # Decimal("63952.82153102")
+```
+
+`RpcPrice.to_decimal()` and `ParsedPriceUpdate.to_decimal()` are convenience wrappers.
+
+## Finding feed ids — use the EXACT symbol
+
+`/v2/price_feeds?query=btc` returns **deprecated / variant** feeds (e.g. `MBTC`, `XBTC`) *before* the canonical one and matches substrings. `get_feed_id()` therefore matches on exact `attributes.symbol`:
+
+```python
+client.get_feed_id("Crypto.BTC/USD")
+# -> "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43"
+```
+
+## 🔴 Authentication (changes 2026-07-31)
+
+Today the public endpoint needs **no** API key. **From 2026-07-31 an API key becomes mandatory.** This client accepts one from day one — pass it now to be ready:
+
+```python
+client = HermesClient(api_key="YOUR_KEY")  # default: Authorization: Bearer YOUR_KEY
+```
+
+The exact header is not finalized publicly, so both the header name and scheme are configurable:
+
+```python
+HermesClient(api_key="KEY", api_key_header="X-Api-Key", api_key_scheme="")  # -> X-Api-Key: KEY
+```
+
+## Endpoints / base URLs
+
+```python
+from pyth_hermes import HermesClient
+
+HermesClient()                                           # production: https://hermes.pyth.network
+HermesClient(base_url="https://hermes-beta.pyth.network")  # beta
+HermesClient(base_url="https://your-paid-provider.example")  # Triton / P2P / extrnode / Liquify
+```
+
+You may also inject your own preconfigured `httpx.Client` / `httpx.AsyncClient` via `client=...` (e.g. for custom transports, proxies, or connection pools). In that case the request host is taken from **your** client, so set `base_url` on the client itself — passing both `base_url=` and `client=` raises a `UserWarning` because the constructor's `base_url` would be a no-op. The `api_key` is still applied per-request, so it works with an injected client.
+
+```python
+import httpx
+from pyth_hermes import HermesClient
+
+http = httpx.Client(base_url="https://your-paid-provider.example", proxy="http://localhost:8080")
+client = HermesClient(api_key="KEY", client=http)  # base_url comes from `http`
+```
+
+## Rate limits
+
+The public endpoint allows **10 requests / 10 seconds per IP**. Exceeding it returns HTTP 429 for the next 60 seconds. The client retries 429 and 5xx responses with exponential backoff + jitter, honoring any `Retry-After` header and never exceeding the 60s rate-limit window per delay. Tune via `max_retries`, `backoff_base`, `backoff_cap`.
+
+## Not implemented
+
+The TWAP endpoints (`/v2/updates/twap/...`) are intentionally omitted — the API returns HTTP 400 "deprecated and no longer available".
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                 # unit tests (no network)
+pytest -m integration  # live smoke tests against production
+mypy
+ruff check .
+```
+
+## License
+
+MIT

pyth_hermes-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pyth_hermes/__init__.py,sha256=nHOrUiz_mUgxbkIt_YnM8ZMhveAgIRtotDPnrE_NjMY,671
+pyth_hermes/_config.py,sha256=-tAx1E63_6P6H3aWieue6lzBvy87N48lPWs7mswD11s,3537
+pyth_hermes/async_client.py,sha256=6CFhl0F6MlFJrr0K-o_TRBYx5W_h7AEW-GElSrIWGBA,6809
+pyth_hermes/client.py,sha256=gvnSPYrWMnWA0tRdgVijMs-kBWICUlYoeuYmr8mAGZA,5987
+pyth_hermes/models.py,sha256=ikp6H_-aiZyseyBEZrI3QfGj3bqWKUaXmsOG_P4odFU,3257
+pyth_hermes/pandas.py,sha256=qiZXcVLJThBPbs7S8AuXkYKGN6AGEkBLUAy3uviRjQs,1388
+pyth_hermes/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyth_hermes-0.1.0.dist-info/METADATA,sha256=C4P6X5836CJ63PiTo0bXHlaY83i35K-WYXXLWS3KS2k,6210
+pyth_hermes-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pyth_hermes-0.1.0.dist-info/licenses/LICENSE,sha256=-AcjerVulaZXw9Ub2qG825vAXbFN8KNwHs9VEcf2XDo,1069
+pyth_hermes-0.1.0.dist-info/RECORD,,

pyth_hermes-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pyth_hermes-0.1.0.dist-info/licenses/LICENSE

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