duo-data-utilities 0.2.1__tar.gz

duo_data_utilities-0.2.1/LICENSE

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

duo_data_utilities-0.2.1/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: duo-data-utilities
+Version: 0.2.1
+Summary: IBAN, ISIN, VAT/tax ID and GTIN barcode validation plus 29 more pay-per-call utilities, and crypto derivatives data (perp funding rates, open interest, futures basis, implied volatility, liquidations, order book depth) for AI agents (x402, USDC on Base, no API key).
+Author: Duo Data Utilities
+License: MIT
+Project-URL: Homepage, https://api.duoleads.com
+Project-URL: Repository, https://github.com/hiesem/duo-data-utilities
+Keywords: iban,isin,vat,tax-id,gtin,barcode,x402,usdc,ai-agents,pay-per-call,mod-97,crypto-derivatives,perp,funding-rate,funding-arbitrage,open-interest,futures-basis,implied-volatility,liquidations,order-book,hyperliquid,trading-bot
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: x402[evm,requests]<3,>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# duo-data-utilities (Python)
+
+Typed Python client for https://api.duoleads.com: IBAN, ISIN, VAT/tax ID, GTIN barcode and 29 more pay-per-call utilities. Each call costs $0.05 in USDC on Base, paid with x402 v2. No API key, no signup.
+
+Also crypto derivatives data from https://derivs.duoleads.com, $0.003 or $0.005 per call: perp funding rates, funding history and arbitrage, perp screener, open interest, futures basis, implied volatility, liquidations and order book depth across Bybit, Hyperliquid, dYdX, Gate, Kraken, Bitfinex, Deribit and OKX. Use `DuoClient(account).derivs.funding_rates(coin="BTC")` or `DerivsClient(account)`; its price guard caps each route at its own listed price ($0.003 or $0.005) unless you pass `max_price_usd` (`derivs_max_price_usd` on `DuoClient`).
+
+```sh
+pip install "git+https://github.com/hiesem/duo-data-utilities#subdirectory=python"
+```
+
+The package is not published to PyPI. The full documentation, the method table and the price guard are in the repository README.
+
+The client sends a User-Agent naming the SDK and version (`duo-data-utilities-py/<version> (+https://github.com/hiesem/duo-data-utilities)`); the API stores only a coarse client class, see https://api.duoleads.com/privacy. Pass `user_agent=` to `DuoClient` to change it.

duo_data_utilities-0.2.1/README.md

@@ -0,0 +1,13 @@
+# duo-data-utilities (Python)
+
+Typed Python client for https://api.duoleads.com: IBAN, ISIN, VAT/tax ID, GTIN barcode and 29 more pay-per-call utilities. Each call costs $0.05 in USDC on Base, paid with x402 v2. No API key, no signup.
+
+Also crypto derivatives data from https://derivs.duoleads.com, $0.003 or $0.005 per call: perp funding rates, funding history and arbitrage, perp screener, open interest, futures basis, implied volatility, liquidations and order book depth across Bybit, Hyperliquid, dYdX, Gate, Kraken, Bitfinex, Deribit and OKX. Use `DuoClient(account).derivs.funding_rates(coin="BTC")` or `DerivsClient(account)`; its price guard caps each route at its own listed price ($0.003 or $0.005) unless you pass `max_price_usd` (`derivs_max_price_usd` on `DuoClient`).
+
+```sh
+pip install "git+https://github.com/hiesem/duo-data-utilities#subdirectory=python"
+```
+
+The package is not published to PyPI. The full documentation, the method table and the price guard are in the repository README.
+
+The client sends a User-Agent naming the SDK and version (`duo-data-utilities-py/<version> (+https://github.com/hiesem/duo-data-utilities)`); the API stores only a coarse client class, see https://api.duoleads.com/privacy. Pass `user_agent=` to `DuoClient` to change it.

duo_data_utilities-0.2.1/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-0.2.1/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-0.2.1/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-0.2.1/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-0.2.1/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)