Documentation Index
Fetch the complete documentation index at: https://docs.vaults.fyi/llms.txt
Use this file to discover all available pages before exploring further.
Installation & setup
npm install @vaultsfyi/sdk
import { VaultsSdk } from '@vaultsfyi/sdk'
const sdk = new VaultsSdk({ apiKey: 'YOUR_API_KEY' })
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 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)
}
})
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}`)
}
}
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
