derive.v3_vaults

Documentation for eth_defi.derive.v3_vaults Python module.

Public Derive v3 native vault data.

Derive v3 vaults are managed exchange subaccounts, not ERC-4626 contracts. The unauthenticated HTTP API exposes discovery, live NAV and sampled performance history. See Derive’s vault documentation and the public API.

Classes

`DeriveV3Vault`	One public native vault record.
`DeriveV3VaultClient`	Synchronous client for the public Derive v3 vault endpoints.
`DeriveV3VaultPrice`	One sampled vault performance point.

class DeriveV3Vault

Bases: object

One public native vault record.

The vault subaccount ID is unique only within the chosen Derive v3 deployment. Monetary values are decimal strings in the source API.

subaccount_id: int: Native vault subaccount ID.

name: str: Curator-supplied display name.

description: str: Curator-supplied strategy description.

curator: eth_typing.evm.HexAddress: Curator wallet address.

deposit_spot_asset: eth_typing.evm.HexAddress: Derive spot asset address accepted for deposits.

nav_usd: Optional[decimal.Decimal]: Live mark-to-market NAV in USD, if priceable.

share_price_usd: Optional[decimal.Decimal]: Live USD price per share, assuming accrued fees were settled now.

total_shares: decimal.Decimal: Outstanding native shares.

management_fee_bps: int: Annual management fee in basis points.

performance_fee_bps: int: Performance fee in basis points.

cooldown_sec: int: Minimum holder withdrawal cooldown in seconds.

whitelist_only: bool: Whether deposits are limited to the vault whitelist.

closed: bool: Whether the vault has entered its terminal closed state.

deposit_symbol: Optional[str]: Deposit currency symbol resolved from public/get_all_currencies.

deposit_decimals: Optional[int]: Underlying ERC-20 decimal count, when the spot asset provides one.

raw_metadata: Optional[dict]: Complete source record, retained for future metadata fields.

classmethod from_api(value)

Parse a public vault record without rounding decimal amounts.

Parameters: value (dict) – Vault object from public/get_vaults.
Returns: Parsed vault metadata.
Return type: eth_defi.derive.v3_vaults.DeriveV3Vault

__init__(subaccount_id, name, description, curator, deposit_spot_asset, nav_usd, share_price_usd, total_shares, management_fee_bps, performance_fee_bps, cooldown_sec, whitelist_only, closed, deposit_symbol=None, deposit_decimals=None, raw_metadata=None)

Parameters

subaccount_id (int) –
name (str) –
description (str) –
curator (eth_typing.evm.HexAddress) –
deposit_spot_asset (eth_typing.evm.HexAddress) –
nav_usd (Optional[decimal.Decimal]) –
share_price_usd (Optional[decimal.Decimal]) –
total_shares (decimal.Decimal) –
management_fee_bps (int) –
performance_fee_bps (int) –
cooldown_sec (int) –
whitelist_only (bool) –
closed (bool) –
deposit_symbol (Optional[str]) –
deposit_decimals (Optional[int]) –
raw_metadata (Optional[dict]) –

Return type

None

class DeriveV3VaultPrice

Bases: object

One sampled vault performance point.

share_price is the historical mark-to-market share price reported by Derive. It can differ from the live simulated post-fee settlement price.

See public/get_vault_performance_history.

subaccount_id: int: Native vault subaccount ID.

timestamp: datetime.datetime: Naive UTC observation time.

share_price: decimal.Decimal: Historical USD price per native share.

nav_usd: Optional[decimal.Decimal]: Vault NAV in USD, or None when the API cannot value the vault.

total_shares: decimal.Decimal: Outstanding native shares.

classmethod from_api(subaccount_id, value)

Parse a performance point and normalise its Unix timestamp.

Derive’s OpenAPI text describes milliseconds. Testnet responses on 24 September 2026 used seconds, so the parser accepts both units.

Parameters

subaccount_id (int) – Vault subaccount ID from the request.
value (dict) – VaultPerformancePointResponse object.

Returns

Parsed performance observation.

Return type

eth_defi.derive.v3_vaults.DeriveV3VaultPrice

__init__(subaccount_id, timestamp, share_price, nav_usd, total_shares)

Parameters

subaccount_id (int) –
timestamp (datetime.datetime) –
share_price (decimal.Decimal) –
nav_usd (Optional[decimal.Decimal]) –
total_shares (decimal.Decimal) –

Return type

None

class DeriveV3VaultClient

Bases: object

Synchronous client for the public Derive v3 vault endpoints.

Defaults to testnet. Pass network="mainnet" for production data; subaccount IDs are scoped to a deployment. No credentials are needed.

The default session retries HTTP 429 and selected server errors up to three times. A supplied session keeps its own retry configuration. close() closes either session, including one supplied by the caller.

Parameters

network – testnet or mainnet.
session – Optional configured HTTP session.
timeout – Per-request timeout in seconds.
api_error_retry_attempts – Maximum attempts for retryable errors returned inside a successful Derive JSON response.
api_error_retry_backoff – Initial exponential backoff in seconds between retryable API errors.

__init__(network='testnet', session=None, timeout=30.0, api_error_retry_attempts=3, api_error_retry_backoff=0.5)

Parameters

network (Literal['testnet', 'mainnet']) –
session (Optional[requests.sessions.Session]) –
timeout (float) –
api_error_retry_attempts (int) –
api_error_retry_backoff (float) –

Return type

None

fetch_vaults(page_size=100)

Fetch each page of the deployment’s public vault listing.

An empty listing yields no records. HTTP and response errors propagate to the caller, so an unavailable API is distinguishable from no vaults.

Parameters: page_size (int) – API page size, between 1 and 100.
Returns: Vault records in API page order.
Return type: collections.abc.Iterator[eth_defi.derive.v3_vaults.DeriveV3Vault]

fetch_vault(subaccount_id)

Fetch a full public native vault record for manual inspection.

Returns the response without parsing it into DeriveV3Vault, so callers can inspect fields absent from the listing model. See public/get_vault.

Parameters: subaccount_id (int) – Native vault subaccount ID.
Returns: Complete public vault response.
Return type: dict

fetch_spot_assets()

Map configured spot asset addresses to symbols and decimals.

Derive identifies a vault’s deposit asset by its internal spot address. Currency metadata is the public source for a display symbol. See public/get_all_currencies.

Returns: Lowercase spot address to (symbol, ERC-20 decimals).
Return type: dict[str, tuple[str, int | None]]

fetch_vault_performance(subaccount_id, resolution='24h', limit=10000)

Iterate the available sampled price history, newest first.

The endpoint caps a page at 10,000 points. Older points are fetched using the exclusive to bound in Unix seconds, even when a response supplies bucket timestamps in milliseconds.

Parameters

subaccount_id (int) – Native vault subaccount ID.
resolution (Literal['1h', '8h', '24h', '1wk']) – Sampling resolution supported by Derive.
limit (int) – Points per request, 1 to 10,000. This does not limit the total number of points yielded across pages.

Returns

Historical observations, newest first.

Return type

collections.abc.Iterator[eth_defi.derive.v3_vaults.DeriveV3VaultPrice]

close()

Close the underlying HTTP session.

Returns: None.
Return type: None