morpho-blue-py 0.1.0__py3-none-any.whl

morpho_blue/__init__.py

@@ -0,0 +1,47 @@
+"""morpho-blue-py: a typed Python client for the Morpho Blue GraphQL API."""
+
+from __future__ import annotations
+
+from ._common import DEFAULT_ENDPOINT
+from .async_client import AsyncMorphoClient
+from .client import MorphoClient
+from .exceptions import GraphQLError, HTTPError, MorphoError
+from .models import (
+    Asset,
+    Chain,
+    Market,
+    MarketPosition,
+    MarketPositionState,
+    MarketState,
+    PageInfo,
+    User,
+    Vault,
+    VaultAllocation,
+    VaultPosition,
+    VaultPositionState,
+    VaultState,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_ENDPOINT",
+    "AsyncMorphoClient",
+    "MorphoClient",
+    "GraphQLError",
+    "HTTPError",
+    "MorphoError",
+    "Asset",
+    "Chain",
+    "Market",
+    "MarketPosition",
+    "MarketPositionState",
+    "MarketState",
+    "PageInfo",
+    "User",
+    "Vault",
+    "VaultAllocation",
+    "VaultPosition",
+    "VaultPositionState",
+    "VaultState",
+]

morpho_blue/_common.py

@@ -0,0 +1,166 @@
+"""Shared, transport-agnostic helpers used by both sync and async clients."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .exceptions import GraphQLError, HTTPError
+from .models import Market, User, Vault
+
+DEFAULT_ENDPOINT = "https://blue-api.morpho.org/graphql"
+
+# Map a friendly "field" name to the API's MarketOrderBy enum value.
+MARKET_ORDER_BY = {
+    "supply_apy": "SupplyApy",
+    "borrow_apy": "BorrowApy",
+    "net_supply_apy": "NetSupplyApy",
+    "net_borrow_apy": "NetBorrowApy",
+    "supply_assets_usd": "SupplyAssetsUsd",
+    "borrow_assets_usd": "BorrowAssetsUsd",
+    "total_liquidity_usd": "TotalLiquidityUsd",
+    "utilization": "Utilization",
+    "lltv": "Lltv",
+}
+
+VAULT_ORDER_BY = {
+    "apy": "Apy",
+    "net_apy": "NetApy",
+    "total_assets": "TotalAssets",
+    "total_assets_usd": "TotalAssetsUsd",
+    "fee": "Fee",
+    "name": "Name",
+}
+
+
+def parse_response(payload: dict[str, Any]) -> dict[str, Any]:
+    """Validate a GraphQL JSON payload and return its ``data`` object.
+
+    Raises :class:`GraphQLError` if the payload carries an ``errors`` array.
+    """
+    errors = payload.get("errors")
+    if errors:
+        raise GraphQLError(errors)
+    data = payload.get("data")
+    if data is None:
+        raise GraphQLError([{"message": "Response contained no data"}])
+    assert isinstance(data, dict)
+    return data
+
+
+def check_status(status_code: int, text: str) -> None:
+    """Raise :class:`HTTPError` for any non-2xx response."""
+    if status_code < 200 or status_code >= 300:
+        raise HTTPError(status_code, text)
+
+
+def build_market_variables(
+    *,
+    first: Optional[int],
+    skip: Optional[int],
+    chain_id: Optional[int],
+    order_by: Optional[str],
+    order_direction: str,
+    where: Optional[dict[str, Any]],
+) -> dict[str, Any]:
+    """Build the GraphQL variables for a ``markets`` query.
+
+    Merges ``chain_id`` into the ``where`` filters as ``chainId_in`` and maps a
+    friendly ``order_by`` key to its ``MarketOrderBy`` enum value (passing
+    through any value not in :data:`MARKET_ORDER_BY`).
+
+    Returns:
+        The ``{"first", "skip", "orderDirection", "where", "orderBy"?}`` variables
+        dict ready to send to the API.
+    """
+    filters: dict[str, Any] = dict(where or {})
+    if chain_id is not None:
+        filters.setdefault("chainId_in", [chain_id])
+    variables: dict[str, Any] = {
+        "first": first,
+        "skip": skip,
+        "orderDirection": order_direction,
+        "where": filters or None,
+    }
+    if order_by is not None:
+        variables["orderBy"] = MARKET_ORDER_BY.get(order_by, order_by)
+    return variables
+
+
+def build_vault_variables(
+    *,
+    first: Optional[int],
+    skip: Optional[int],
+    chain_id: Optional[int],
+    order_by: Optional[str],
+    order_direction: str,
+    where: Optional[dict[str, Any]],
+) -> dict[str, Any]:
+    """Build the GraphQL variables for a ``vaults`` query.
+
+    Merges ``chain_id`` into the ``where`` filters as ``chainId_in`` and maps a
+    friendly ``order_by`` key to its ``VaultOrderBy`` enum value (passing through
+    any value not in :data:`VAULT_ORDER_BY`).
+
+    Returns:
+        The ``{"first", "skip", "orderDirection", "where", "orderBy"?}`` variables
+        dict ready to send to the API.
+    """
+    filters: dict[str, Any] = dict(where or {})
+    if chain_id is not None:
+        filters.setdefault("chainId_in", [chain_id])
+    variables: dict[str, Any] = {
+        "first": first,
+        "skip": skip,
+        "orderDirection": order_direction,
+        "where": filters or None,
+    }
+    if order_by is not None:
+        variables["orderBy"] = VAULT_ORDER_BY.get(order_by, order_by)
+    return variables
+
+
+def markets_from_data(data: dict[str, Any]) -> list[Market]:
+    """Parse the ``markets.items`` of a response into :class:`Market` objects.
+
+    Returns:
+        The parsed markets (an empty list when the page has no items).
+    """
+    items = data["markets"]["items"] or []
+    return [Market.model_validate(item) for item in items]
+
+
+def vaults_from_data(data: dict[str, Any]) -> list[Vault]:
+    """Parse the ``vaults.items`` of a response into :class:`Vault` objects.
+
+    Returns:
+        The parsed vaults (an empty list when the page has no items).
+    """
+    items = data["vaults"]["items"] or []
+    return [Vault.model_validate(item) for item in items]
+
+
+def market_from_data(data: dict[str, Any]) -> Market:
+    """Parse the ``marketById`` field of a response into a :class:`Market`.
+
+    Returns:
+        The parsed single market.
+    """
+    return Market.model_validate(data["marketById"])
+
+
+def vault_from_data(data: dict[str, Any]) -> Vault:
+    """Parse the ``vaultByAddress`` field of a response into a :class:`Vault`.
+
+    Returns:
+        The parsed single vault.
+    """
+    return Vault.model_validate(data["vaultByAddress"])
+
+
+def user_from_data(data: dict[str, Any]) -> User:
+    """Parse the ``userByAddress`` field of a response into a :class:`User`.
+
+    Returns:
+        The parsed user with their market and vault positions.
+    """
+    return User.model_validate(data["userByAddress"])

morpho_blue/async_client.py

@@ -0,0 +1,377 @@
+"""Asynchronous Morpho Blue GraphQL client (httpx.AsyncClient)."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any, Optional
+
+import httpx
+
+from . import queries
+from ._common import (
+    DEFAULT_ENDPOINT,
+    build_market_variables,
+    build_vault_variables,
+    check_status,
+    market_from_data,
+    markets_from_data,
+    parse_response,
+    user_from_data,
+    vault_from_data,
+    vaults_from_data,
+)
+from .client import DEFAULT_TIMEOUT
+from .models import Market, User, Vault
+
+
+class AsyncMorphoClient:
+    """An asyncio client for the Morpho Blue GraphQL API.
+
+    The async counterpart of :class:`~morpho_blue.client.MorphoClient`, exposing
+    the same methods as coroutines. Use it as an async context manager so the
+    underlying ``httpx.AsyncClient`` is closed automatically.
+
+    Example::
+
+        import asyncio
+        from morpho_blue import AsyncMorphoClient
+
+        async def main() -> None:
+            async with AsyncMorphoClient() as client:
+                markets = await client.top_markets_by_supply_apy(chain_id=1, limit=5)
+                for m in markets:
+                    if m.loan_asset and m.state:
+                        print(m.loan_asset.symbol, m.state.supply_apy)
+
+        asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        endpoint: str = DEFAULT_ENDPOINT,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        headers: Optional[dict[str, str]] = None,
+        client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        """Create an async client.
+
+        Args:
+            endpoint: GraphQL endpoint URL. Defaults to the public Morpho Blue
+                API (:data:`~morpho_blue.DEFAULT_ENDPOINT`).
+            timeout: Per-request timeout in seconds. Ignored if ``client`` is
+                supplied.
+            headers: Extra HTTP headers merged into every request (on top of the
+                default ``Content-Type: application/json``).
+            client: A pre-configured ``httpx.AsyncClient`` to use. When provided,
+                the caller owns its lifecycle and :meth:`aclose` will not close
+                it; otherwise the client creates and owns one.
+        """
+        self.endpoint = endpoint
+        default_headers = {"Content-Type": "application/json"}
+        if headers:
+            default_headers.update(headers)
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(timeout=timeout, headers=default_headers)
+
+    # -- lifecycle -------------------------------------------------------
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client if this instance owns it.
+
+        A no-op when an external ``httpx.AsyncClient`` was passed to
+        :meth:`__init__`, since the caller is responsible for closing it.
+        """
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncMorphoClient:
+        """Enter the async context manager and return this client."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        """Exit the async context manager, closing the client via :meth:`aclose`."""
+        await self.aclose()
+
+    # -- low level -------------------------------------------------------
+    async def execute(
+        self, query: str, variables: Optional[dict[str, Any]] = None
+    ) -> dict[str, Any]:
+        """POST a raw GraphQL query and return its ``data`` object.
+
+        Args:
+            query: The GraphQL query document.
+            variables: Optional variables to bind into the query.
+
+        Returns:
+            The ``data`` object from the GraphQL response.
+
+        Raises:
+            HTTPError: If the endpoint returns a non-2xx HTTP status.
+            GraphQLError: If the response carries a GraphQL ``errors`` array
+                (the API returns HTTP 200 even for query errors).
+        """
+        response = await self._client.post(
+            self.endpoint, json={"query": query, "variables": variables or {}}
+        )
+        check_status(response.status_code, response.text)
+        return parse_response(response.json())
+
+    # -- markets ---------------------------------------------------------
+    async def get_markets(
+        self,
+        *,
+        chain_id: Optional[int] = None,
+        first: Optional[int] = 100,
+        skip: Optional[int] = 0,
+        order_by: Optional[str] = None,
+        order_direction: str = "Desc",
+        where: Optional[dict[str, Any]] = None,
+    ) -> list[Market]:
+        """Fetch a single page of markets, optionally filtered and sorted.
+
+        Args:
+            chain_id: Restrict to one chain (e.g. ``1`` for Ethereum). When set,
+                it is merged into ``where`` as ``chainId_in``. Omit for all chains.
+            first: Page size (max number of markets to return).
+            skip: Offset for pagination.
+            order_by: Sort field. Accepts a friendly key (``"supply_apy"``,
+                ``"supply_assets_usd"``, ``"utilization"``, ``"lltv"``, …) or a
+                raw ``MarketOrderBy`` enum value.
+            order_direction: ``"Desc"`` (default) or ``"Asc"``.
+            where: Additional raw ``MarketFilters`` (e.g.
+                ``{"utilization_lte": 0.99}``), merged with ``chain_id``.
+
+        Returns:
+            The page of markets as :class:`~morpho_blue.models.Market` objects.
+
+        Raises:
+            HTTPError: On a non-2xx HTTP status.
+            GraphQLError: If the API returns a GraphQL error.
+        """
+        variables = build_market_variables(
+            first=first,
+            skip=skip,
+            chain_id=chain_id,
+            order_by=order_by,
+            order_direction=order_direction,
+            where=where,
+        )
+        data = await self.execute(queries.MARKETS_QUERY, variables)
+        return markets_from_data(data)
+
+    async def get_market(self, market_id: str, *, chain_id: int) -> Market:
+        """Fetch a single market by its ``marketId`` (the unique key).
+
+        Args:
+            market_id: The market's unique key (0x-prefixed 32-byte hash). Note
+                the Morpho schema uses ``marketId``, not ``uniqueKey``.
+            chain_id: The chain the market lives on (required for this lookup).
+
+        Returns:
+            The :class:`~morpho_blue.models.Market`.
+
+        Raises:
+            HTTPError: On a non-2xx HTTP status.
+            GraphQLError: If the market is not found or the API errors.
+        """
+        data = await self.execute(
+            queries.MARKET_BY_ID_QUERY,
+            {"marketId": market_id, "chainId": chain_id},
+        )
+        return market_from_data(data)
+
+    async def top_markets_by_supply_apy(
+        self,
+        *,
+        chain_id: Optional[int] = None,
+        limit: int = 10,
+        where: Optional[dict[str, Any]] = None,
+    ) -> list[Market]:
+        """Return the ``limit`` markets with the highest supply APY.
+
+        Sorts by raw supply APY descending, which can surface tiny, fully
+        utilized markets whose instantaneous rate spikes; pass
+        ``where={"utilization_lte": 0.99}`` to exclude them.
+
+        Args:
+            chain_id: Restrict to one chain, or omit for all chains.
+            limit: How many markets to return.
+            where: Additional raw ``MarketFilters`` to apply.
+
+        Returns:
+            Up to ``limit`` markets ordered by descending supply APY.
+
+        Raises:
+            HTTPError: On a non-2xx HTTP status.
+            GraphQLError: If the API returns a GraphQL error.
+        """
+        return await self.get_markets(
+            chain_id=chain_id,
+            first=limit,
+            order_by="supply_apy",
+            order_direction="Desc",
+            where=where,
+        )
+
+    async def iter_markets(
+        self,
+        *,
+        chain_id: Optional[int] = None,
+        page_size: int = 100,
+        order_by: Optional[str] = None,
+        order_direction: str = "Desc",
+        where: Optional[dict[str, Any]] = None,
+    ) -> list[Market]:
+        """Fetch *all* matching markets, paginating automatically via ``skip``.
+
+        Repeatedly requests pages of ``page_size`` until a short page signals the
+        end, accumulating every market into one list.
+
+        Args:
+            chain_id: Restrict to one chain, or omit for all chains.
+            page_size: Number of markets requested per underlying page.
+            order_by: Sort field (see :meth:`get_markets`).
+            order_direction: ``"Desc"`` (default) or ``"Asc"``.
+            where: Additional raw ``MarketFilters`` to apply.
+
+        Returns:
+            Every matching market across all pages.
+
+        Raises:
+            HTTPError: On a non-2xx HTTP status.
+            GraphQLError: If the API returns a GraphQL error.
+        """
+        out: list[Market] = []
+        skip = 0
+        while True:
+            page = await self.get_markets(
+                chain_id=chain_id,
+                first=page_size,
+                skip=skip,
+                order_by=order_by,
+                order_direction=order_direction,
+                where=where,
+            )
+            out.extend(page)
+            if len(page) < page_size:
+                break
+            skip += page_size
+        return out
+
+    # -- vaults ----------------------------------------------------------
+    async def get_vaults(
+        self,
+        *,
+        chain_id: Optional[int] = None,
+        first: Optional[int] = 100,
+        skip: Optional[int] = 0,
+        order_by: Optional[str] = None,
+        order_direction: str = "Desc",
+        where: Optional[dict[str, Any]] = None,
+    ) -> list[Vault]:
+        """Fetch a single page of MetaMorpho vaults, optionally filtered/sorted.
+
+        Args:
+            chain_id: Restrict to one chain, or omit for all chains.
+            first: Page size (max number of vaults to return).
+            skip: Offset for pagination.
+            order_by: Sort field. Accepts a friendly key (``"net_apy"``,
+                ``"total_assets_usd"``, ``"apy"``, ``"fee"``, …) or a raw
+                ``VaultOrderBy`` enum value.
+            order_direction: ``"Desc"`` (default) or ``"Asc"``.
+            where: Additional raw ``VaultFilters`` to apply.
+
+        Returns:
+            The page of vaults as :class:`~morpho_blue.models.Vault` objects.
+
+        Raises:
+            HTTPError: On a non-2xx HTTP status.
+            GraphQLError: If the API returns a GraphQL error.
+        """
+        variables = build_vault_variables(
+            first=first,
+            skip=skip,
+            chain_id=chain_id,
+            order_by=order_by,
+            order_direction=order_direction,
+            where=where,
+        )
+        data = await self.execute(queries.VAULTS_QUERY, variables)
+        return vaults_from_data(data)
+
+    async def get_vault(self, address: str, *, chain_id: Optional[int] = None) -> Vault:
+        """Fetch a single vault by its contract ``address``.
+
+        Args:
+            address: The vault contract address.
+            chain_id: The chain the vault lives on; recommended to disambiguate
+                the same address across chains.
+
+        Returns:
+            The :class:`~morpho_blue.models.Vault`.
+
+        Raises:
+            HTTPError: On a non-2xx HTTP status.
+            GraphQLError: If the vault is not found or the API errors.
+        """
+        data = await self.execute(
+            queries.VAULT_BY_ADDRESS_QUERY,
+            {"address": address, "chainId": chain_id},
+        )
+        return vault_from_data(data)
+
+    async def top_vaults_by_apy(
+        self,
+        *,
+        chain_id: Optional[int] = None,
+        limit: int = 10,
+        where: Optional[dict[str, Any]] = None,
+    ) -> list[Vault]:
+        """Return the ``limit`` vaults with the highest net APY.
+
+        Args:
+            chain_id: Restrict to one chain, or omit for all chains.
+            limit: How many vaults to return.
+            where: Additional raw ``VaultFilters`` to apply.
+
+        Returns:
+            Up to ``limit`` vaults ordered by descending net APY.
+
+        Raises:
+            HTTPError: On a non-2xx HTTP status.
+            GraphQLError: If the API returns a GraphQL error.
+        """
+        return await self.get_vaults(
+            chain_id=chain_id,
+            first=limit,
+            order_by="net_apy",
+            order_direction="Desc",
+            where=where,
+        )
+
+    # -- users / positions ----------------------------------------------
+    async def get_user(self, address: str, *, chain_id: Optional[int] = None) -> User:
+        """Fetch a wallet's market and vault positions by ``address``.
+
+        Args:
+            address: The wallet address to look up.
+            chain_id: The chain to read positions on; recommended.
+
+        Returns:
+            A :class:`~morpho_blue.models.User` with ``market_positions`` and
+            ``vault_positions``.
+
+        Raises:
+            HTTPError: On a non-2xx HTTP status.
+            GraphQLError: If the API returns a GraphQL error.
+        """
+        data = await self.execute(
+            queries.USER_BY_ADDRESS_QUERY,
+            {"address": address, "chainId": chain_id},
+        )
+        return user_from_data(data)