Skip to main content
For installation and client setup, see the quickstart guide.

​
Installation & setup

npm install @vaultsfyi/sdk

import { VaultsSdk } from '@vaultsfyi/sdk'

const sdk = new VaultsSdk({ apiKey: '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,
  }
})

​
getVault / get_vault

Returns full detail for a single vault by network and address. 
const vault = await sdk.getVault({
  path: {
    network: 'mainnet',
    vaultAddress: '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...'
  }
})

​
getAssets / get_assets

Lists all tracked assets across networks. 
const assets = await sdk.getAssets({
  query: { page: 0, perPage: 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
  }
})

​
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
  }
})

​
getVaultHistoricalTvl / get_vault_historical_tvl

TVL-only time series. 
const tvlHistory = await sdk.getVaultHistoricalTvl({
  path: { network: 'mainnet', vaultAddress: '0x1234...' },
  query: { fromTimestamp: 1735689600, toTimestamp: 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 }
})

​
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
  }
})

​
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'
  }
})

​
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' }
})

​
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'
  }
})

​
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']
  }
})

​
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'
  }
})

​
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...'
  }
})

​
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...'
  }
})

​
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...'
  }
})

​
getActions / get_actions

Returns ready-to-sign transaction calldata for a vault action. Execute actions in order — each must confirm on-chain 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)
  }
})

​
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' }
})

​
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']
  }
})

​
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' }
})

​
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
  }
})

​
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}`)
  }
}
The Python SDK exposes five exception classes, all inheriting from VaultsFyiError:
ExceptionCause
HttpResponseErrorAny non-2xx HTTP response
AuthenticationErrorInvalid or missing API key
ForbiddenErrorEndpoint requires a higher plan tier
RateLimitErrorToo many requests
NetworkErrorConnection 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