apex.vault

Documentation for eth_defi.apex.vault Python module.

Typed ApeX public vault API parsing and fetching.

The public endpoints are:

The history endpoint was verified on 2026-07-23 to return one unpaginated data.timeValue array with no completeness token or range parameters.

Functions

`fetch_ranking_page`(session_pool, page, *[, ...])	Fetch one zero-based ranking page.
`fetch_stabilised_vaults`(session_pool, *[, ...])	Fetch two complete matching ranking passes.
`fetch_vault_history`(session_pool, vault_id, *)	Fetch all history currently recoverable for one ApeX vault.
`parse_history`(payload)	Parse, canonicalise and order one unpaginated history response.
`parse_ranking_page`(payload)	Parse and validate one ranking response page.
`parse_vault_summary`(raw)	Parse one ranking vault without status or TVL filtering.

Classes

`ApexHistoryPoint`	One native ApeX historical vault value.
`ApexRankingPage`	One validated ranking page.
`ApexVaultSummary`	One vault returned by the ApeX ranking endpoint.

class ApexVaultSummary

Bases: object

One vault returned by the ApeX ranking endpoint.

vault_id: str: Platform-unique vault identifier.

synthetic_address: str: Stable synthetic reader address.

reported_ethereum_address: Optional[eth_typing.evm.HexAddress]: Ethereum address reported by ApeX, which is not unique per vault.

name: str: Display name.

description: str: Strategy description.

status: str: Raw vault lifecycle status.

vault_type: str: Raw collection-vault type.

share_price: Optional[float]: Current share price in ApeX USDT terms.

tvl: Optional[float]: Current total value in ApeX USDT terms.

share_count: Optional[float]: Current reported share count.

created_at: Optional[datetime.datetime]: Creation timestamp as naive UTC.

source_updated_at: Optional[datetime.datetime]: Source update timestamp as naive UTC.

finished_at: Optional[datetime.datetime]: Terminal timestamp as naive UTC.

max_amount: Optional[float]: Subscription cap as a raw numeric value.

purchase_fee_rate_raw: Optional[str]: Unverified fee-unit source value.

share_profit_ratio_raw: Optional[str]: Unverified profit-share-unit source value.

__init__(vault_id, synthetic_address, reported_ethereum_address, name, description, status, vault_type, share_price, tvl, share_count, created_at, source_updated_at, finished_at, max_amount, purchase_fee_rate_raw, share_profit_ratio_raw)

Parameters

vault_id (str) –
synthetic_address (str) –
reported_ethereum_address (Optional[eth_typing.evm.HexAddress]) –
name (str) –
description (str) –
status (str) –
vault_type (str) –
share_price (Optional[float]) –
tvl (Optional[float]) –
share_count (Optional[float]) –
created_at (Optional[datetime.datetime]) –
source_updated_at (Optional[datetime.datetime]) –
finished_at (Optional[datetime.datetime]) –
max_amount (Optional[float]) –
purchase_fee_rate_raw (Optional[str]) –
share_profit_ratio_raw (Optional[str]) –

Return type

None

class ApexHistoryPoint

Bases: object

One native ApeX historical vault value.

timestamp: datetime.datetime: Exact naive UTC source timestamp.

net_value: float: Native share price.

total_value: float: Native total vault value.

property total_supply: Optional[float]

Derive total share supply when division is valid.

Returns: Total value divided by positive NAV, otherwise None.

__init__(timestamp, net_value, total_value)

Parameters

timestamp (datetime.datetime) –
net_value (float) –
total_value (float) –

Return type

None

class ApexRankingPage

Bases: object

One validated ranking page.

total_size: int: Total source rows reported for the complete ranking.

vaults: tuple[eth_defi.apex.vault.ApexVaultSummary, ...]: Parsed page vaults.

__init__(total_size, vaults)

Parameters

total_size (int) –
vaults (tuple[eth_defi.apex.vault.ApexVaultSummary, ...]) –

Return type

None

parse_vault_summary(raw)

Parse one ranking vault without status or TVL filtering.

Parameters: raw (object) – Raw vaultList object.
Returns: Typed vault summary.
Return type: eth_defi.apex.vault.ApexVaultSummary

parse_ranking_page(payload)

Parse and validate one ranking response page.

The application envelope, total size, vault array and every retained vault record are validated before the page is returned.

Parameters: payload (object) – Decoded JSON response.
Returns: Typed page with its complete-source row count.
Return type: eth_defi.apex.vault.ApexRankingPage

parse_history(payload)

Parse, canonicalise and order one unpaginated history response.

Equivalent duplicate timestamps collapse to one point. Conflicting values at one timestamp reject the complete response so no ambiguous history is staged.

Parameters: payload (object) – Decoded JSON response.
Returns: Timestamp-ordered immutable history points.
Return type: tuple[eth_defi.apex.vault.ApexHistoryPoint, …]

fetch_ranking_page(session_pool, page, *, limit=100, operation_deadline)

Fetch one zero-based ranking page.

Endpoint validation runs inside the session pool retry boundary, so an invalid HTTP-200 application envelope is retried as one request operation.

Parameters

session_pool (eth_defi.apex.session.ApexSessionPool) – Configured bounded ApeX session pool.
page (int) – Zero-based page number.
limit (int) – Positive page size.
operation_deadline (float) – Monotonic budget boundary shared by the full ranking operation.

Returns

Validated typed ranking page.

Return type

eth_defi.apex.vault.ApexRankingPage

fetch_stabilised_vaults(session_pool, *, limit=100, operation_timeout=300.0, attempts=3)

Fetch two complete matching ranking passes.

The second pass supplies the stored metric values after both passes report identical vault membership.

Parameters

session_pool (eth_defi.apex.session.ApexSessionPool) – Configured bounded ApeX session pool.
limit (int) – Positive ranking page size.
operation_timeout (float) – Monotonic whole-read budget used across both passes and retries.
attempts (int) – Positive number of complete two-pass attempts.

Returns

Stabilised second-pass vault records.

Return type

tuple[eth_defi.apex.vault.ApexVaultSummary, …]

fetch_vault_history(session_pool, vault_id, *, operation_timeout=120.0)

Fetch all history currently recoverable for one ApeX vault.

The public endpoint exposes no pagination or completeness metadata. The returned timestamps are therefore the recoverable source range, not a claim of lifetime completeness.

Parameters

session_pool (eth_defi.apex.session.ApexSessionPool) – Configured bounded ApeX session pool.
vault_id (str) – Non-empty ApeX platform vault ID.
operation_timeout (float) – Monotonic operation budget shared by all HTTP attempts.

Returns

Parsed history ordered by exact naive UTC source timestamp.

Return type

tuple[eth_defi.apex.vault.ApexHistoryPoint, …]