Vaults.fyi Python SDK

Python SDK for the Vaults.fyi V2 API.

Installation

pip install vaultsfyi

Quick Start

from vaultsfyi import VaultsSdk

client = VaultsSdk(api_key="your_api_key_here")

# Basic health check
print(client.get_health())

# Fetch detailed vaults with filters
vaults = client.get_detailed_vaults(
    page=0,
    per_page=100,
    allowed_assets=["USDC", "USDT"],
    allowed_networks=["mainnet", "base"],
    min_tvl=1_000_000,
    only_transactional=True,
)

# User portfolio positions
positions = client.get_positions(
    user_address="0x1234...",
    allowed_networks=["mainnet", "base"],
    min_usd_asset_value_threshold=100,
)

Authentication

All endpoints use API key auth via x-api-key header.

client = VaultsSdk(api_key="your_api_key_here")

Method Reference

Health & Metadata

• get_health()
• get_networks(**kwargs)
• get_tags(**kwargs)
• get_assets(page=None, per_page=None, network=None, **kwargs)
• get_vaults(page=None, per_page=None, network=None, asset_symbol=None, only_transactional=None, only_app_featured=None, allow_corrupted=None, **kwargs)
• get_curators(**kwargs)

Benchmarks

• get_benchmarks(network, code)
• get_historical_benchmarks(network, code, page=None, per_page=None, from_timestamp=None, to_timestamp=None, **kwargs)

Detailed Vaults

• get_detailed_vaults(page=None, per_page=None, allowed_assets=None, disallowed_assets=None, allowed_protocols=None, disallowed_protocols=None, allowed_networks=None, disallowed_networks=None, min_tvl=None, max_tvl=None, min_apy=None, max_apy=None, tags=None, curators=None, only_transactional=None, only_app_featured=None, allow_corrupted=None, allow_vaults_with_warnings=None, sort_by=None, sort_order=None, **kwargs)
• get_all_vaults(**kwargs) (backward-compatible alias for get_detailed_vaults)
• get_vault(network, vault_address, **kwargs)
• get_vault_apy_breakdown(network, vault_address, **kwargs)
• get_vault_tvl_breakdown(network, vault_address, **kwargs)

Historical Data

• get_vault_historical_data(network, vault_address, page=None, per_page=None, apy_interval=None, granularity=None, from_timestamp=None, to_timestamp=None, **kwargs)
• get_vault_historical_apy(network, vault_address, page=None, per_page=None, apy_interval=None, granularity=None, from_timestamp=None, to_timestamp=None, **kwargs)
• get_vault_historical_tvl(network, vault_address, page=None, per_page=None, apy_interval=None, granularity=None, from_timestamp=None, to_timestamp=None, **kwargs)
• get_vault_historical_share_price(network, vault_address, page=None, per_page=None, apy_interval=None, granularity=None, from_timestamp=None, to_timestamp=None, **kwargs)
• get_historical_asset_prices(network, asset_address, page=None, per_page=None, granularity=None, from_timestamp=None, to_timestamp=None, **kwargs)

Portfolio

• get_positions(user_address, allowed_assets=None, disallowed_assets=None, allowed_protocols=None, disallowed_protocols=None, allowed_networks=None, disallowed_networks=None, min_tvl=None, max_tvl=None, min_apy=None, max_apy=None, tags=None, curators=None, only_transactional=None, only_app_featured=None, allow_corrupted=None, allow_vaults_with_warnings=None, sort_by=None, sort_order=None, apy_interval=None, min_usd_asset_value_threshold=None, **kwargs)
• get_position(user_address, network, vault_address, apy_interval=None, **kwargs)
• get_best_vault(user_address, allowed_assets=None, disallowed_assets=None, allowed_protocols=None, disallowed_protocols=None, allowed_networks=None, disallowed_networks=None, min_tvl=None, min_apy=None, only_transactional=None, only_app_featured=None, allow_corrupted=None, allow_vaults_with_warnings=None, apy_interval=None, min_usd_asset_value_threshold=None, **kwargs)
• get_deposit_options(user_address, allowed_assets=None, disallowed_assets=None, allowed_protocols=None, disallowed_protocols=None, allowed_networks=None, disallowed_networks=None, min_tvl=None, min_apy=None, only_transactional=None, only_app_featured=None, allow_corrupted=None, allow_vaults_with_warnings=None, apy_interval=None, min_usd_asset_value_threshold=None, always_return_assets=None, max_vaults_per_asset=None, **kwargs)
• get_idle_assets(user_address, allowed_assets=None, disallowed_assets=None, allowed_networks=None, disallowed_networks=None, min_usd_asset_value_threshold=None, sort_by=None, sort_direction=None, **kwargs)
• get_vault_total_returns(user_address, network, vault_address, **kwargs)
• get_vault_holder_events(user_address, network, vault_address, **kwargs)

Transactions

• get_transactions_context(user_address, network, vault_address, **kwargs)
• get_actions(action, user_address, network, vault_address, amount=None, asset_address=None, simulate=False, all=None, **kwargs)

Rewards

• get_rewards_context(user_address, **kwargs)
• get_rewards_claim(user_address, simulate=None, claim_ids=None, **kwargs)

Usage Examples

Detailed vault filters

vaults = client.get_detailed_vaults(
    allowed_assets=["USDC"],
    allowed_networks=["mainnet", "base"],
    min_tvl=1_000_000,
    min_apy=0.02,
    sort_by="apy",
    sort_order="desc",
    page=0,
    per_page=100,
)

Deposit options

options = client.get_deposit_options(
    user_address="0x1234...",
    allowed_assets=["USDC", "USDT"],
    allowed_networks=["mainnet", "base"],
    min_usd_asset_value_threshold=100,
    always_return_assets=["USDC"],
    max_vaults_per_asset=5,
)

Historical asset prices

prices = client.get_historical_asset_prices(
    network="mainnet",
    asset_address="0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    granularity="1d",
    page=0,
    per_page=100,
)

Transaction actions

actions = client.get_actions(
    action="deposit",
    user_address="0x1234...",
    network="mainnet",
    vault_address="0x5678...",
    asset_address="0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    amount="1000000",
    simulate=False,
)

Error Handling

from vaultsfyi import VaultsSdk, AuthenticationError, HttpResponseError

client = VaultsSdk(api_key="your_api_key_here")

try:
    result = client.get_benchmarks("mainnet", "usd")
except AuthenticationError:
    print("Invalid API key")
except HttpResponseError as e:
    print(f"API error: {e}")

Requirements

• Python 3.8+
• requests>=2.25.0

License

MIT