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.

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;
  totalVolume: number;
  tvlByWallet: WalletTVL[];
  metadata?: {
    sdkKeyId: string;
    clientName: string;
    walletsCount: number;
  };
}

interface WalletTVL {
  walletAddress: Address;
  tvl: number; // USD
  positions?: {
    chainId: number;
    protocol: string;
    amount: number; // USD
    assetType: string; // underlying asset (e.g. "usdc", "eth", "btc")
  }[];
}

All monetary fields (totalTvl, totalVolume, tvl, and amount) are returned in USD. Balances are converted server-side before aggregation (USDC/USDT at 1:1, WETH/cbETH via Chainlink ETH price, WBTC/cbBTC via Chainlink BTC price).

assetType identifies the underlying deposited asset — it does not change the unit of amount. Positions can be filtered with ?assetType=eth, but returned amounts remain in USD.

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");
console.log("Total Volume:", result.totalVolume, "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.assetType}) = $${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)}`);
  displayMetric('total-volume', `$${tvl.totalVolume.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
• Volume is calculated from rebalancing activity
• All amounts (totalTvl, totalVolume, tvl, amount) are in USD, converted server-side from the underlying asset
• assetType indicates the deposited asset (e.g. usdc, eth, btc) — amounts are still in USD
• Optional ?assetType=eth filter limits returned positions; amounts remain in USD
• Wallets with no positions have 0 TVL
• Position breakdown includes chain, protocol, amount (USD), and assetType
• Results are sorted by natural order (not by TVL - sort client-side if needed)