API reference

`morpho_blue`

morpho-blue-py: a typed Python client for the Morpho Blue GraphQL API.

`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())

`init(endpoint=DEFAULT_ENDPOINT, *, timeout=DEFAULT_TIMEOUT, headers=None, client=None)`

Create an async client.

Parameters:

Name	Type	Description	Default
`endpoint`	`str`	GraphQL endpoint URL. Defaults to the public Morpho Blue API (:data:`~morpho_blue.DEFAULT_ENDPOINT`).	`DEFAULT_ENDPOINT`
`timeout`	`float`	Per-request timeout in seconds. Ignored if `client` is supplied.	`DEFAULT_TIMEOUT`
`headers`	`Optional[dict[str, str]]`	Extra HTTP headers merged into every request (on top of the default `Content-Type: application/json`).	`None`
`client`	`Optional[AsyncClient]`	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.	`None`

`aclose()` `async`

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.

`aenter()` `async`

Enter the async context manager and return this client.

`aexit(exc_type, exc, tb)` `async`

Exit the async context manager, closing the client via :meth:aclose.

`execute(query, variables=None)` `async`

POST a raw GraphQL query and return its data object.

Parameters:

Name	Type	Description	Default
`query`	`str`	The GraphQL query document.	required
`variables`	`Optional[dict[str, Any]]`	Optional variables to bind into the query.	`None`

Returns:

Type	Description
`dict[str, Any]`	The `data` object from the GraphQL response.

Raises:

Type	Description
`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).

`get_markets(*, chain_id=None, first=100, skip=0, order_by=None, order_direction='Desc', where=None)` `async`

Fetch a single page of markets, optionally filtered and sorted.

Parameters:

Name	Type	Description	Default
`chain_id`	`Optional[int]`	Restrict to one chain (e.g. `1` for Ethereum). When set, it is merged into `where` as `chainId_in`. Omit for all chains.	`None`
`first`	`Optional[int]`	Page size (max number of markets to return).	`100`
`skip`	`Optional[int]`	Offset for pagination.	`0`
`order_by`	`Optional[str]`	Sort field. Accepts a friendly key (`"supply_apy"`, `"supply_assets_usd"`, `"utilization"`, `"lltv"`, …) or a raw `MarketOrderBy` enum value.	`None`
`order_direction`	`str`	`"Desc"` (default) or `"Asc"`.	`'Desc'`
`where`	`Optional[dict[str, Any]]`	Additional raw `MarketFilters` (e.g. `{"utilization_lte": 0.99}`), merged with `chain_id`.	`None`

Returns:

Type	Description
`list[Market]`	The page of markets as :class:`~morpho_blue.models.Market` objects.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the API returns a GraphQL error.

`get_market(market_id, *, chain_id)` `async`

Fetch a single market by its marketId (the unique key).

Parameters:

Name	Type	Description	Default
`market_id`	`str`	The market's unique key (0x-prefixed 32-byte hash). Note the Morpho schema uses `marketId`, not `uniqueKey`.	required
`chain_id`	`int`	The chain the market lives on (required for this lookup).	required

Returns:

Name	Type	Description
`The`	`Market`	class:`~morpho_blue.models.Market`.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the market is not found or the API errors.

`top_markets_by_supply_apy(*, chain_id=None, limit=10, where=None)` `async`

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.

Parameters:

Name	Type	Description	Default
`chain_id`	`Optional[int]`	Restrict to one chain, or omit for all chains.	`None`
`limit`	`int`	How many markets to return.	`10`
`where`	`Optional[dict[str, Any]]`	Additional raw `MarketFilters` to apply.	`None`

Returns:

Type	Description
`list[Market]`	Up to `limit` markets ordered by descending supply APY.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the API returns a GraphQL error.

`iter_markets(*, chain_id=None, page_size=100, order_by=None, order_direction='Desc', where=None)` `async`

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.

Parameters:

Name	Type	Description	Default
`chain_id`	`Optional[int]`	Restrict to one chain, or omit for all chains.	`None`
`page_size`	`int`	Number of markets requested per underlying page.	`100`
`order_by`	`Optional[str]`	Sort field (see :meth:`get_markets`).	`None`
`order_direction`	`str`	`"Desc"` (default) or `"Asc"`.	`'Desc'`
`where`	`Optional[dict[str, Any]]`	Additional raw `MarketFilters` to apply.	`None`

Returns:

Type	Description
`list[Market]`	Every matching market across all pages.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the API returns a GraphQL error.

`get_vaults(*, chain_id=None, first=100, skip=0, order_by=None, order_direction='Desc', where=None)` `async`

Fetch a single page of MetaMorpho vaults, optionally filtered/sorted.

Parameters:

Name	Type	Description	Default
`chain_id`	`Optional[int]`	Restrict to one chain, or omit for all chains.	`None`
`first`	`Optional[int]`	Page size (max number of vaults to return).	`100`
`skip`	`Optional[int]`	Offset for pagination.	`0`
`order_by`	`Optional[str]`	Sort field. Accepts a friendly key (`"net_apy"`, `"total_assets_usd"`, `"apy"`, `"fee"`, …) or a raw `VaultOrderBy` enum value.	`None`
`order_direction`	`str`	`"Desc"` (default) or `"Asc"`.	`'Desc'`
`where`	`Optional[dict[str, Any]]`	Additional raw `VaultFilters` to apply.	`None`

Returns:

Type	Description
`list[Vault]`	The page of vaults as :class:`~morpho_blue.models.Vault` objects.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the API returns a GraphQL error.

`get_vault(address, *, chain_id=None)` `async`

Fetch a single vault by its contract address.

Parameters:

Name	Type	Description	Default
`address`	`str`	The vault contract address.	required
`chain_id`	`Optional[int]`	The chain the vault lives on; recommended to disambiguate the same address across chains.	`None`

Returns:

Name	Type	Description
`The`	`Vault`	class:`~morpho_blue.models.Vault`.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the vault is not found or the API errors.

`top_vaults_by_apy(*, chain_id=None, limit=10, where=None)` `async`

Return the limit vaults with the highest net APY.

Parameters:

Name	Type	Description	Default
`chain_id`	`Optional[int]`	Restrict to one chain, or omit for all chains.	`None`
`limit`	`int`	How many vaults to return.	`10`
`where`	`Optional[dict[str, Any]]`	Additional raw `VaultFilters` to apply.	`None`

Returns:

Type	Description
`list[Vault]`	Up to `limit` vaults ordered by descending net APY.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the API returns a GraphQL error.

`get_user(address, *, chain_id=None)` `async`

Fetch a wallet's market and vault positions by address.

Parameters:

Name	Type	Description	Default
`address`	`str`	The wallet address to look up.	required
`chain_id`	`Optional[int]`	The chain to read positions on; recommended.	`None`

Returns:

Name	Type	Description
`A`	`User`	class:`~morpho_blue.models.User` with `market_positions` and
	`User`	`vault_positions`.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the API returns a GraphQL error.

`MorphoClient`

A synchronous client for the Morpho Blue GraphQL API.

Example::

with MorphoClient() as client:
    markets = client.top_markets_by_supply_apy(chain_id=1, limit=5)
    for m in markets:
        print(m.loan_asset.symbol, m.state.supply_apy)

`init(endpoint=DEFAULT_ENDPOINT, *, timeout=DEFAULT_TIMEOUT, headers=None, client=None)`

Create a synchronous client.

Parameters:

Name	Type	Description	Default
`endpoint`	`str`	GraphQL endpoint URL. Defaults to the public Morpho Blue API (:data:`~morpho_blue.DEFAULT_ENDPOINT`).	`DEFAULT_ENDPOINT`
`timeout`	`float`	Per-request timeout in seconds. Ignored if `client` is supplied.	`DEFAULT_TIMEOUT`
`headers`	`Optional[dict[str, str]]`	Extra HTTP headers merged into every request (on top of the default `Content-Type: application/json`).	`None`
`client`	`Optional[Client]`	A pre-configured `httpx.Client` to use. When provided, the caller owns its lifecycle and :meth:`close` will not close it; otherwise the client creates and owns one.	`None`

`close()`

Close the underlying HTTP client if this instance owns it.

A no-op when an external httpx.Client was passed to :meth:__init__, since the caller is responsible for closing it.

`enter()`

Enter the context manager and return this client.

`exit(exc_type, exc, tb)`

Exit the context manager, closing the client via :meth:close.

`execute(query, variables=None)`

POST a raw GraphQL query and return its data object.

Parameters:

Name	Type	Description	Default
`query`	`str`	The GraphQL query document.	required
`variables`	`Optional[dict[str, Any]]`	Optional variables to bind into the query.	`None`

Returns:

Type	Description
`dict[str, Any]`	The `data` object from the GraphQL response.

Raises:

Type	Description
`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).

`get_markets(*, chain_id=None, first=100, skip=0, order_by=None, order_direction='Desc', where=None)`

Fetch a single page of markets, optionally filtered and sorted.

Parameters:

Name	Type	Description	Default
`chain_id`	`Optional[int]`	Restrict to one chain (e.g. `1` for Ethereum). When set, it is merged into `where` as `chainId_in`. Omit for all chains.	`None`
`first`	`Optional[int]`	Page size (max number of markets to return).	`100`
`skip`	`Optional[int]`	Offset for pagination.	`0`
`order_by`	`Optional[str]`	Sort field. Accepts a friendly key (`"supply_apy"`, `"supply_assets_usd"`, `"utilization"`, `"lltv"`, …) or a raw `MarketOrderBy` enum value.	`None`
`order_direction`	`str`	`"Desc"` (default) or `"Asc"`.	`'Desc'`
`where`	`Optional[dict[str, Any]]`	Additional raw `MarketFilters` (e.g. `{"utilization_lte": 0.99}`), merged with `chain_id`.	`None`

Returns:

Type	Description
`list[Market]`	The page of markets as :class:`~morpho_blue.models.Market` objects.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the API returns a GraphQL error.

Example::

with MorphoClient() as client:
    markets = client.get_markets(
        chain_id=1, first=5, order_by="supply_assets_usd"
    )
    for m in markets:
        if m.loan_asset and m.state:
            print(m.loan_asset.symbol, m.state.supply_apy)

`get_market(market_id, *, chain_id)`

Fetch a single market by its marketId (the unique key).

Parameters:

Name	Type	Description	Default
`market_id`	`str`	The market's unique key (0x-prefixed 32-byte hash). Note the Morpho schema uses `marketId`, not `uniqueKey`.	required
`chain_id`	`int`	The chain the market lives on (required for this lookup).	required

Returns:

Name	Type	Description
`The`	`Market`	class:`~morpho_blue.models.Market`.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the market is not found or the API errors.

`top_markets_by_supply_apy(*, chain_id=None, limit=10, where=None)`

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.

Parameters:

Name	Type	Description	Default
`chain_id`	`Optional[int]`	Restrict to one chain, or omit for all chains.	`None`
`limit`	`int`	How many markets to return.	`10`
`where`	`Optional[dict[str, Any]]`	Additional raw `MarketFilters` to apply.	`None`

Returns:

Type	Description
`list[Market]`	Up to `limit` markets ordered by descending supply APY.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the API returns a GraphQL error.

`iter_markets(*, chain_id=None, page_size=100, order_by=None, order_direction='Desc', where=None)`

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.

Parameters:

Name	Type	Description	Default
`chain_id`	`Optional[int]`	Restrict to one chain, or omit for all chains.	`None`
`page_size`	`int`	Number of markets requested per underlying page.	`100`
`order_by`	`Optional[str]`	Sort field (see :meth:`get_markets`).	`None`
`order_direction`	`str`	`"Desc"` (default) or `"Asc"`.	`'Desc'`
`where`	`Optional[dict[str, Any]]`	Additional raw `MarketFilters` to apply.	`None`

Returns:

Type	Description
`list[Market]`	Every matching market across all pages.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the API returns a GraphQL error.

`get_vaults(*, chain_id=None, first=100, skip=0, order_by=None, order_direction='Desc', where=None)`

Fetch a single page of MetaMorpho vaults, optionally filtered/sorted.

Parameters:

Name	Type	Description	Default
`chain_id`	`Optional[int]`	Restrict to one chain, or omit for all chains.	`None`
`first`	`Optional[int]`	Page size (max number of vaults to return).	`100`
`skip`	`Optional[int]`	Offset for pagination.	`0`
`order_by`	`Optional[str]`	Sort field. Accepts a friendly key (`"net_apy"`, `"total_assets_usd"`, `"apy"`, `"fee"`, …) or a raw `VaultOrderBy` enum value.	`None`
`order_direction`	`str`	`"Desc"` (default) or `"Asc"`.	`'Desc'`
`where`	`Optional[dict[str, Any]]`	Additional raw `VaultFilters` to apply.	`None`

Returns:

Type	Description
`list[Vault]`	The page of vaults as :class:`~morpho_blue.models.Vault` objects.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the API returns a GraphQL error.

`get_vault(address, *, chain_id=None)`

Fetch a single vault by its contract address.

Parameters:

Name	Type	Description	Default
`address`	`str`	The vault contract address.	required
`chain_id`	`Optional[int]`	The chain the vault lives on; recommended to disambiguate the same address across chains.	`None`

Returns:

Name	Type	Description
`The`	`Vault`	class:`~morpho_blue.models.Vault`.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the vault is not found or the API errors.

`top_vaults_by_apy(*, chain_id=None, limit=10, where=None)`

Return the limit vaults with the highest net APY.

Parameters:

Name	Type	Description	Default
`chain_id`	`Optional[int]`	Restrict to one chain, or omit for all chains.	`None`
`limit`	`int`	How many vaults to return.	`10`
`where`	`Optional[dict[str, Any]]`	Additional raw `VaultFilters` to apply.	`None`

Returns:

Type	Description
`list[Vault]`	Up to `limit` vaults ordered by descending net APY.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the API returns a GraphQL error.

`get_user(address, *, chain_id=None)`

Fetch a wallet's market and vault positions by address.

Parameters:

Name	Type	Description	Default
`address`	`str`	The wallet address to look up.	required
`chain_id`	`Optional[int]`	The chain to read positions on; recommended.	`None`

Returns:

Name	Type	Description
`A`	`User`	class:`~morpho_blue.models.User` with `market_positions` and
	`User`	`vault_positions`.

Raises:

Type	Description
`HTTPError`	On a non-2xx HTTP status.
`GraphQLError`	If the API returns a GraphQL error.

`GraphQLError`

Bases: MorphoError

Raised when the GraphQL endpoint returns an errors array.

The endpoint responds with HTTP 200 even for query errors, so this is surfaced from the response body rather than the status code.

Attributes:

Name	Type	Description
`errors`		The raw list of GraphQL error objects from the response.

`init(errors)`

Build the error from a GraphQL errors array.

Parameters:

Name	Type	Description	Default
`errors`	`list[Any]`	The `errors` list from the GraphQL response. Each item's `message` (when present) is joined into the exception message.	required

`HTTPError`

Bases: MorphoError

Raised for non-2xx HTTP responses from the endpoint.

Attributes:

Name	Type	Description
`status_code`		The HTTP status code returned by the endpoint.
`body`		The response body text, if any.

`init(status_code, body=None)`

Build the error from an HTTP status and optional body.

Parameters:

Name	Type	Description	Default
`status_code`	`int`	The non-2xx HTTP status code.	required
`body`	`Optional[str]`	The response body text, included in the message when present.	`None`

`MorphoError`

Bases: Exception

Base class for all errors raised by this library.

`Asset`

Bases: _Model

An ERC-20 token used as a loan or collateral asset, or a vault's asset.

`Chain`

Bases: _Model

An EVM chain that Morpho Blue is deployed on (e.g. Ethereum, Base).

`Market`

Bases: _Model

A Morpho Blue lending market (one loan asset against one collateral asset).

The unique key is :attr:market_id (the schema's marketId); there is no uniqueKey field. collateral_asset is None for idle markets.

`MarketPosition`

Bases: _Model

A user's position in a single market, with its health factor and balances.

`MarketPositionState`

Bases: _Model

A user's balances within a single market position.

`MarketState`

Bases: _Model

The current on-chain state and rates of a market.

APY and utilization are decimal fractions; *_usd are dollars; raw asset amounts are in the loan asset's smallest unit.

`PageInfo`

Bases: _Model

Pagination metadata returned alongside a page of results.

`User`

Bases: _Model

A wallet's positions across Morpho markets and vaults on one chain.

`Vault`

Bases: _Model

A MetaMorpho vault that allocates a single asset across Morpho markets.

`VaultAllocation`

Bases: _Model

A MetaMorpho vault's allocation of deposits into a single market.

`VaultPosition`

Bases: _Model

A user's position in a single MetaMorpho vault.

`VaultPositionState`

Bases: _Model

A user's balances within a single vault position.

`VaultState`

Bases: _Model

The current state of a MetaMorpho vault: yield, size, fee, and allocations.

API reference

morpho_blue

AsyncMorphoClient

__init__(endpoint=DEFAULT_ENDPOINT, *, timeout=DEFAULT_TIMEOUT, headers=None, client=None)

aclose() async

__aenter__() async

__aexit__(exc_type, exc, tb) async

execute(query, variables=None) async

get_markets(*, chain_id=None, first=100, skip=0, order_by=None, order_direction='Desc', where=None) async

get_market(market_id, *, chain_id) async

top_markets_by_supply_apy(*, chain_id=None, limit=10, where=None) async

iter_markets(*, chain_id=None, page_size=100, order_by=None, order_direction='Desc', where=None) async

get_vaults(*, chain_id=None, first=100, skip=0, order_by=None, order_direction='Desc', where=None) async

get_vault(address, *, chain_id=None) async

top_vaults_by_apy(*, chain_id=None, limit=10, where=None) async

get_user(address, *, chain_id=None) async

MorphoClient

__init__(endpoint=DEFAULT_ENDPOINT, *, timeout=DEFAULT_TIMEOUT, headers=None, client=None)

close()

__enter__()

__exit__(exc_type, exc, tb)

execute(query, variables=None)

get_markets(*, chain_id=None, first=100, skip=0, order_by=None, order_direction='Desc', where=None)

get_market(market_id, *, chain_id)

top_markets_by_supply_apy(*, chain_id=None, limit=10, where=None)

iter_markets(*, chain_id=None, page_size=100, order_by=None, order_direction='Desc', where=None)

get_vaults(*, chain_id=None, first=100, skip=0, order_by=None, order_direction='Desc', where=None)

get_vault(address, *, chain_id=None)

top_vaults_by_apy(*, chain_id=None, limit=10, where=None)

get_user(address, *, chain_id=None)

GraphQLError

__init__(errors)

HTTPError

__init__(status_code, body=None)

MorphoError

Asset

Chain

Market

MarketPosition

MarketPositionState

MarketState

PageInfo

User

Vault

VaultAllocation

VaultPosition

VaultPositionState

VaultState

`morpho_blue`

`AsyncMorphoClient`

`init(endpoint=DEFAULT_ENDPOINT, *, timeout=DEFAULT_TIMEOUT, headers=None, client=None)`

`aclose()` `async`

`aenter()` `async`

`aexit(exc_type, exc, tb)` `async`

`execute(query, variables=None)` `async`

`get_markets(*, chain_id=None, first=100, skip=0, order_by=None, order_direction='Desc', where=None)` `async`

`get_market(market_id, *, chain_id)` `async`

`top_markets_by_supply_apy(*, chain_id=None, limit=10, where=None)` `async`

`iter_markets(*, chain_id=None, page_size=100, order_by=None, order_direction='Desc', where=None)` `async`

`get_vaults(*, chain_id=None, first=100, skip=0, order_by=None, order_direction='Desc', where=None)` `async`

`get_vault(address, *, chain_id=None)` `async`

`top_vaults_by_apy(*, chain_id=None, limit=10, where=None)` `async`

`get_user(address, *, chain_id=None)` `async`

`MorphoClient`

`init(endpoint=DEFAULT_ENDPOINT, *, timeout=DEFAULT_TIMEOUT, headers=None, client=None)`

`close()`

`enter()`

`exit(exc_type, exc, tb)`

`execute(query, variables=None)`

`get_markets(*, chain_id=None, first=100, skip=0, order_by=None, order_direction='Desc', where=None)`

`get_market(market_id, *, chain_id)`

`top_markets_by_supply_apy(*, chain_id=None, limit=10, where=None)`

`iter_markets(*, chain_id=None, page_size=100, order_by=None, order_direction='Desc', where=None)`

`get_vaults(*, chain_id=None, first=100, skip=0, order_by=None, order_direction='Desc', where=None)`

`get_vault(address, *, chain_id=None)`

`top_vaults_by_apy(*, chain_id=None, limit=10, where=None)`

`get_user(address, *, chain_id=None)`

`GraphQLError`

`init(errors)`

`HTTPError`

`init(status_code, body=None)`

`MorphoError`

`Asset`

`Chain`

`Market`

`MarketPosition`

`MarketPositionState`

`MarketState`

`PageInfo`

`User`

`Vault`

`VaultAllocation`

`VaultPosition`

`VaultPositionState`

`VaultState`