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)

Getting Started

Smart Wallet API

Intelligence Layer

Signature

Returns

Return Type

Example

Performance

Use Cases

Example Use Cases

Dashboard Summary

TVL Monitoring

TVL by Chain Analysis

Notes

​Signature

​Returns

​Return Type

​Example

​Performance

​Use Cases

​Example Use Cases

​Dashboard Summary

​TVL Monitoring

​TVL by Chain Analysis

​Notes

Signature

Returns

Return Type

Example

Performance

Use Cases

Example Use Cases

Dashboard Summary

TVL Monitoring

TVL by Chain Analysis

Notes