SDK Method Reference

For installation and client setup, see the quickstart guide.

Installation & setup

npm install @vaultsfyi/sdk

pip install vaultsfyi

import { VaultsSdk } from '@vaultsfyi/sdk'

const sdk = new VaultsSdk({ apiKey: 'YOUR_API_KEY' })

from vaultsfyi import VaultsSdk

client = VaultsSdk(api_key="YOUR_API_KEY")

The Python client also accepts optional api_base_url, timeout (default 30s), and max_retries (default 3) constructor arguments.

Vault discovery

`getAllVaults` / `get_all_vaults`

Returns a paginated, filterable list of vaults with full performance metrics.

const vaults = await sdk.getAllVaults({
  query: {
    page: 0,
    perPage: 100,
    allowedNetworks: ['mainnet', 'base'],
    allowedProtocols: ['aave', 'morpho'],
    allowedAssets: ['USDC', 'USDT'],
    minTvl: 1000000,
    maxTvl: 100000000,
    minApy: 0.03,
    sortBy: 'apy7day',
    sortOrder: 'desc',
    onlyTransactional: true,
  }
})

vaults = client.get_all_vaults(
    page=0,
    per_page=100,
    allowed_networks=["mainnet", "base"],
    allowed_protocols=["aave", "morpho"],
    allowed_assets=["USDC", "USDT"],
    min_tvl=1_000_000,
    max_tvl=100_000_000,
    min_apy=0.03,
    sort_by="apy7day",
    sort_order="desc",
    only_transactional=True,
)

`getVault` / `get_vault`

Returns full detail for a single vault by network and address.

const vault = await sdk.getVault({
  path: {
    network: 'mainnet',
    vaultAddress: '0x9D39A5DE30e57443BfF2A8307A4256c8797A3497'
  }
})

vault = client.get_vault(
    network="mainnet",
    vault_address="0x9D39A5DE30e57443BfF2A8307A4256c8797A3497",
)

`getVaultApyBreakdown` / `get_vault_apy_breakdown`

Returns only the APY breakdown for a vault — lighter than fetching the full vault object.

const apy = await sdk.getVaultApyBreakdown({
  path: {
    network: 'mainnet',
    vaultAddress: '0x1234...'
  }
})

apy = client.get_vault_apy_breakdown(
    network="mainnet",
    vault_address="0x1234...",
)

`getAssets` / `get_assets`

Lists all tracked assets across networks.

const assets = await sdk.getAssets({
  query: { page: 0, perPage: 100 }
})

assets = client.get_assets(page=0, per_page=100)

Historical data

`getVaultHistoricalData` / `get_vault_historical_data`

Returns combined APY, TVL, and share price time-series for a vault.

const history = await sdk.getVaultHistoricalData({
  path: {
    network: 'mainnet',
    vaultAddress: '0x1234...'
  },
  query: {
    page: 0,
    perPage: 90,
    apyInterval: '7day',
    granularity: '1day',
    fromTimestamp: 1735689600,
    toTimestamp: 1743465600
  }
})

history = client.get_vault_historical_data(
    network="mainnet",
    vault_address="0x1234...",
    page=0,
    per_page=90,
    apy_interval="7day",
    granularity="1day",
    from_timestamp=1735689600,
    to_timestamp=1743465600,
)

`getVaultHistoricalApy` / `get_vault_historical_apy`

APY-only time series. Lighter than the combined endpoint when TVL is not needed.

const apyHistory = await sdk.getVaultHistoricalApy({
  path: { network: 'mainnet', vaultAddress: '0x1234...' },
  query: {
    apyInterval: '7day',
    granularity: '1day',
    fromTimestamp: 1735689600,
    toTimestamp: 1743465600
  }
})

apy_history = client.get_vault_historical_apy(
    network="mainnet",
    vault_address="0x1234...",
    apy_interval="7day",
    granularity="1day",
    from_timestamp=1735689600,
    to_timestamp=1743465600,
)

`getVaultHistoricalTvl` / `get_vault_historical_tvl`

TVL-only time series.

const tvlHistory = await sdk.getVaultHistoricalTvl({
  path: { network: 'mainnet', vaultAddress: '0x1234...' },
  query: { fromTimestamp: 1735689600, toTimestamp: 1743465600 }
})

tvl_history = client.get_vault_historical_tvl(
    network="mainnet",
    vault_address="0x1234...",
    from_timestamp=1735689600,
    to_timestamp=1743465600,
)

`getVaultHistoricalSharePrice` / `get_vault_historical_share_price`

Share price time series.

const sharePriceHistory = await sdk.getVaultHistoricalSharePrice({
  path: { network: 'mainnet', vaultAddress: '0x1234...' },
  query: { fromTimestamp: 1735689600, toTimestamp: 1743465600 }
})

share_price_history = client.get_vault_historical_share_price(
    network="mainnet",
    vault_address="0x1234...",
    from_timestamp=1735689600,
    to_timestamp=1743465600,
)

`getHistoricalAssetPrices` / `get_historical_asset_prices`

Historical USD prices for a tracked asset.

const prices = await sdk.getHistoricalAssetPrices({
  path: {
    network: 'mainnet',
    assetAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
  },
  query: {
    granularity: '1day',
    fromTimestamp: 1735689600,
    toTimestamp: 1743465600
  }
})

prices = client.get_historical_asset_prices(
    network="mainnet",
    asset_address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    granularity="1day",
    from_timestamp=1735689600,
    to_timestamp=1743465600,
)

Portfolio

`getPositions` / `get_positions`

Returns all active vault positions for a wallet, optionally filtered and sorted.

const positions = await sdk.getPositions({
  path: { userAddress: '0xYourWallet' },
  query: {
    allowedNetworks: ['mainnet', 'base'],
    apyInterval: '7day',
    sortBy: 'balanceUsd',
    sortOrder: 'desc'
  }
})

positions = client.get_positions(
    user_address="0xYourWallet",
    allowed_networks=["mainnet", "base"],
    apy_interval="7day",
    sort_by="balanceUsd",
    sort_order="desc",
)

`getPosition` / `get_position`

Returns a single vault position for a specific wallet and vault.

const position = await sdk.getPosition({
  path: {
    userAddress: '0xYourWallet',
    network: 'mainnet',
    vaultAddress: '0x1234...'
  },
  query: { apyInterval: '7day' }
})

position = client.get_position(
    user_address="0xYourWallet",
    network="mainnet",
    vault_address="0x1234...",
    apy_interval="7day",
)

`getIdleAssets` / `get_idle_assets`

Returns assets sitting in a wallet not currently earning yield.

const idle = await sdk.getIdleAssets({
  path: { userAddress: '0xYourWallet' },
  query: {
    allowedNetworks: ['mainnet', 'base'],
    minUsdAssetValueThreshold: 10,
    sortBy: 'balanceUsd',
    sortDirection: 'desc'
  }
})

idle = client.get_idle_assets(
    user_address="0xYourWallet",
    allowed_networks=["mainnet", "base"],
    min_usd_asset_value_threshold=10,
    sort_by="balanceUsd",
    sort_direction="desc",
)

`getDepositOptions` / `get_deposit_options`

Returns ranked vault recommendations for each idle asset in a wallet.

const options = await sdk.getDepositOptions({
  path: { userAddress: '0xYourWallet' },
  query: {
    allowedNetworks: ['mainnet', 'base'],
    allowedAssets: ['USDC', 'USDT'],
    minTvl: 1000000,
    onlyTransactional: true,
    apyInterval: '7day',
    maxVaultsPerAsset: 3,
    alwaysReturnAssets: ['USDC']
  }
})

options = client.get_deposit_options(
    user_address="0xYourWallet",
    allowed_networks=["mainnet", "base"],
    allowed_assets=["USDC", "USDT"],
    min_tvl=1_000_000,
    only_transactional=True,
    apy_interval="7day",
    max_vaults_per_asset=3,
    always_return_assets=["USDC"],
)

`getBestVault` / `get_best_vault`

Returns the single highest-yielding vault opportunity for a wallet’s current balances.

const best = await sdk.getBestVault({
  path: { userAddress: '0xYourWallet' },
  query: {
    allowedNetworks: ['mainnet', 'base'],
    onlyTransactional: true,
    apyInterval: '7day'
  }
})

best = client.get_best_vault(
    user_address="0xYourWallet",
    allowed_networks=["mainnet", "base"],
    only_transactional=True,
    apy_interval="7day",
)

`getUserVaultTotalReturns` / `get_vault_total_returns`

Returns total yield earned in a specific vault since the wallet’s first deposit.

const returns = await sdk.getUserVaultTotalReturns({
  path: {
    userAddress: '0xYourWallet',
    network: 'mainnet',
    vaultAddress: '0x1234...'
  }
})

returns = client.get_vault_total_returns(
    user_address="0xYourWallet",
    network="mainnet",
    vault_address="0x1234...",
)

`getUserVaultEvents` / `get_vault_holder_events`

Returns the full deposit and withdrawal history for a wallet in a specific vault.

const events = await sdk.getUserVaultEvents({
  path: {
    userAddress: '0xYourWallet',
    network: 'mainnet',
    vaultAddress: '0x1234...'
  }
})

events = client.get_vault_holder_events(
    user_address="0xYourWallet",
    network="mainnet",
    vault_address="0x1234...",
)

Transactions

`getTransactionsContext` / `get_transactions_context`

Returns the current state for a vault interaction: available action steps, token balances, and allowance status. Call this before getActions to determine what step is next.

const context = await sdk.getTransactionsContext({
  path: {
    userAddress: '0xYourWallet',
    network: 'mainnet',
    vaultAddress: '0x1234...'
  }
})

context = client.get_transactions_context(
    user_address="0xYourWallet",
    network="mainnet",
    vault_address="0x1234...",
)

`getActions` / `get_actions`

Returns ready-to-sign transaction calldata for a vault action. Execute actions in order — each must confirm onchain before sending the next. The action parameter accepts: deposit, redeem, request-redeem, claim-redeem, request-deposit, claim-deposit, claim-rewards, start-redeem-cooldown.

const actions = await sdk.getActions({
  path: {
    action: 'deposit',
    userAddress: '0xYourWallet',
    network: 'mainnet',
    vaultAddress: '0x1234...'
  },
  query: {
    assetAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    amount: '1000000000'  // 1000 USDC (6 decimals)
  }
})

actions = client.get_actions(
    action="deposit",
    user_address="0xYourWallet",
    network="mainnet",
    vault_address="0x1234...",
    asset_address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    amount="1000000000",  # 1000 USDC (6 decimals)
)

Rewards

`getRewardsTransactionsContext` / `get_rewards_context`

Returns all claimable reward balances for a wallet across every supported network.

const rewardsContext = await sdk.getRewardsTransactionsContext({
  path: { userAddress: '0xYourWallet' }
})

rewards_context = client.get_rewards_context(
    user_address="0xYourWallet",
)

`getRewardsClaimActions` / `get_rewards_claim`

Returns transaction calldata to claim one or more pending rewards. Pass claimIds from the rewards context response.

const claimActions = await sdk.getRewardsClaimActions({
  path: { userAddress: '0xYourWallet' },
  query: {
    claimIds: ['claim-id-1', 'claim-id-2']
  }
})

claim_actions = client.get_rewards_claim(
    user_address="0xYourWallet",
    claim_ids=["claim-id-1", "claim-id-2"],
)

Benchmarks

`getBenchmarks` / `get_benchmarks`

Returns current benchmark APY rates for a network. Use code to specify usd or eth denomination.

const benchmarks = await sdk.getBenchmarks({
  path: { network: 'mainnet' },
  query: { code: 'usd' }
})

benchmarks = client.get_benchmarks(
    network="mainnet",
    code="usd",
)

`getHistoricalBenchmarks` / `get_historical_benchmarks`

Returns paginated historical benchmark rates within a time range.

const historicalBenchmarks = await sdk.getHistoricalBenchmarks({
  path: { network: 'mainnet' },
  query: {
    code: 'usd',
    page: 0,
    perPage: 90,
    fromTimestamp: 1735689600,
    toTimestamp: 1743465600
  }
})

historical_benchmarks = client.get_historical_benchmarks(
    network="mainnet",
    code="usd",
    page=0,
    per_page=90,
    from_timestamp=1735689600,
    to_timestamp=1743465600,
)

Error handling

import { VaultsSdk, HttpResponseError } from '@vaultsfyi/sdk'

try {
  const vault = await sdk.getVault({
    path: { network: 'mainnet', vaultAddress: '0xinvalid' }
  })
} catch (error) {
  if (error instanceof HttpResponseError) {
    console.error(`API error ${error.statusCode}: ${error.message}`)
  }
}

from vaultsfyi import VaultsSdk
from vaultsfyi.exceptions import (
    AuthenticationError,
    ForbiddenError,
    RateLimitError,
    HttpResponseError,
    NetworkError,
)

try:
    vault = client.get_vault(
        network="mainnet",
        vault_address="0xinvalid",
    )
except AuthenticationError:
    print("Invalid or missing API key")
except ForbiddenError:
    print("API key has exhausted available credits")
except RateLimitError:
    print("Rate limit exceeded — slow down requests")
except HttpResponseError as e:
    print(f"API error {e.status_code}: {e}")
except NetworkError:
    print("Network connectivity issue")

The Python SDK exposes five exception classes, all inheriting from VaultsFyiError:

Exception	Cause
`HttpResponseError`	Any non-2xx HTTP response
`AuthenticationError`	Invalid or missing API key
`ForbiddenError`	API key has exhausted available credits
`RateLimitError`	Too many requests
`NetworkError`	Connection or timeout failure

TypeScript types

The TypeScript SDK ships full type definitions generated from the OpenAPI spec. All response types are inferred automatically — no manual casting required.

// Types are inferred from the API spec
const vaults = await sdk.getAllVaults()    // DetailedVault[]
const vault  = await sdk.getVault({ … })  // DetailedVault

Start Here

Core Concepts

Methodology

SDK

AI & Agents

Plans & Billing

Resources

SDK Method Reference

Installation & setup

Vault discovery

`getAllVaults` / `get_all_vaults`

`getVault` / `get_vault`

`getVaultApyBreakdown` / `get_vault_apy_breakdown`

`getAssets` / `get_assets`

Historical data

`getVaultHistoricalData` / `get_vault_historical_data`

`getVaultHistoricalApy` / `get_vault_historical_apy`

`getVaultHistoricalTvl` / `get_vault_historical_tvl`

`getVaultHistoricalSharePrice` / `get_vault_historical_share_price`

`getHistoricalAssetPrices` / `get_historical_asset_prices`

Portfolio

`getPositions` / `get_positions`

`getPosition` / `get_position`

`getIdleAssets` / `get_idle_assets`

`getDepositOptions` / `get_deposit_options`

`getBestVault` / `get_best_vault`

`getUserVaultTotalReturns` / `get_vault_total_returns`

`getUserVaultEvents` / `get_vault_holder_events`

Transactions

`getTransactionsContext` / `get_transactions_context`

`getActions` / `get_actions`

Rewards

`getRewardsTransactionsContext` / `get_rewards_context`

`getRewardsClaimActions` / `get_rewards_claim`

Benchmarks

`getBenchmarks` / `get_benchmarks`

`getHistoricalBenchmarks` / `get_historical_benchmarks`

Error handling

TypeScript types

​Installation & setup

​Vault discovery

​getAllVaults / get_all_vaults

​getVault / get_vault

​getVaultApyBreakdown / get_vault_apy_breakdown

​getAssets / get_assets

​Historical data

​getVaultHistoricalData / get_vault_historical_data

​getVaultHistoricalApy / get_vault_historical_apy

​getVaultHistoricalTvl / get_vault_historical_tvl

​getVaultHistoricalSharePrice / get_vault_historical_share_price

​getHistoricalAssetPrices / get_historical_asset_prices

​Portfolio

​getPositions / get_positions

​getPosition / get_position

​getIdleAssets / get_idle_assets

​getDepositOptions / get_deposit_options

​getBestVault / get_best_vault

​getUserVaultTotalReturns / get_vault_total_returns

​getUserVaultEvents / get_vault_holder_events

​Transactions

​getTransactionsContext / get_transactions_context

​getActions / get_actions

​Rewards

​getRewardsTransactionsContext / get_rewards_context

​getRewardsClaimActions / get_rewards_claim

​Benchmarks

​getBenchmarks / get_benchmarks

​getHistoricalBenchmarks / get_historical_benchmarks

​Error handling

​TypeScript types

Installation & setup

Vault discovery

`getAllVaults` / `get_all_vaults`

`getVault` / `get_vault`

`getVaultApyBreakdown` / `get_vault_apy_breakdown`

`getAssets` / `get_assets`

Historical data

`getVaultHistoricalData` / `get_vault_historical_data`

`getVaultHistoricalApy` / `get_vault_historical_apy`

`getVaultHistoricalTvl` / `get_vault_historical_tvl`

`getVaultHistoricalSharePrice` / `get_vault_historical_share_price`

`getHistoricalAssetPrices` / `get_historical_asset_prices`

Portfolio

`getPositions` / `get_positions`

`getPosition` / `get_position`

`getIdleAssets` / `get_idle_assets`

`getDepositOptions` / `get_deposit_options`

`getBestVault` / `get_best_vault`

`getUserVaultTotalReturns` / `get_vault_total_returns`

`getUserVaultEvents` / `get_vault_holder_events`

Transactions

`getTransactionsContext` / `get_transactions_context`

`getActions` / `get_actions`

Rewards

`getRewardsTransactionsContext` / `get_rewards_context`

`getRewardsClaimActions` / `get_rewards_claim`

Benchmarks

`getBenchmarks` / `get_benchmarks`

`getHistoricalBenchmarks` / `get_historical_benchmarks`

Error handling

TypeScript types