Skip to main content
This tutorial walks you through building a yield integration for a wallet application. You will detect idle assets in a user’s wallet, show them personalized deposit opportunities, prepare and execute a deposit transaction, and then track the resulting position. The full example code is available in the official tutorial repositories: 
git clone https://github.com/WallfacerLabs/js-examples.git

​
Run the example

1

Install dependencies

cd js-examples/
npm install
2

Set your API key

export VAULTS_FYI_API_KEY="your_api_key_here"
3

Run the wallet integration script

npm run wallet_integration

​
Step-by-step walkthrough

​
1. Initialize the SDK

Create the client once and reuse it across all calls. 
import pkg from '@vaultsfyi/sdk';
const { VaultsSdk } = pkg;

const vaultsFyi = new VaultsSdk({
  apiKey: process.env.VAULTS_FYI_API_KEY,
});

​
2. Detect idle assets

Call getIdleAssets to find tokens sitting in a wallet that are not currently earning yield. This is the starting point for any yield nudge or suggestion UI. 
async function getUserBalances(userAddress) {
  const idleAssets = await vaultsFyi.getIdleAssets({
    path: { userAddress }
  });

  return idleAssets;
}
The response includes each asset’s symbol, balance, and USD value. Use this data to decide which assets to surface deposit options for.
Filter out assets below a minimum USD threshold before presenting options to the user. Small balances often produce high gas costs relative to yield earned.

​
3. Get personalized deposit options

Call getDepositOptions with a list of assets the user holds. The API returns ranked vault opportunities filtered to those assets, sorted by APY. 
async function getBestDepositOptions(userAddress) {
  const depositOptions = await vaultsFyi.getDepositOptions({
    path: { userAddress },
    query: { allowedAssets: ['USDC', 'USDS'] }
  });

  return depositOptions;
}
Each option in the response includes the vault address, network, protocol name, current APY, and TVL — everything you need to render a yield card in your UI.

​
4. Check transaction context

Before building a deposit transaction, call getTransactionsContext to confirm the vault is ready to accept a deposit. The response tells you which steps are required (for example, an ERC-20 approval before the deposit itself) and the current deposit limits. 
async function getTransactionContext(userAddress, network, vaultAddress) {
  const context = await vaultsFyi.getTransactionsContext({
    path: { userAddress, network, vaultAddress }
  });

  return context;
}

​
5. Build the deposit transaction

Call getActions with action: 'deposit' to receive ready-to-sign transaction calldata. Pass the calldata directly to the user’s wallet or signer library — no intermediate contract needed. 
async function generateDepositTransaction(
  userAddress,
  network,
  vaultAddress,
  assetAddress,
  amount
) {
  const transaction = await vaultsFyi.getActions({
    path: {
      action: 'deposit',
      userAddress,
      network,
      vaultAddress
    },
    query: {
      amount,
      assetAddress
    }
  });

  return transaction;
}
getActions may return multiple steps when an approval is required before the deposit. Execute each step in order using the user’s wallet.
Always call getTransactionsContext before getActions. Skipping the context check can result in failed transactions if deposit limits are reached or approvals are stale.

​
6. Track the user’s position

After the deposit confirms on-chain, call getPositions to retrieve the user’s updated vault positions. Display the balance, current APY, and accumulated returns in your portfolio view. 
async function getUserPositions(userAddress) {
  const positions = await vaultsFyi.getPositions({
    path: { userAddress }
  });

  return positions;
}
To show total earnings for a specific vault, use getUserVaultTotalReturns with the same userAddress, network, and vaultAddress.

​
What to build next

  • Surface pending rewards with getRewardsTransactionsContext and let users claim in one tap using getRewardsClaimActions.
  • Show per-vault event history (deposits and withdrawals) with getUserVaultEvents.
  • Compare the vault’s current APY against benchmark rates using getBenchmarks to give users context on whether the yield is competitive.
See the SDK Reference for full parameter details on every method used in this tutorial.