odos-py 0.1.0__py3-none-any.whl

odos_py/__init__.py

@@ -0,0 +1,33 @@
+"""odos-py: a modern Python client for the Odos DEX Aggregator API."""
+
+from __future__ import annotations
+
+from .async_client import AsyncOdosClient
+from .client import OdosClient
+from .exceptions import OdosAPIError, OdosError, OdosRateLimitError
+from .models import (
+    AssembleRequest,
+    AssembleResponse,
+    InputToken,
+    OutputToken,
+    QuoteRequest,
+    QuoteResponse,
+    Transaction,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OdosClient",
+    "AsyncOdosClient",
+    "OdosError",
+    "OdosAPIError",
+    "OdosRateLimitError",
+    "QuoteRequest",
+    "QuoteResponse",
+    "AssembleRequest",
+    "AssembleResponse",
+    "InputToken",
+    "OutputToken",
+    "Transaction",
+]

odos_py/_base.py

@@ -0,0 +1,110 @@
+"""Shared configuration and HTTP plumbing for the sync and async clients."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any, Mapping, Optional
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.odos.xyz"
+DEFAULT_API_KEY_HEADER = "x-api-key"
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_BACKOFF_BASE = 0.5
+DEFAULT_TIMEOUT = 30.0
+
+
+class OdosConfig:
+    """Holds connection settings shared by both client flavours."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: Optional[str] = None,
+        api_key_header: str = DEFAULT_API_KEY_HEADER,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        backoff_base: float = DEFAULT_BACKOFF_BASE,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.api_key_header = api_key_header
+        self.max_retries = max_retries
+        self.backoff_base = backoff_base
+        self.timeout = timeout
+
+    def headers(self) -> dict[str, str]:
+        """Build default request headers, including the API key when set."""
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        if self.api_key:
+            headers[self.api_key_header] = self.api_key
+        return headers
+
+    def url(self, path: str) -> str:
+        return f"{self.base_url}/{path.lstrip('/')}"
+
+
+def parse_retry_after(
+    headers: Mapping[str, str], *, now: Optional[datetime] = None
+) -> Optional[float]:
+    """Extract the ``Retry-After`` delay in seconds, if present.
+
+    Per RFC 7231 the header may be either a number of seconds (delta) or an
+    HTTP-date. Both forms are supported; an HTTP-date is converted to a delay
+    relative to ``now`` (defaulting to the current UTC time) and clamped to a
+    non-negative value. Returns ``None`` when the header is absent or
+    unparseable, so callers fall back to exponential backoff.
+    """
+    value = headers.get("Retry-After") or headers.get("retry-after")
+    if value is None:
+        return None
+
+    text = str(value).strip()
+
+    # Form 1: a number of seconds.
+    try:
+        return float(text)
+    except ValueError:
+        pass
+
+    # Form 2: an HTTP-date.
+    try:
+        target = parsedate_to_datetime(text)
+    except (TypeError, ValueError):
+        return None
+    if target is None:
+        return None
+    if target.tzinfo is None:
+        target = target.replace(tzinfo=timezone.utc)
+
+    current = now or datetime.now(timezone.utc)
+    if current.tzinfo is None:
+        current = current.replace(tzinfo=timezone.utc)
+
+    delay = (target - current).total_seconds()
+    return max(0.0, delay)
+
+
+def backoff_delay(base: float, attempt: int, retry_after: Optional[float]) -> float:
+    """Compute the wait before the next retry (exponential, server-hint aware).
+
+    ``attempt`` is zero-based. A server-provided ``Retry-After`` wins when it is
+    larger than the computed exponential backoff.
+    """
+    computed = base * float(2**attempt)
+    if retry_after is not None:
+        return max(computed, retry_after)
+    return computed
+
+
+def safe_json(response: httpx.Response) -> Any:
+    """Return parsed JSON, or the raw text if the body is not valid JSON."""
+    try:
+        return response.json()
+    except ValueError:
+        return response.text

odos_py/async_client.py

@@ -0,0 +1,163 @@
+"""Asynchronous client for the Odos DEX Aggregator API."""
+
+from __future__ import annotations
+
+import asyncio
+from types import TracebackType
+from typing import Any, Optional
+
+import httpx
+
+from ._base import (
+    DEFAULT_API_KEY_HEADER,
+    DEFAULT_BACKOFF_BASE,
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    OdosConfig,
+    backoff_delay,
+    parse_retry_after,
+    safe_json,
+)
+from .exceptions import OdosAPIError, OdosRateLimitError
+from .models import AssembleRequest, AssembleResponse, QuoteRequest, QuoteResponse
+
+
+class AsyncOdosClient:
+    """Async counterpart of :class:`~odos_py.client.OdosClient`.
+
+    Same configuration and behaviour, backed by ``httpx.AsyncClient``.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: Optional[str] = None,
+        api_key_header: str = DEFAULT_API_KEY_HEADER,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        backoff_base: float = DEFAULT_BACKOFF_BASE,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        self._config = OdosConfig(
+            base_url=base_url,
+            api_key=api_key,
+            api_key_header=api_key_header,
+            max_retries=max_retries,
+            backoff_base=backoff_base,
+            timeout=timeout,
+        )
+        self._client = httpx.AsyncClient(
+            timeout=timeout,
+            headers=self._config.headers(),
+            transport=transport,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._config.base_url
+
+    # -- lifecycle ---------------------------------------------------------
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncOdosClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        await self.aclose()
+
+    # -- low-level request with retry/backoff ------------------------------
+
+    async def _request(self, method: str, path: str, *, json: Any = None) -> Any:
+        url = self._config.url(path)
+        attempt = 0
+        while True:
+            response = await self._client.request(method, url, json=json)
+            if response.status_code < 400:
+                return safe_json(response)
+
+            if response.status_code == 429 and attempt < self._config.max_retries:
+                retry_after = parse_retry_after(response.headers)
+                delay = backoff_delay(self._config.backoff_base, attempt, retry_after)
+                if delay > 0:
+                    await asyncio.sleep(delay)
+                attempt += 1
+                continue
+
+            body = safe_json(response)
+            message = f"{method} {url} failed with status {response.status_code}"
+            if response.status_code == 429:
+                raise OdosRateLimitError(
+                    message,
+                    status_code=429,
+                    body=body,
+                    retry_after=parse_retry_after(response.headers),
+                )
+            raise OdosAPIError(message, status_code=response.status_code, body=body)
+
+    # -- SOR endpoints -----------------------------------------------------
+
+    async def quote(self, request: QuoteRequest) -> QuoteResponse:
+        """``POST /sor/quote/v2`` — get a swap path and its ``pathId``."""
+        data = await self._request("POST", "/sor/quote/v2", json=request.model_dump(by_alias=True))
+        return QuoteResponse.model_validate(data)
+
+    async def assemble(
+        self, *, user_addr: str, path_id: str, simulate: bool = False
+    ) -> AssembleResponse:
+        """``POST /sor/assemble`` — turn a ``pathId`` into signable calldata."""
+        req = AssembleRequest(user_addr=user_addr, path_id=path_id, simulate=simulate)
+        data = await self._request("POST", "/sor/assemble", json=req.model_dump(by_alias=True))
+        return AssembleResponse.model_validate(data)
+
+    async def execute(self, *, user_addr: str, path_id: str) -> Any:
+        """``POST /sor/execute`` — assisted execution (returns raw JSON)."""
+        return await self._request(
+            "POST",
+            "/sor/execute",
+            json={"userAddr": user_addr, "pathId": path_id},
+        )
+
+    async def swap(
+        self, request: QuoteRequest, *, simulate: bool = False
+    ) -> tuple[QuoteResponse, AssembleResponse]:
+        """Convenience helper: quote then assemble in one awaited call."""
+        quote = await self.quote(request)
+        if not quote.path_id:
+            raise OdosAPIError("Quote response did not include a pathId", body=quote.model_dump())
+        assembled = await self.assemble(
+            user_addr=request.user_addr, path_id=quote.path_id, simulate=simulate
+        )
+        return quote, assembled
+
+    quote_and_assemble = swap
+
+    # -- info / pricing endpoints -----------------------------------------
+
+    async def get_chains(self) -> Any:
+        """``GET /info/chains`` — supported chains."""
+        return await self._request("GET", "/info/chains")
+
+    async def get_tokens(self, chain_id: int) -> Any:
+        """``GET /info/tokens/{chainId}`` — token map for a chain."""
+        return await self._request("GET", f"/info/tokens/{chain_id}")
+
+    async def get_router(self, chain_id: int) -> Any:
+        """``GET /info/router/v2/{chainId}`` — router contract address."""
+        return await self._request("GET", f"/info/router/v2/{chain_id}")
+
+    async def get_contract_info(self, chain_id: int) -> Any:
+        """``GET /info/contract-info/v2/{chainId}`` — contract metadata."""
+        return await self._request("GET", f"/info/contract-info/v2/{chain_id}")
+
+    async def get_token_price(self, chain_id: int, token_address: str) -> Any:
+        """``GET /pricing/token/{chainId}/{tokenAddress}`` — token price."""
+        return await self._request("GET", f"/pricing/token/{chain_id}/{token_address}")

odos_py/client.py

@@ -0,0 +1,167 @@
+"""Synchronous client for the Odos DEX Aggregator API."""
+
+from __future__ import annotations
+
+import time
+from types import TracebackType
+from typing import Any, Optional
+
+import httpx
+
+from ._base import (
+    DEFAULT_API_KEY_HEADER,
+    DEFAULT_BACKOFF_BASE,
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    OdosConfig,
+    backoff_delay,
+    parse_retry_after,
+    safe_json,
+)
+from .exceptions import OdosAPIError, OdosRateLimitError
+from .models import AssembleRequest, AssembleResponse, QuoteRequest, QuoteResponse
+
+
+class OdosClient:
+    """A synchronous client for the Odos API.
+
+    The free keyless tier is heavily rate limited; pass ``api_key`` to raise
+    limits. ``api_key_header`` is configurable because the exact header name is
+    not publicly documented.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: Optional[str] = None,
+        api_key_header: str = DEFAULT_API_KEY_HEADER,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        backoff_base: float = DEFAULT_BACKOFF_BASE,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self._config = OdosConfig(
+            base_url=base_url,
+            api_key=api_key,
+            api_key_header=api_key_header,
+            max_retries=max_retries,
+            backoff_base=backoff_base,
+            timeout=timeout,
+        )
+        self._client = httpx.Client(
+            timeout=timeout,
+            headers=self._config.headers(),
+            transport=transport,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._config.base_url
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> OdosClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+    # -- low-level request with retry/backoff ------------------------------
+
+    def _request(self, method: str, path: str, *, json: Any = None) -> Any:
+        url = self._config.url(path)
+        attempt = 0
+        while True:
+            response = self._client.request(method, url, json=json)
+            if response.status_code < 400:
+                return safe_json(response)
+
+            if response.status_code == 429 and attempt < self._config.max_retries:
+                retry_after = parse_retry_after(response.headers)
+                delay = backoff_delay(self._config.backoff_base, attempt, retry_after)
+                if delay > 0:
+                    time.sleep(delay)
+                attempt += 1
+                continue
+
+            body = safe_json(response)
+            message = f"{method} {url} failed with status {response.status_code}"
+            if response.status_code == 429:
+                raise OdosRateLimitError(
+                    message,
+                    status_code=429,
+                    body=body,
+                    retry_after=parse_retry_after(response.headers),
+                )
+            raise OdosAPIError(message, status_code=response.status_code, body=body)
+
+    # -- SOR endpoints -----------------------------------------------------
+
+    def quote(self, request: QuoteRequest) -> QuoteResponse:
+        """``POST /sor/quote/v2`` — get a swap path and its ``pathId``."""
+        data = self._request("POST", "/sor/quote/v2", json=request.model_dump(by_alias=True))
+        return QuoteResponse.model_validate(data)
+
+    def assemble(self, *, user_addr: str, path_id: str, simulate: bool = False) -> AssembleResponse:
+        """``POST /sor/assemble`` — turn a ``pathId`` into signable calldata."""
+        req = AssembleRequest(user_addr=user_addr, path_id=path_id, simulate=simulate)
+        data = self._request("POST", "/sor/assemble", json=req.model_dump(by_alias=True))
+        return AssembleResponse.model_validate(data)
+
+    def execute(self, *, user_addr: str, path_id: str) -> Any:
+        """``POST /sor/execute`` — assisted execution (returns raw JSON)."""
+        return self._request(
+            "POST",
+            "/sor/execute",
+            json={"userAddr": user_addr, "pathId": path_id},
+        )
+
+    def swap(
+        self, request: QuoteRequest, *, simulate: bool = False
+    ) -> tuple[QuoteResponse, AssembleResponse]:
+        """Convenience helper: quote then assemble in one call.
+
+        Returns the quote and the assembled transaction. Raises
+        :class:`OdosAPIError` if the quote did not return a ``pathId``.
+        """
+        quote = self.quote(request)
+        if not quote.path_id:
+            raise OdosAPIError("Quote response did not include a pathId", body=quote.model_dump())
+        assembled = self.assemble(
+            user_addr=request.user_addr, path_id=quote.path_id, simulate=simulate
+        )
+        return quote, assembled
+
+    quote_and_assemble = swap
+
+    # -- info / pricing endpoints -----------------------------------------
+
+    def get_chains(self) -> Any:
+        """``GET /info/chains`` — supported chains."""
+        return self._request("GET", "/info/chains")
+
+    def get_tokens(self, chain_id: int) -> Any:
+        """``GET /info/tokens/{chainId}`` — token map for a chain."""
+        return self._request("GET", f"/info/tokens/{chain_id}")
+
+    def get_router(self, chain_id: int) -> Any:
+        """``GET /info/router/v2/{chainId}`` — router contract address."""
+        return self._request("GET", f"/info/router/v2/{chain_id}")
+
+    def get_contract_info(self, chain_id: int) -> Any:
+        """``GET /info/contract-info/v2/{chainId}`` — contract metadata."""
+        return self._request("GET", f"/info/contract-info/v2/{chain_id}")
+
+    def get_token_price(self, chain_id: int, token_address: str) -> Any:
+        """``GET /pricing/token/{chainId}/{tokenAddress}`` — token price."""
+        return self._request("GET", f"/pricing/token/{chain_id}/{token_address}")

odos_py/exceptions.py

@@ -0,0 +1,42 @@
+"""Exception hierarchy for the Odos client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class OdosError(Exception):
+    """Base class for all errors raised by this library."""
+
+
+class OdosAPIError(OdosError):
+    """Raised when the Odos API returns a non-success HTTP status."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class OdosRateLimitError(OdosAPIError):
+    """Raised on HTTP 429 after retries are exhausted.
+
+    ``retry_after`` is the server-advised wait in seconds, when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        body: Any = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, body=body)
+        self.retry_after = retry_after

odos_py/models.py

@@ -0,0 +1,106 @@
+"""Pydantic models for Odos API requests and responses.
+
+All models accept both the API's native ``camelCase`` field names and
+``snake_case`` aliases so the library is ergonomic from Python while staying
+faithful to the wire format. Response models tolerate unknown fields because
+the Odos API returns a large, evolving payload.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+_REQUEST_CONFIG = ConfigDict(
+    alias_generator=to_camel,
+    populate_by_name=True,
+    serialize_by_alias=True,
+)
+_RESPONSE_CONFIG = ConfigDict(
+    alias_generator=to_camel,
+    populate_by_name=True,
+    extra="allow",
+)
+
+
+class InputToken(BaseModel):
+    """A token being sold, with its amount expressed in wei (base units)."""
+
+    model_config = _REQUEST_CONFIG
+
+    token_address: str
+    amount: str
+
+
+class OutputToken(BaseModel):
+    """A token being bought, with its desired proportion of the output."""
+
+    model_config = _REQUEST_CONFIG
+
+    token_address: str
+    proportion: float
+
+
+class QuoteRequest(BaseModel):
+    """Body for ``POST /sor/quote/v2``."""
+
+    model_config = _REQUEST_CONFIG
+
+    chain_id: int
+    input_tokens: list[InputToken]
+    output_tokens: list[OutputToken]
+    user_addr: str
+    slippage_limit_percent: float
+
+
+class QuoteResponse(BaseModel):
+    """Response from ``POST /sor/quote/v2``.
+
+    Only the fields commonly needed by callers are typed explicitly; any other
+    fields the API returns are preserved (``extra="allow"``).
+    """
+
+    model_config = _RESPONSE_CONFIG
+
+    path_id: Optional[str] = None
+    out_amounts: list[str] = Field(default_factory=list)
+    in_amounts: list[str] = Field(default_factory=list)
+    gas_estimate: Optional[float] = None
+    gas_estimate_value: Optional[float] = None
+    price_impact: Optional[float] = None
+    block_number: Optional[int] = None
+
+
+class AssembleRequest(BaseModel):
+    """Body for ``POST /sor/assemble``."""
+
+    model_config = _REQUEST_CONFIG
+
+    user_addr: str
+    path_id: str
+    simulate: bool = False
+
+
+class Transaction(BaseModel):
+    """The ready-to-sign transaction returned by ``assemble``."""
+
+    model_config = _RESPONSE_CONFIG
+
+    to: Optional[str] = None
+    data: Optional[str] = None
+    value: Optional[str] = None
+    gas: Optional[int] = None
+    gas_price: Optional[int] = None
+    nonce: Optional[int] = None
+    chain_id: Optional[int] = None
+    from_: Optional[str] = Field(default=None, alias="from")
+
+
+class AssembleResponse(BaseModel):
+    """Response from ``POST /sor/assemble``."""
+
+    model_config = _RESPONSE_CONFIG
+
+    transaction: Optional[Transaction] = None

odos_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: odos-py
+Version: 0.1.0
+Summary: A modern Python client for the Odos DEX Aggregator API
+Project-URL: Homepage, https://github.com/robertruben98/odos-py
+Project-URL: Documentation, https://docs.odos.xyz/build/api-docs
+Project-URL: Repository, https://github.com/robertruben98/odos-py
+Project-URL: Issues, https://github.com/robertruben98/odos-py/issues
+Author: robertdev
+License: MIT
+License-File: LICENSE
+Keywords: aggregator,defi,dex,ethereum,odos,swap
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: exec
+Requires-Dist: web3>=6.0; extra == 'exec'
+Description-Content-Type: text/markdown
+
+# odos-py
+
+A modern, fully-typed Python client for the [Odos](https://docs.odos.xyz/build/api-docs) DEX Aggregator API.
+
+- Sync (`OdosClient`) and async (`AsyncOdosClient`) clients built on `httpx`
+- `pydantic` v2 models for all requests and responses
+- Automatic HTTP 429 handling with exponential backoff
+- Configurable base URL and API-key header
+- `mypy --strict` clean, ships a `py.typed` marker
+
+## Install
+
+```bash
+pip install odos-py
+```
+
+Optional extra for signing/sending the assembled transaction with `web3.py`:
+
+```bash
+pip install "odos-py[exec]"
+```
+
+## Quickstart
+
+Odos works in two steps: `quote` returns a `pathId`, then `assemble` turns that
+`pathId` into ready-to-sign transaction calldata. The `swap()` helper chains
+both:
+
+```python
+from odos_py import OdosClient, QuoteRequest, InputToken, OutputToken
+
+client = OdosClient(api_key="YOUR_KEY")  # api_key optional but recommended
+quote, assembled = client.swap(QuoteRequest(
+    chain_id=1,
+    input_tokens=[InputToken(token_address="0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",  # WETH
+                             amount="1000000000000000000")],                              # 1 WETH (wei)
+    output_tokens=[OutputToken(token_address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",  # USDC
+                               proportion=1)],
+    user_addr="0x47E2D28169738039755586743E2dfCF3bd643f86",
+    slippage_limit_percent=0.3,
+))
+print(quote.path_id, assembled.transaction.to)
+```
+
+Async is identical with `await`:
+
+```python
+import asyncio
+from odos_py import AsyncOdosClient
+
+async def main(request):
+    async with AsyncOdosClient() as client:
+        quote = await client.quote(request)
+        print(quote.path_id)
+```
+
+## Auth & rate limits
+
+There is a free, **keyless** tier, but it is heavily rate limited — `POST
+/sor/quote/v2` returns HTTP 429 quickly without a key. Pass an `api_key` to
+raise limits. The exact API-key header name is not publicly documented, so it
+is configurable:
+
+```python
+OdosClient(api_key="YOUR_KEY", api_key_header="x-api-key")  # default header name
+```
+
+The client retries 429 responses with exponential backoff (honouring any
+`Retry-After` header) and raises `OdosRateLimitError` once retries are
+exhausted. Tune with `max_retries` and `backoff_base`.
+
+## Endpoints
+
+| Method | Endpoint |
+| --- | --- |
+| `quote(request)` | `POST /sor/quote/v2` |
+| `assemble(user_addr=, path_id=)` | `POST /sor/assemble` |
+| `execute(user_addr=, path_id=)` | `POST /sor/execute` |
+| `swap(request)` / `quote_and_assemble(request)` | quote then assemble |
+| `get_chains()` | `GET /info/chains` |
+| `get_tokens(chain_id)` | `GET /info/tokens/{chainId}` |
+| `get_router(chain_id)` | `GET /info/router/v2/{chainId}` |
+| `get_contract_info(chain_id)` | `GET /info/contract-info/v2/{chainId}` |
+| `get_token_price(chain_id, token_address)` | `GET /pricing/token/{chainId}/{tokenAddress}` |
+
+Multi-chain is handled per call via `chain_id` on `QuoteRequest` and the info
+endpoints.
+
+## Configuration
+
+```python
+OdosClient(
+    base_url="https://api.odos.xyz",  # configurable / proxyable
+    api_key=None,
+    api_key_header="x-api-key",
+    max_retries=3,
+    backoff_base=0.5,
+    timeout=30.0,
+)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev,exec]"
+pytest                  # unit tests (HTTP mocked, no network)
+pytest -m integration   # live smoke test against /info/chains
+ruff check .
+mypy
+```
+
+## License
+
+MIT

odos_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+odos_py/__init__.py,sha256=6M2Eu4raTapGlVVbNItTwLEVlBLgJuzlOcBkgZgILDw,689
+odos_py/_base.py,sha256=eVpW_URmVefVAChSegNcn1cUaYngFifpl2SAf78hwbc,3436
+odos_py/async_client.py,sha256=ICyFDH_zm7tMIalMZ60NsrOvYEh66aiuAL45O8NyJtk,6078
+odos_py/client.py,sha256=24MvIazeXvJXF5ERQxrYpV77XME5J-6wiu348cyqsvE,6104
+odos_py/exceptions.py,sha256=MTce7jYyIqTAP14tEQyNDf0NI0J6eO8EUnSKcn_KP60,1043
+odos_py/models.py,sha256=B5LMUbvbnAXMqGF1IVMFRTSg0d9PzdtC7gi_vJrgCQ4,2705
+odos_py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+odos_py-0.1.0.dist-info/METADATA,sha256=IAf2aclXr4-esBRI8vx5JSsag1xe1CloF1YxnEB9YJ0,4735
+odos_py-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+odos_py-0.1.0.dist-info/licenses/LICENSE,sha256=-AcjerVulaZXw9Ub2qG825vAXbFN8KNwHs9VEcf2XDo,1069
+odos_py-0.1.0.dist-info/RECORD,,

odos_py-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

odos_py-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.