DeriveV3VaultClient

Documentation for eth_defi.derive.v3_vaults.DeriveV3VaultClient Python class.

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.

Methods summary

__init__([network, session, timeout, ...])
close()	Close the underlying HTTP session.
fetch_spot_assets()	Map configured spot asset addresses to symbols and decimals.
fetch_vault(subaccount_id)	Fetch a full public native vault record for manual inspection.
fetch_vault_performance(subaccount_id[, ...])	Iterate the available sampled price history, newest first.
fetch_vaults([page_size])	Fetch each page of the deployment's public vault listing.

__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