> ## 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.

# SDK Method Reference

> Complete method reference for the TypeScript and Python Vaults.fyi SDKs — vault discovery, historical data, portfolio, transactions, rewards, and benchmarks.

<Note>
  For installation and client setup, see the [quickstart guide](/sdk/quickstart).
</Note>

## Installation & setup

<CodeGroup>
  ```bash TypeScript theme={null}
  npm install @vaultsfyi/sdk
  ```

  ```bash Python theme={null}
  pip install vaultsfyi
  ```
</CodeGroup>

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { VaultsSdk } from '@vaultsfyi/sdk'

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

  ```python Python theme={null}
  from vaultsfyi import VaultsSdk

  client = VaultsSdk(api_key="YOUR_API_KEY")
  ```
</CodeGroup>

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.

<CodeGroup>
  ```typescript TypeScript theme={null}
  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,
    }
  })
  ```

  ```python Python theme={null}
  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,
  )
  ```
</CodeGroup>

### `getVault` / `get_vault`

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const vault = await sdk.getVault({
    path: {
      network: 'mainnet',
      vaultAddress: '0x9D39A5DE30e57443BfF2A8307A4256c8797A3497'
    }
  })
  ```

  ```python Python theme={null}
  vault = client.get_vault(
      network="mainnet",
      vault_address="0x9D39A5DE30e57443BfF2A8307A4256c8797A3497",
  )
  ```
</CodeGroup>

### `getVaultApyBreakdown` / `get_vault_apy_breakdown`

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const apy = await sdk.getVaultApyBreakdown({
    path: {
      network: 'mainnet',
      vaultAddress: '0x1234...'
    }
  })
  ```

  ```python Python theme={null}
  apy = client.get_vault_apy_breakdown(
      network="mainnet",
      vault_address="0x1234...",
  )
  ```
</CodeGroup>

### `getAssets` / `get_assets`

Lists all tracked assets across networks.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const assets = await sdk.getAssets({
    query: { page: 0, perPage: 100 }
  })
  ```

  ```python Python theme={null}
  assets = client.get_assets(page=0, per_page=100)
  ```
</CodeGroup>

***

## Historical data

### `getVaultHistoricalData` / `get_vault_historical_data`

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

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

  ```python Python theme={null}
  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,
  )
  ```
</CodeGroup>

### `getVaultHistoricalApy` / `get_vault_historical_apy`

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const apyHistory = await sdk.getVaultHistoricalApy({
    path: { network: 'mainnet', vaultAddress: '0x1234...' },
    query: {
      apyInterval: '7day',
      granularity: '1day',
      fromTimestamp: 1735689600,
      toTimestamp: 1743465600
    }
  })
  ```

  ```python Python theme={null}
  apy_history = client.get_vault_historical_apy(
      network="mainnet",
      vault_address="0x1234...",
      apy_interval="7day",
      granularity="1day",
      from_timestamp=1735689600,
      to_timestamp=1743465600,
  )
  ```
</CodeGroup>

### `getVaultHistoricalTvl` / `get_vault_historical_tvl`

TVL-only time series.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const tvlHistory = await sdk.getVaultHistoricalTvl({
    path: { network: 'mainnet', vaultAddress: '0x1234...' },
    query: { fromTimestamp: 1735689600, toTimestamp: 1743465600 }
  })
  ```

  ```python Python theme={null}
  tvl_history = client.get_vault_historical_tvl(
      network="mainnet",
      vault_address="0x1234...",
      from_timestamp=1735689600,
      to_timestamp=1743465600,
  )
  ```
</CodeGroup>

### `getVaultHistoricalSharePrice` / `get_vault_historical_share_price`

Share price time series.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const sharePriceHistory = await sdk.getVaultHistoricalSharePrice({
    path: { network: 'mainnet', vaultAddress: '0x1234...' },
    query: { fromTimestamp: 1735689600, toTimestamp: 1743465600 }
  })
  ```

  ```python Python theme={null}
  share_price_history = client.get_vault_historical_share_price(
      network="mainnet",
      vault_address="0x1234...",
      from_timestamp=1735689600,
      to_timestamp=1743465600,
  )
  ```
</CodeGroup>

### `getHistoricalAssetPrices` / `get_historical_asset_prices`

Historical USD prices for a tracked asset.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const prices = await sdk.getHistoricalAssetPrices({
    path: {
      network: 'mainnet',
      assetAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
    },
    query: {
      granularity: '1day',
      fromTimestamp: 1735689600,
      toTimestamp: 1743465600
    }
  })
  ```

  ```python Python theme={null}
  prices = client.get_historical_asset_prices(
      network="mainnet",
      asset_address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      granularity="1day",
      from_timestamp=1735689600,
      to_timestamp=1743465600,
  )
  ```
</CodeGroup>

***

## Portfolio

### `getPositions` / `get_positions`

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const positions = await sdk.getPositions({
    path: { userAddress: '0xYourWallet' },
    query: {
      allowedNetworks: ['mainnet', 'base'],
      apyInterval: '7day',
      sortBy: 'balanceUsd',
      sortOrder: 'desc'
    }
  })
  ```

  ```python Python theme={null}
  positions = client.get_positions(
      user_address="0xYourWallet",
      allowed_networks=["mainnet", "base"],
      apy_interval="7day",
      sort_by="balanceUsd",
      sort_order="desc",
  )
  ```
</CodeGroup>

### `getPosition` / `get_position`

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const position = await sdk.getPosition({
    path: {
      userAddress: '0xYourWallet',
      network: 'mainnet',
      vaultAddress: '0x1234...'
    },
    query: { apyInterval: '7day' }
  })
  ```

  ```python Python theme={null}
  position = client.get_position(
      user_address="0xYourWallet",
      network="mainnet",
      vault_address="0x1234...",
      apy_interval="7day",
  )
  ```
</CodeGroup>

### `getIdleAssets` / `get_idle_assets`

Returns assets sitting in a wallet not currently earning yield.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const idle = await sdk.getIdleAssets({
    path: { userAddress: '0xYourWallet' },
    query: {
      allowedNetworks: ['mainnet', 'base'],
      minUsdAssetValueThreshold: 10,
      sortBy: 'balanceUsd',
      sortDirection: 'desc'
    }
  })
  ```

  ```python Python theme={null}
  idle = client.get_idle_assets(
      user_address="0xYourWallet",
      allowed_networks=["mainnet", "base"],
      min_usd_asset_value_threshold=10,
      sort_by="balanceUsd",
      sort_direction="desc",
  )
  ```
</CodeGroup>

### `getDepositOptions` / `get_deposit_options`

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  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']
    }
  })
  ```

  ```python Python theme={null}
  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"],
  )
  ```
</CodeGroup>

### `getBestVault` / `get_best_vault`

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const best = await sdk.getBestVault({
    path: { userAddress: '0xYourWallet' },
    query: {
      allowedNetworks: ['mainnet', 'base'],
      onlyTransactional: true,
      apyInterval: '7day'
    }
  })
  ```

  ```python Python theme={null}
  best = client.get_best_vault(
      user_address="0xYourWallet",
      allowed_networks=["mainnet", "base"],
      only_transactional=True,
      apy_interval="7day",
  )
  ```
</CodeGroup>

### `getUserVaultTotalReturns` / `get_vault_total_returns`

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const returns = await sdk.getUserVaultTotalReturns({
    path: {
      userAddress: '0xYourWallet',
      network: 'mainnet',
      vaultAddress: '0x1234...'
    }
  })
  ```

  ```python Python theme={null}
  returns = client.get_vault_total_returns(
      user_address="0xYourWallet",
      network="mainnet",
      vault_address="0x1234...",
  )
  ```
</CodeGroup>

### `getUserVaultEvents` / `get_vault_holder_events`

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const events = await sdk.getUserVaultEvents({
    path: {
      userAddress: '0xYourWallet',
      network: 'mainnet',
      vaultAddress: '0x1234...'
    }
  })
  ```

  ```python Python theme={null}
  events = client.get_vault_holder_events(
      user_address="0xYourWallet",
      network="mainnet",
      vault_address="0x1234...",
  )
  ```
</CodeGroup>

***

## 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.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const context = await sdk.getTransactionsContext({
    path: {
      userAddress: '0xYourWallet',
      network: 'mainnet',
      vaultAddress: '0x1234...'
    }
  })
  ```

  ```python Python theme={null}
  context = client.get_transactions_context(
      user_address="0xYourWallet",
      network="mainnet",
      vault_address="0x1234...",
  )
  ```
</CodeGroup>

### `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`.

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

  ```python Python theme={null}
  actions = client.get_actions(
      action="deposit",
      user_address="0xYourWallet",
      network="mainnet",
      vault_address="0x1234...",
      asset_address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      amount="1000000000",  # 1000 USDC (6 decimals)
  )
  ```
</CodeGroup>

***

## Rewards

### `getRewardsTransactionsContext` / `get_rewards_context`

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const rewardsContext = await sdk.getRewardsTransactionsContext({
    path: { userAddress: '0xYourWallet' }
  })
  ```

  ```python Python theme={null}
  rewards_context = client.get_rewards_context(
      user_address="0xYourWallet",
  )
  ```
</CodeGroup>

### `getRewardsClaimActions` / `get_rewards_claim`

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const claimActions = await sdk.getRewardsClaimActions({
    path: { userAddress: '0xYourWallet' },
    query: {
      claimIds: ['claim-id-1', 'claim-id-2']
    }
  })
  ```

  ```python Python theme={null}
  claim_actions = client.get_rewards_claim(
      user_address="0xYourWallet",
      claim_ids=["claim-id-1", "claim-id-2"],
  )
  ```
</CodeGroup>

***

## Benchmarks

### `getBenchmarks` / `get_benchmarks`

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const benchmarks = await sdk.getBenchmarks({
    path: { network: 'mainnet' },
    query: { code: 'usd' }
  })
  ```

  ```python Python theme={null}
  benchmarks = client.get_benchmarks(
      network="mainnet",
      code="usd",
  )
  ```
</CodeGroup>

### `getHistoricalBenchmarks` / `get_historical_benchmarks`

Returns paginated historical benchmark rates within a time range.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const historicalBenchmarks = await sdk.getHistoricalBenchmarks({
    path: { network: 'mainnet' },
    query: {
      code: 'usd',
      page: 0,
      perPage: 90,
      fromTimestamp: 1735689600,
      toTimestamp: 1743465600
    }
  })
  ```

  ```python Python theme={null}
  historical_benchmarks = client.get_historical_benchmarks(
      network="mainnet",
      code="usd",
      page=0,
      per_page=90,
      from_timestamp=1735689600,
      to_timestamp=1743465600,
  )
  ```
</CodeGroup>

***

## Error handling

<CodeGroup>
  ```typescript TypeScript theme={null}
  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}`)
    }
  }
  ```

  ```python Python theme={null}
  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")
  ```
</CodeGroup>

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.

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