Skip to main content

getSdkKeyTVL

Get the total TVL (Total Value Locked) across all smart wallets created via your SDK API key, with per-wallet breakdown and position details.

info

This method does not require a wallet connection - only your SDK API key is needed.

Signature​

getSdkKeyTVL(): Promise<SdkKeyTVLResponse>

Returns​

Total TVL across all allowed wallets with detailed breakdown

Return Type​

interface SdkKeyTVLResponse {
  success: boolean;
  allowedWallets: Address[];
  totalTvl: number;
  tvlByWallet: WalletTVL[];
  metadata?: {
    sdkKeyId: string;
    clientName: string;
    walletsCount: number;
  };
}

interface WalletTVL {
  walletAddress: Address;
  tvl: number;
  positions?: {
    chainId: number;
    protocol: string;
    amount: number;
  }[];
}

Example​

// No wallet connection required
const result = await sdk.getSdkKeyTVL();

console.log("Client:", result.metadata.clientName);
console.log("Total wallets:", result.metadata.walletsCount);
console.log("Total TVL:", result.totalTvl, "USD");

// Display top wallets by TVL
const topWallets = result.tvlByWallet
  .sort((a, b) => b.tvl - a.tvl)
  .slice(0, 5);

topWallets.forEach(wallet => {
  console.log(`${wallet.walletAddress}: $${wallet.tvl.toFixed(2)}`);

  wallet.positions?.forEach(pos => {
    console.log(`  - Chain ${pos.chainId}: ${pos.protocol} = $${pos.amount.toFixed(2)}`);
  });
});

Performance​

This method uses efficient server-side calculation:

  • Single API call regardless of wallet count
  • Fast database query with proper indexes
  • Optimized for large numbers of wallets (100+)
  • No N+1 query issues

Use Cases​

  • B2B Dashboards: Display total TVL across all user wallets
  • Analytics: Track TVL growth over time
  • Monitoring: Alert when TVL drops below threshold
  • Reporting: Generate reports on user activity and balances
  • Billing: Calculate usage-based pricing based on TVL

Example Use Cases​

Dashboard Summary​

async function updateDashboard() {
  const tvl = await sdk.getSdkKeyTVL();

  // Display metrics
  displayMetric('total-wallets', tvl.metadata.walletsCount);
  displayMetric('total-tvl', `$${tvl.totalTvl.toFixed(2)}`);

  // Show top wallets
  const topWallets = tvl.tvlByWallet
    .sort((a, b) => b.tvl - a.tvl)
    .slice(0, 10);

  displayWalletTable(topWallets);
}

TVL Monitoring​

async function monitorTvl() {
  const result = await sdk.getSdkKeyTVL();

  // Alert if TVL drops significantly
  if (result.totalTvl < THRESHOLD_TVL) {
    await sendAlert({
      type: 'LOW_TVL',
      message: `TVL dropped to $${result.totalTvl.toFixed(2)}`,
    });
  }

  // Track individual wallet TVL
  for (const wallet of result.tvlByWallet) {
    if (wallet.tvl > WALLET_TVL_THRESHOLD) {
      await sendAlert({
        type: 'HIGH_WALLET_TVL',
        wallet: wallet.walletAddress,
        tvl: wallet.tvl,
      });
    }
  }
}

TVL by Chain Analysis​

async function analyzeTvlByChain() {
  const result = await sdk.getSdkKeyTVL();

  // Calculate TVL by chain
  const tvlByChain = new Map<number, number>();

  result.tvlByWallet.forEach(wallet => {
    wallet.positions?.forEach(pos => {
      const current = tvlByChain.get(pos.chainId) || 0;
      tvlByChain.set(pos.chainId, current + pos.amount);
    });
  });

  // Display results
  tvlByChain.forEach((amount, chainId) => {
    console.log(`Chain ${chainId}: $${amount.toFixed(2)}`);
  });
}

Notes​

  • Only returns data for wallets created via the authenticated SDK API key
  • TVL is calculated from active positions only
  • Amounts are in USD (converted from USDC with 6 decimals)
  • Wallets with no positions have 0 TVL
  • Position breakdown includes chain, protocol, and amount
  • Results are sorted by natural order (not by TVL - sort client-side if needed)