mellow.offchain_metadata

Documentation for eth_defi.mellow.offchain_metadata Python module.

Mellow vault offchain metadata.

Mellow publishes a public vault catalogue API at https://points.mellow.finance/v1/vaults. The adapter uses this metadata only for enrichment values that are not part of the canonical on-chain vault accounting path, such as public names, symbols and base-token hints.

The current TVL value returned by the API is USD-denominated and point-in-time. It is useful for manual mapping diagnostics, but it is not written as production NAV or total_assets. Mellow current and historical denomination-token TVL is read from on-chain vault state as share_price * total_supply.

API response structure

GET /v1/vaults returns a JSON array. Each element is expected to include:

{
    "chain_id": 1,
    "address": "0x014e6DA8F283C4aF65B2AA0f201438680A004452",
    "symbol": "earnUSD",
    "name": "Lido Earn USD",
    "layer": "mellow",
    "tvl_usd": "21897383.50",
    "base_token": {
        "symbol": "USDC",
        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    }
}

The module follows the same two-level cache pattern used by other offchain vault metadata integrations: a disk cache for multiprocess scanner runs and an in-process dictionary for adapter lookups.

Module Attributes

DEFAULT_API_BASE_URL

Mellow public API base URL documented at https://docs.mellow.finance/resources/api

Functions

`fetch_mellow_api_vault_metadata`(chain_id, ...)	Fetch one vault metadata entry from the Mellow offchain API.
`fetch_mellow_api_vaults`([cache_path, ...])	Fetch and cache public Mellow API vault data.

Classes

MellowApiVaultMetadata

Optional current Mellow API metadata attached to a vault.

DEFAULT_CACHE_PATH = PosixPath('/home/runner/.tradingstrategy/cache/mellow'): Where we cache fetched Mellow API metadata files.

DEFAULT_API_BASE_URL = 'https://points.mellow.finance': Mellow public API base URL documented at https://docs.mellow.finance/resources/api

class MellowApiVaultMetadata

Bases: object

Optional current Mellow API metadata attached to a vault.

The Mellow API is an enrichment source. Its USD TVL is intentionally kept separate from on-chain denomination-token TVL so current scan records remain comparable with ERC-4626 and other smart-contract vault protocols.

chain_id: Optional[int]: EVM chain id.

address: Optional[eth_typing.evm.HexAddress]: Canonical Mellow Vault address.

name: Optional[str]: Public vault name.

symbol: Optional[str]: Public vault symbol.

layer: Optional[str]: Mellow API layer field, e.g. mellow or symbiotic.

tvl_usd: Optional[decimal.Decimal]

Current USD TVL from the public Mellow API, for diagnostics only.

Do not use this value as canonical production NAV. MellowVault reads comparable denomination-token TVL from on-chain share price and ShareManager.totalSupply().

base_token_address: Optional[eth_typing.evm.HexAddress]: Base token address from API/configuration, if known.

base_token_symbol: Optional[str]: Base token symbol from API/configuration, if known.

raw: dict[str, object]: Raw API fields kept for diagnostics.

__init__(chain_id=None, address=None, name=None, symbol=None, layer=None, tvl_usd=None, base_token_address=None, base_token_symbol=None, raw=<factory>)

Parameters

chain_id (Optional[int]) –
address (Optional[eth_typing.evm.HexAddress]) –
name (Optional[str]) –
symbol (Optional[str]) –
layer (Optional[str]) –
tvl_usd (Optional[decimal.Decimal]) –
base_token_address (Optional[eth_typing.evm.HexAddress]) –
base_token_symbol (Optional[str]) –
raw (dict[str, object]) –

Return type

None

fetch_mellow_api_vaults(cache_path=PosixPath('/home/runner/.tradingstrategy/cache/mellow'), api_base_url='https://points.mellow.finance', now_=None, max_cache_duration=datetime.timedelta(days=2))

Fetch and cache public Mellow API vault data.

The public API is used only as an enrichment layer. Hypersync factory events remain the source of truth for newly-created Core Vault leads, and on-chain share price/supply reads remain the source of truth for denomination-token TVL.

Parameters

cache_path (pathlib.Path) – Directory for cache files.
api_base_url (str) – Mellow API base URL.
now – Override current time for tests.
max_cache_duration (datetime.timedelta) – How long before refreshing cache.
now_ (Optional[datetime.datetime]) –

Returns

Mapping (chain_id, lower-case vault address) -> metadata.

Return type

dict[tuple[int, str], eth_defi.mellow.offchain_metadata.MellowApiVaultMetadata]

fetch_mellow_api_vault_metadata(chain_id, vault_address)

Fetch one vault metadata entry from the Mellow offchain API.

Parameters

chain_id (int) – EVM chain id.
vault_address (eth_typing.evm.HexAddress) – Mellow Vault address.

Returns

Metadata entry or None if the API has no matching vault.

Return type

Optional[eth_defi.mellow.offchain_metadata.MellowApiVaultMetadata]