duo-data-utilities 0.2.1__py3-none-any.whl

duo_data_utilities/__init__.py

@@ -0,0 +1,37 @@
+"""Pay-per-call data for AI agents (x402, USDC on Base): IBAN, ISIN, VAT/tax ID, GTIN and 29 more utilities, plus
+crypto derivatives data (perp funding rates, open interest, futures basis, implied volatility, liquidations,
+order book depth) through DuoClient(...).derivs or DerivsClient."""
+
+from ._version import USER_AGENT, __version__
+from .client import DuoClient, PaidResult
+from .counterparty import CounterpartyCheck, CounterpartyResult
+from .derivs import DEFAULT_DERIVS_BASE_URL, DEFAULT_DERIVS_MAX_PRICE_USD, DERIVS_MCP_URL, DerivsClient, DerivsPaidResult
+from .derivs_generated import DERIVS_ROUTES, DerivsMethods, DerivsRouteInfo
+from .errors import DuoApiError, PriceGuardError
+from .generated import ROUTES, DuoMethods, RouteInfo
+from .price_guard import BASE_NETWORK, BASE_USDC_ADDRESS, DEFAULT_MAX_PRICE_USD
+
+__all__ = [
+    "BASE_NETWORK",
+    "BASE_USDC_ADDRESS",
+    "CounterpartyCheck",
+    "CounterpartyResult",
+    "DEFAULT_DERIVS_BASE_URL",
+    "DEFAULT_DERIVS_MAX_PRICE_USD",
+    "DEFAULT_MAX_PRICE_USD",
+    "DERIVS_MCP_URL",
+    "DERIVS_ROUTES",
+    "DerivsClient",
+    "DerivsMethods",
+    "DerivsPaidResult",
+    "DerivsRouteInfo",
+    "DuoApiError",
+    "DuoClient",
+    "DuoMethods",
+    "PaidResult",
+    "PriceGuardError",
+    "ROUTES",
+    "RouteInfo",
+    "USER_AGENT",
+    "__version__",
+]

duo_data_utilities/_http.py

@@ -0,0 +1,116 @@
+"""HTTP plumbing shared by DuoClient (api.duoleads.com) and DerivsClient (derivs.duoleads.com)."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Callable, Mapping
+from urllib.parse import urlsplit, urlunsplit
+
+import requests
+from x402 import SchemeRegistration, x402ClientConfig, x402ClientSync
+from x402.http import x402HTTPClientSync
+from x402.http.clients.requests import wrapRequestsWithPayment
+from x402.http.utils import decode_payment_response_header
+from x402.mechanisms.evm.exact.client import ExactEvmScheme
+
+from .errors import PriceGuardError
+from .price_guard import BASE_NETWORK, guard_policy, requirement_problem
+
+# urllib returns IPv6 hosts without brackets.
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+def normalise_base_url(raw: str) -> str:
+    parts = urlsplit(raw)
+    plain_loopback = parts.scheme == "http" and parts.hostname in _LOOPBACK_HOSTS
+    if parts.scheme != "https" and not plain_loopback:
+        raise ValueError(f"base_url must use https (plain http is only allowed for localhost): {raw}")
+    if parts.query or parts.fragment:
+        raise ValueError("base_url must not contain a query or a fragment")
+    return urlunsplit((parts.scheme, parts.netloc, parts.path.rstrip("/"), "", ""))
+
+
+def assert_route_path(path: str) -> None:
+    if not re.fullmatch(r"/v1/[a-z]+/[a-z0-9-]+", path):
+        raise ValueError(f"not a route path: {path!r} (expected /v1/<group>/<name>)")
+
+
+def _query_value(name: str, value: Any) -> str:
+    # bool is a subclass of int, so it is checked first. The API expects "true" and "false".
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, str):
+        return value
+    raise TypeError(f"parameter {name} must be a string, number or boolean")
+
+
+def _query(params: Mapping[str, Any]) -> dict[str, str]:
+    return {name: _query_value(name, value) for name, value in params.items() if value is not None}
+
+
+def _parse_json(response: requests.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+def _receipt_of(response: requests.Response) -> Any:
+    header = response.headers.get("PAYMENT-RESPONSE")
+    if not header:
+        return None
+    try:
+        return decode_payment_response_header(header)
+    except ValueError:
+        return None
+
+
+def _price_guard_refusal(error: BaseException) -> PriceGuardError | None:
+    """The PriceGuardError inside an x402 PaymentError chain, if there is one."""
+    current: BaseException | None = error
+    while current is not None:
+        if isinstance(current, PriceGuardError):
+            return current
+        current = current.__cause__ or current.__context__
+    return None
+
+
+def _challenge_guard(max_atomic: int, max_price_usd: float, pay_to: str | None) -> Callable[[Any], None]:
+    """Checks every option of a 402 challenge before the x402 client selects or signs anything.
+
+    Runs as an on_payment_required hook. It refuses a challenge with no acceptable option, the same way the
+    TypeScript client does. Any exception it raises reaches the caller wrapped in PaymentError, which
+    _price_guard_refusal unwraps.
+    """
+
+    def check(context: Any) -> None:
+        required = context.payment_required
+        reasons: list[str] = []
+        if required.x402_version != 2:
+            reasons.append(f"x402Version {required.x402_version} is not 2")
+        options = list(required.accepts or [])
+        problems = [requirement_problem(option, max_atomic, pay_to) for option in options]
+        if not options:
+            reasons.append("the challenge offers no payment option")
+        elif all(problem is not None for problem in problems):
+            reasons.extend(problem for problem in problems if problem is not None)
+        if reasons:
+            raise PriceGuardError(reasons, max_price_usd)
+
+    return check
+
+
+def _paying_session(account: Any, max_atomic: int, max_price_usd: float, pay_to: str | None) -> requests.Session:
+    config = x402ClientConfig(
+        schemes=[SchemeRegistration(network=BASE_NETWORK, client=ExactEvmScheme(account))],
+        policies=[guard_policy(max_atomic, max_price_usd, pay_to)],
+        # The price guard is the only spend control. It is stricter (Base USDC only, at most max_price_usd),
+        # and the payment layer's default-asset check would refuse the same requirements with a vaguer error.
+        spend_controls=False,
+    )
+    http_client = x402HTTPClientSync(x402ClientSync.from_config(config)).on_payment_required(
+        _challenge_guard(max_atomic, max_price_usd, pay_to)
+    )
+    return wrapRequestsWithPayment(requests.Session(), http_client)

duo_data_utilities/_version.py

@@ -0,0 +1,12 @@
+"""The package version and the User-Agent, both read from the installed package metadata (pyproject.toml)."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("duo-data-utilities")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0+unknown"
+
+USER_AGENT = f"duo-data-utilities-py/{__version__} (+https://github.com/hiesem/duo-data-utilities)"

duo_data_utilities/client.py

@@ -0,0 +1,150 @@
+"""Client for https://api.duoleads.com. Each call costs $0.05 (x402 v2, USDC on Base)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+import requests
+from x402.http.clients.requests import PaymentError
+
+from ._http import (
+    _paying_session,
+    _parse_json,
+    _price_guard_refusal,
+    _query,
+    _receipt_of,
+    assert_route_path,
+    normalise_base_url,
+)
+from ._version import USER_AGENT
+from .counterparty import CounterpartyResult, run_counterparty_check
+from .derivs import DEFAULT_DERIVS_BASE_URL, DerivsClient
+from .errors import DuoApiError
+from .generated import DuoMethods
+from .price_guard import DEFAULT_MAX_PRICE_USD, DEFAULT_PAY_TO, usd_to_atomic
+
+DEFAULT_BASE_URL = "https://api.duoleads.com"
+
+
+@dataclass(frozen=True)
+class PaidResult:
+    """A route's result with the response meta and the settlement receipt (None when the header is absent)."""
+
+    data: dict[str, Any]
+    meta: dict[str, Any]
+    receipt: Any
+
+
+def _api_error(path: str, response: requests.Response, body: Any) -> DuoApiError:
+    status = response.status_code
+    meta = body.get("meta") if isinstance(body, dict) else None
+    request_id = meta.get("request_id") if isinstance(meta, dict) and isinstance(meta.get("request_id"), str) else None
+    if isinstance(body, dict) and body.get("ok") is False and isinstance(body.get("error"), dict):
+        error = body["error"]
+        return DuoApiError(
+            code=str(error.get("code") or "UNKNOWN_ERROR"),
+            message=str(error.get("message") or f"{path} failed with HTTP {status}"),
+            param=error.get("param") if isinstance(error.get("param"), str) else None,
+            expected=error.get("expected") if isinstance(error.get("expected"), str) else None,
+            status=status,
+            route=path,
+            request_id=request_id,
+        )
+    if status == 402:
+        return DuoApiError(
+            code="PAYMENT_REQUIRED",
+            message="the payment was not accepted (HTTP 402)",
+            status=status,
+            route=path,
+            request_id=request_id,
+        )
+    if 200 <= status < 300:
+        return DuoApiError(
+            code="INVALID_RESPONSE",
+            message=f"{path} did not return a valid response envelope (HTTP {status})",
+            status=status,
+            route=path,
+            request_id=request_id,
+        )
+    return DuoApiError(code=f"HTTP_{status}", message=f"{path} failed with HTTP {status}", status=status, route=path, request_id=request_id)
+
+
+
+class DuoClient(DuoMethods):
+    """Typed methods for every route, plus call, call_with_receipt and check_counterparty.
+
+    Pass `account` (an eth_account LocalAccount, or any object implementing x402's ClientEvmSigner) to pay
+    with your wallet. The client refuses any price above `max_price_usd`, and any payee other than `pay_to`
+    (default: the service's public address; None accepts any), before it signs. Pass `session`
+    instead to use a requests.Session that already pays; the price guard cannot check payments made inside it.
+    Every request carries `user_agent` (default USER_AGENT, naming the SDK and its version); to append your own
+    product, pass f"{USER_AGENT} my-agent/1.0".
+
+    `derivs` is a DerivsClient for https://derivs.duoleads.com (crypto derivatives data, $0.003 or $0.005 per
+    call) on the same wallet or session, with its own price cap `derivs_max_price_usd` (default: each route's own
+    listed price).
+    """
+
+    def __init__(
+        self,
+        account: Any = None,
+        *,
+        session: requests.Session | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        max_price_usd: float = DEFAULT_MAX_PRICE_USD,
+        timeout: float | None = None,
+        pay_to: str | None = DEFAULT_PAY_TO,
+        user_agent: str = USER_AGENT,
+        derivs_base_url: str = DEFAULT_DERIVS_BASE_URL,
+        derivs_max_price_usd: float | None = None,
+    ) -> None:
+        if (account is None) == (session is None):
+            raise TypeError("pass exactly one of account (pays with your wallet) or session (a requests.Session that already pays)")
+        if "\r" in user_agent or "\n" in user_agent:
+            raise ValueError("user_agent must not contain line breaks")
+        max_atomic = usd_to_atomic(max_price_usd)
+        self._user_agent = user_agent
+        self._base_url = normalise_base_url(base_url)
+        self._max_price_usd = max_price_usd
+        self._timeout = timeout
+        self._session = session if session is not None else _paying_session(account, max_atomic, max_price_usd, pay_to)
+        super().__init__(self.call)
+        self.derivs = DerivsClient(
+            account if session is None else None,
+            session=session,
+            base_url=derivs_base_url,
+            max_price_usd=derivs_max_price_usd,
+            timeout=timeout,
+            pay_to=pay_to,
+            user_agent=user_agent,
+        )
+
+    def call(self, path: str, params: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        """Calls any route by path and returns its `data` object. Costs $0.05 per call."""
+        return self.call_with_receipt(path, params).data
+
+    def call_with_receipt(self, path: str, params: Mapping[str, Any] | None = None) -> PaidResult:
+        """Like `call`, and also returns the response meta and the settlement receipt."""
+        assert_route_path(path)
+        try:
+            response = self._session.get(
+                f"{self._base_url}{path}",
+                params=_query(params or {}),
+                headers={"accept": "application/json", "User-Agent": self._user_agent},
+                timeout=self._timeout,
+            )
+        except PaymentError as error:
+            refusal = _price_guard_refusal(error)
+            if refusal is not None:
+                raise refusal from error
+            raise
+        body = _parse_json(response)
+        if 200 <= response.status_code < 300 and isinstance(body, dict) and body.get("ok") is True and "data" in body:
+            meta = body.get("meta")
+            return PaidResult(data=body["data"], meta=meta if isinstance(meta, dict) else {}, receipt=_receipt_of(response))
+        raise _api_error(path, response, body)
+
+    def check_counterparty(self, *, iban: str, country: str, tax_id_type: str, tax_id: str) -> CounterpartyResult:
+        """Runs IBAN, tax ID and country checks: three calls, $0.15. Structure and checksum only."""
+        return run_counterparty_check(self, iban=iban, country=country, tax_id_type=tax_id_type, tax_id=tax_id)

duo_data_utilities/counterparty.py

@@ -0,0 +1,118 @@
+"""Counterparty check: IBAN, tax ID and country in one verdict. Mirrors src/counterparty.ts."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from .errors import DuoApiError
+
+Status = Literal["pass", "fail", "review"]
+
+INPUT_PROBLEM_CODES = frozenset({"MISSING_PARAM", "INVALID_PARAM", "INPUT_TOO_LARGE"})
+NOT_COVERED_CODES = frozenset({"UNSUPPORTED_VALUE"})
+
+
+@dataclass(frozen=True)
+class CounterpartyCheck:
+    """One check. `check` is one of iban, tax_id, country or country_match (no route for the last)."""
+
+    check: str
+    route: str | None
+    status: Status
+    detail: str
+
+
+@dataclass(frozen=True)
+class CounterpartyResult:
+    """`verdict` is fail if any check failed, else review if any check could not run or the countries differ, else pass."""
+
+    verdict: Status
+    checks: list[CounterpartyCheck] = field(default_factory=list)
+    reasons: list[str] = field(default_factory=list)
+
+
+def _text(value: Any, name: str) -> str:
+    if not isinstance(value, str) or value.strip() == "":
+        raise TypeError(f"{name} must be a non-empty string")
+    return value.strip()
+
+
+def _country(value: Any) -> str:
+    code = _text(value, "country").upper()
+    if not re.fullmatch(r"[A-Z]{2}", code):
+        raise ValueError("country must be an ISO 3166-1 alpha-2 code, e.g. NL")
+    return "GB" if code == "UK" else code
+
+
+def _problem_check(check: str, route: str, problem: DuoApiError) -> CounterpartyCheck:
+    status: Status = "review" if problem.code in NOT_COVERED_CODES else "fail"
+    return CounterpartyCheck(check=check, route=route, status=status, detail=f"{problem.message} ({problem.code})")
+
+
+def run_counterparty_check(api: Any, *, iban: str, country: str, tax_id_type: str, tax_id: str) -> CounterpartyResult:
+    """Runs the three checks in order (three calls, $0.15) and combines them. Inputs are validated before any call."""
+    iban = _text(iban, "iban")
+    country = _country(country)
+    tax_id_type = _text(tax_id_type, "tax_id_type")
+    tax_id = _text(tax_id, "tax_id")
+    checks: list[CounterpartyCheck] = []
+
+    iban_route = "/v1/id/iban"
+    iban_country: str | None = None
+    try:
+        iban_data = api.iban.validate(iban=iban)
+    except DuoApiError as problem:
+        if problem.code not in INPUT_PROBLEM_CODES | NOT_COVERED_CODES:
+            raise
+        checks.append(_problem_check("iban", iban_route, problem))
+    else:
+        if iban_data["valid"]:
+            iban_country = str(iban_data["country"]).upper()
+            checks.append(CounterpartyCheck("iban", iban_route, "pass", f"IBAN checksum valid ({iban_country})"))
+        else:
+            checks.append(CounterpartyCheck("iban", iban_route, "fail", f"IBAN invalid: {iban_data.get('reason') or 'unknown reason'}"))
+
+    tax_route = "/v1/id/national"
+    try:
+        tax_data = api.tax_id.validate(country=country, kind=tax_id_type, value=tax_id)
+    except DuoApiError as problem:
+        if problem.code not in INPUT_PROBLEM_CODES | NOT_COVERED_CODES:
+            raise
+        checks.append(_problem_check("tax_id", tax_route, problem))
+    else:
+        if tax_data["valid"]:
+            checks.append(CounterpartyCheck("tax_id", tax_route, "pass", f"{tax_id_type} checksum valid for {country}"))
+        else:
+            checks.append(
+                CounterpartyCheck("tax_id", tax_route, "fail", f"{tax_id_type} invalid for {country}: {tax_data.get('reason') or 'unknown reason'}")
+            )
+
+    country_route = "/v1/ref/country"
+    try:
+        country_data = api.country.lookup(code=country)
+    except DuoApiError as problem:
+        if problem.code not in INPUT_PROBLEM_CODES | NOT_COVERED_CODES:
+            raise
+        checks.append(_problem_check("country", country_route, problem))
+    else:
+        if country_data["found"] and country_data.get("kind") == "country":
+            checks.append(CounterpartyCheck("country", country_route, "pass", f"{country} is an ISO 3166-1 country"))
+        else:
+            checks.append(CounterpartyCheck("country", country_route, "fail", f"{country} is not an ISO 3166-1 country code"))
+
+    if iban_country is not None and iban_country != country:
+        checks.append(
+            CounterpartyCheck(
+                "country_match",
+                None,
+                "review",
+                f"IBAN country {iban_country} differs from the tax ID country {country}",
+            )
+        )
+
+    statuses = [check.status for check in checks]
+    verdict: Status = "fail" if "fail" in statuses else "review" if "review" in statuses else "pass"
+    reasons = [check.detail for check in checks if check.status != "pass"]
+    return CounterpartyResult(verdict=verdict, checks=checks, reasons=reasons)

duo_data_utilities/derivs.py

@@ -0,0 +1,165 @@
+"""Client for https://derivs.duoleads.com: crypto derivatives data, paid per call over x402 (USDC on Base).
+
+Perp funding rates, funding history and arbitrage, a perp screener, open interest, futures basis, implied
+volatility, liquidations, order book depth and a one-call snapshot, across Bybit, Hyperliquid, dYdX, Gate,
+Kraken, Bitfinex, Deribit and OKX. $0.003 or $0.005 per call. Mirrors src/derivs.ts.
+
+Differences from the main API handled here: paths are /v1/<name> (one segment), a 200 answer is the data
+object itself (no {ok, data, meta} envelope), and an error answer is {"error": {...}, "request_id": ...}.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+import requests
+from x402.http.clients.requests import PaymentError
+
+from ._http import _parse_json, _paying_session, _price_guard_refusal, _receipt_of, normalise_base_url
+from ._version import USER_AGENT
+from .derivs_generated import DERIVS_ROUTES, DerivsMethods
+from .errors import DuoApiError
+from .price_guard import DEFAULT_PAY_TO, usd_to_atomic
+
+DEFAULT_DERIVS_BASE_URL = "https://derivs.duoleads.com"
+# The cap for a path the client does not know (the most expensive derivs route costs $0.005). Every listed route
+# is capped by default at its own price, $0.003 or $0.005.
+DEFAULT_DERIVS_MAX_PRICE_USD = 0.005
+# Default cap per path when the caller passed no max_price_usd: each route's own price.
+_ROUTE_CAP_USD: dict[str, float] = {r["path"]: float(r["price_usd"]) for r in DERIVS_ROUTES}
+# Paid MCP endpoint (Streamable HTTP; payment in params._meta["x402/payment"]).
+DERIVS_MCP_URL = "https://derivs.duoleads.com/mcp"
+
+
+@dataclass(frozen=True)
+class DerivsPaidResult:
+    """A derivs answer (its JSON body) with the settlement receipt (None when the header is absent)."""
+
+    data: dict[str, Any]
+    receipt: Any
+
+
+def assert_derivs_path(path: str) -> None:
+    if not re.fullmatch(r"/v1/[a-z0-9-]+", path):
+        raise ValueError(f"not a derivs route path: {path!r} (expected /v1/<name>)")
+
+
+def derivs_query_value(name: str, value: Any) -> str:
+    """A query value as the derivs API reads it: numbers as plain decimals (no exponent, at most 8 decimals)."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise TypeError(f"parameter {name} must be a finite number")
+        if value.is_integer():
+            return str(int(value))
+        return f"{value:.8f}".rstrip("0").rstrip(".")
+    if isinstance(value, str):
+        return value
+    raise TypeError(f"parameter {name} must be a string, number or boolean")
+
+
+def derivs_query(params: Mapping[str, Any]) -> dict[str, str]:
+    return {name: derivs_query_value(name, value) for name, value in params.items() if value is not None}
+
+
+def _derivs_error(path: str, response: requests.Response, body: Any) -> DuoApiError:
+    status = response.status_code
+    request_id = body.get("request_id") if isinstance(body, dict) and isinstance(body.get("request_id"), str) else None
+    if isinstance(body, dict) and isinstance(body.get("error"), dict):
+        error = body["error"]
+        return DuoApiError(
+            code=str(error.get("code") or "UNKNOWN_ERROR"),
+            message=str(error.get("message") or f"{path} failed with HTTP {status}"),
+            param=error.get("param") if isinstance(error.get("param"), str) else None,
+            expected=error.get("expected") if isinstance(error.get("expected"), str) else None,
+            status=status,
+            route=path,
+            request_id=request_id,
+        )
+    if status == 402:
+        return DuoApiError(code="PAYMENT_REQUIRED", message="the payment was not accepted (HTTP 402)", status=status, route=path, request_id=request_id)
+    if 200 <= status < 300:
+        return DuoApiError(code="INVALID_RESPONSE", message=f"{path} did not return a JSON object (HTTP {status})", status=status, route=path, request_id=request_id)
+    return DuoApiError(code=f"HTTP_{status}", message=f"{path} failed with HTTP {status}", status=status, route=path, request_id=request_id)
+
+
+class DerivsClient(DerivsMethods):
+    """Typed methods for the 10 derivs routes, plus call and call_with_receipt.
+
+    Pass `account` to pay with your wallet; the client refuses any price above `max_price_usd` (by default
+    each route's own listed price, $0.003 or $0.005, and 0.005 for a path it does not know; pass 0.003 to
+    refuse the $0.005 routes), any network but Base, any asset but USDC and any payee but `pay_to`, before
+    it signs. Pass `session` instead to use a requests.Session that already pays.
+    `DuoClient(...).derivs` is the same client, sharing the wallet with the main API.
+    """
+
+    def __init__(
+        self,
+        account: Any = None,
+        *,
+        session: requests.Session | None = None,
+        base_url: str = DEFAULT_DERIVS_BASE_URL,
+        max_price_usd: float | None = None,
+        timeout: float | None = None,
+        pay_to: str | None = DEFAULT_PAY_TO,
+        user_agent: str = USER_AGENT,
+    ) -> None:
+        if (account is None) == (session is None):
+            raise TypeError("pass exactly one of account (pays with your wallet) or session (a requests.Session that already pays)")
+        if "\r" in user_agent or "\n" in user_agent:
+            raise ValueError("user_agent must not contain line breaks")
+        if max_price_usd is not None:
+            usd_to_atomic(max_price_usd)  # validates it at construction
+        self._user_agent = user_agent
+        self._base_url = normalise_base_url(base_url)
+        self._max_price_usd = max_price_usd
+        self._timeout = timeout
+        self._account = account
+        self._pay_to = pay_to
+        self._session = session
+        # One paying session per price cap (at most one per distinct route price), built on first use.
+        self._sessions: dict[float, requests.Session] = {}
+        super().__init__(self.call)
+
+    def _cap_for(self, path: str) -> float:
+        if self._max_price_usd is not None:
+            return self._max_price_usd
+        return _ROUTE_CAP_USD.get(path, DEFAULT_DERIVS_MAX_PRICE_USD)
+
+    def _session_for(self, path: str) -> requests.Session:
+        if self._session is not None:
+            return self._session
+        cap = self._cap_for(path)
+        if cap not in self._sessions:
+            self._sessions[cap] = _paying_session(self._account, usd_to_atomic(cap), cap, self._pay_to)
+        return self._sessions[cap]
+
+    def call(self, path: str, params: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        """Calls any derivs route by path (e.g. /v1/funding-rates) and returns its JSON body."""
+        return self.call_with_receipt(path, params).data
+
+    def call_with_receipt(self, path: str, params: Mapping[str, Any] | None = None) -> DerivsPaidResult:
+        """Like `call`, and also returns the settlement receipt."""
+        assert_derivs_path(path)
+        try:
+            response = self._session_for(path).get(
+                f"{self._base_url}{path}",
+                params=derivs_query(params or {}),
+                headers={"accept": "application/json", "User-Agent": self._user_agent},
+                timeout=self._timeout,
+            )
+        except PaymentError as error:
+            refusal = _price_guard_refusal(error)
+            if refusal is not None:
+                raise refusal from error
+            raise
+        body = _parse_json(response)
+        if 200 <= response.status_code < 300 and isinstance(body, dict) and "error" not in body:
+            return DerivsPaidResult(data=body, receipt=_receipt_of(response))
+        raise _derivs_error(path, response, body)