AI Tool Guide

// Zapper price aggregation
async function getTokenPrices(
  client: ZapperClient,
  tokens: string[],
  network: string = ethereum
): Promise<Map<string, number>> {
  const prices = new Map<string, number>();
  
  // Batch price requests (max 100 per call)
  const batchSize = 100;
  for (let i = 0; i < tokens.length; i += batchSize) {
    const batch = tokens.slice(i, i + batchSize);
    
    const response = await client.v2.prices.getPrices({
      network,
      addresses: batch
    });
    
    response.data.forEach((price: any) => {
      prices.set(price.address.toLowerCase(), price.priceUSD);
    });
  }
  
  return prices;
}

// Usage
const tokenPrices = await getTokenPrices(
  client,
  [
    0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2, // WETH
    0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48, // USDC
    0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984  // UNI
  ]
);

console.log('WETH:', tokenPrices.get(0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2));
console.log('USDC:', tokenPrices.get(0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48));

# Step 1: Sign up at https://zapper.xyz and navigate to Developer Settings
# Step 2: Generate an API key
# Step 3: Store securely in environment variables

export ZAPPER_API_KEY="your_api_key_here"
export ZAPPER_API_URL="https://api.zapper.xyz"

// Initialize Zapper SDK with authentication
import { ZapperClient } from '@zapper-fi/zapper-api';

// Option 1: Direct initialization
const client = new ZapperClient({
  apiKey: process.env.ZAPPER_API_KEY,
  timeout: 30000,           // 30 second timeout
  retries: 3                // Auto-retry failed requests
});

// Option 2: Using environment configuration
const client = ZapperClient.fromEnvironment();

# Python SDK setup
import os
from zapper_api import ZapperClient

client = ZapperClient(
    api_key=os.getenv(ZAPPER_API_KEY),
    base_url='https://api.zapper.xyz'
)

# Verify connection
health = client.health.check()
print(f"API Status: {health.status}")
print(f"Supported Networks: {len(health.networks)}")
print(f"Integrated Protocols: {health.protocolCount}")

# cURL authentication example
curl -X GET "https://api.zapper.xyz/v2/balances?addresses[]=0x...&networks[]=ethereum" \
  -H "Authorization: Bearer ${ZAPPER_API_KEY}" \
  -H "Content-Type: application/json"

// Get comprehensive portfolio with all positions
async function getFullPortfolio(address: string) {
  const response = await client.v2.balances.getBalances({
    addresses: [address],
    networks: [ethereum, polygon, arbitrum, optimism, base, avalanche],
    includeMeta: true
  });

  // Process and categorize positions
  const breakdown = {
    wallet: { value: 0, tokens: [] },
    lending: { supplied: 0, borrowed: 0, netValue: 0, protocols: [] },
    liquidityPools: { value: 0, pools: [] },
    staking: { value: 0, positions: [] },
    nfts: { value: 0, collections: [] },
    claimable: { value: 0, rewards: [] }
  };

  response.data.forEach((position: any) => {
    const category = categorizePosition(position);
    
    switch (category) {
      case wallet: breakdown.wallet.value += position.balanceUSD;
        breakdown.wallet.tokens.push({
          symbol: position.symbol,
          balance: formatUnits(position.balance, position.decimals),
          valueUSD: position.balanceUSD
        });
        break;
        
      case lending: const supplied = position.balances?.supplied?.balanceUSD || 0;
        const borrowed = position.balances?.borrowed?.balanceUSD || 0;
        breakdown.lending.supplied += supplied;
        breakdown.lending.borrowed += borrowed;
        breakdown.lending.netValue += (supplied - borrowed);
        breakdown.lending.protocols.push(position.appName);
        break;
        
      case liquidity: breakdown.liquidityPools.value += position.balanceUSD;
        breakdown.liquidityPools.pools.push({
          protocol: position.appName,
          tokens: position.tokens.map((t: any) => t.symbol),
          valueUSD: position.balanceUSD,
          apy: position.yield?.apy || 0
        });
        break;
        
      case staking: breakdown.staking.value += position.balanceUSD;
        breakdown.staking.positions.push(position);
        break;
    }
  });

  return breakdown;
}

// Helper function
function categorizePosition(position: any): string {
  if (position.appId === tokens) return wallet;
  if (['aave-v3', compound, morpho, spark].includes(position.appId)) return lending;
  if (['uniswap-v3', 'balancer-v2', curve, sushi].includes(position.appId)) return liquidity;
  if (position.positionType === staking) return staking;
  return other;
}

// Track NFT holdings across marketplaces
async function getNFTPortfolio(address: string) {
  const nfts = await client.v2.nfts.getNftsForAddress({
    address,
    networks: [ethereum, polygon],
    includeFloorPrice: true,
    includeMetadata: true
  });

  const nftSummary = {
    totalCollections: 0,
    totalNFTs: 0,
    estimatedValueUSD: 0,
    collections: [] as any[]
  };

  nfts.data.forEach((collection: any) => {
    const collectionValue = collection.floorPriceUSD * collection.tokenIds.length;
    
    nftSummary.totalCollections++;
    nftSummary.totalNFTs += collection.tokenIds.length;
    nftSummary.estimatedValueUSD += collectionValue;
    
    nftSummary.collections.push({
      name: collection.collectionName,
      contract: collection.contractAddress,
      count: collection.tokenIds.length,
      floorPriceUSD: collection.floorPriceUSD,
      estimatedValueUSD: collectionValue,
      tokens: collection.tokenIds
    });
  });

  return nftSummary;
}

// Display NFT portfolio
const nftPortfolio = await getNFTPortfolio('0xMyAddress...');
console.log(````\n📊 NFT Portfolio Summary````);
console.log(````Collections: ${nftPortfolio.totalCollections}````);
console.log(````Total NFTs: ${nftPortfolio.totalNFTs}````);
console.log(````Estimated Value: $${nftPortfolio.estimatedValueUSD.toLocaleString()}````);

nftPortfolio.collections
  .sort((a, b) => b.estimatedValueUSD - a.estimatedValueUSD)
  .forEach(c => {
    console.log(````\n  ${c.name}: ${c.count} items @ $${c.floorPriceUSD.toFixed(2)} floor = $${c.estimatedValueUSD.toFixed(2)}````);
  });

// Track yield farming positions with APY analytics
interface YieldPosition {
  protocol: string;
  poolName: string;
  network: string;
  depositedTokens: TokenAmount[];
  depositedValueUSD: number;
  rewardTokens: RewardInfo[];
  apy: {
    total: number;
    base: number;        // Base pool APY
    rewards: number;     // Reward token APY
  };
  dailyYieldUSD: number;
  totalEarnedUSD: number;
  impermanentLoss?: number;
}

interface RewardInfo {
  token: string;
  tokenPriceUSD: number;
  dailyAmount: number;
  dailyValueUSD: number;
  claimableAmount: number;
}

// Fetch yield positions
async function getYieldPositions(address: string): Promise<YieldPosition[]> {
  const balances = await client.v2.balances.getBalances({
    addresses: [address],
    networks: [ethereum, arbitrum, optimism],
    appId: ['uniswap-v3', 'balancer-v2', curve, convex, yearn, pendle]
  });

  const yieldPositions: YieldPosition[] = [];

  balances.data.forEach((position: any) => {
    if (position.yield?.apy > 0) {
      yieldPositions.push({
        protocol: position.appName,
        poolName: position.label || 'Unknown Pool',
        network: position.network,
        depositedTokens: position.tokens.map((t: any) => ({
          symbol: t.symbol,
          amount: formatUnits(t.balance, t.decimals),
          valueUSD: t.balanceUSD
        })),
        depositedValueUSD: position.balanceUSD,
        rewardTokens: position.yield.rewardTokens?.map((r: any) => ({
          token: r.symbol,
          tokenPriceUSD: r.priceUSD,
          dailyAmount: r.dailyAmount,
          dailyValueUSD: r.dailyValueUSD,
          claimableAmount: r.claimable
        })) || [],
        apy: {
          total: position.yield.apy,
          base: position.yield.baseApy || 0,
          rewards: position.yield.rewardApy || 0
        },
        dailyYieldUSD: position.yield.dailyYieldUSD || 0,
        totalEarnedUSD: position.yield.totalEarnedUSD || 0,
        impermanentLoss: position.il?.percent
      });
    }
  });

  return yieldPositions.sort((a, b) => b.depositedValueUSD - a.depositedValueUSD);
}

// Display yield dashboard
const positions = await getYieldPositions('0xMyAddress...');

console.log('\n🌾 Active Yield Positions\n');
console.log('-'.repeat(80));

let totalDeposited = 0;
let totalDailyYield = 0;

positions.forEach(pos => {
  totalDeposited += pos.depositedValueUSD;
  totalDailyYield += pos.dailyYieldUSD;
  
  console.log(````\n${pos.protocol} — ${pos.poolName} (${pos.network})````);
  console.log(````  Deposited: $${pos.depositedValueUSD.toLocaleString()}````);
  console.log(````  APY: ${pos.apy.total.toFixed(2)}% (Base: ${pos.apy.base.toFixed(2)}% + Rewards: ${pos.apy.rewards.toFixed(2)}%)````);
  console.log(````  Daily Yield: $${pos.dailyYieldUSD.toFixed(2)}````);
  console.log(````  Total Earned: $${pos.totalEarnedUSD.toLocaleString()}````);
  
  if (pos.impermanentLoss) {
    console.log(````  ⚠️ IL: ${pos.impermanentLoss.toFixed(2)}%````);
  }
  
  pos.rewardTokens.forEach(r => {
    console.log(````  Reward: ${r.dailyAmount.toFixed(4)} ${r.token}/day ($${r.dailyValueUSD.toFixed(2)})````);
  });
});

console.log(````\n${'='.repeat(80)}````);
console.log(````Total Deposited: $${totalDeposited.toLocaleString()}````);
console.log(````Total Daily Yield: $${totalDailyYield.toFixed(2)} (${(totalDailyYield * 365 / totalDeposited * 100).toFixed(2)}% APY)````);
console.log(````Monthly Projection: $${(totalDailyYield * 30).toFixed(2)}````);

// Discover new yield opportunities
async function discoverYields(
  network: string = ethereum,
  minTvl: number = 1_000_000,  // $1M minimum TVL
  minApy: number = 5            // 5% minimum APY
) {
  const opportunities = await client.v2.yields.getYieldOpportunities({
    network,
    minTvl,
    minApy,
    sortBy: apy,
    sortDirection: desc,
    limit: 50
  });

  return opportunities.data.map((opp: any) => ({
    protocol: opp.protocol,
    poolName: opp.name,
    tokens: opp.tokens.map((t: any) => t.symbol),
    tvlUSD: opp.tvlUSD,
    apy: {
      total: opp.apy.total,
      base: opp.apy.base,
      rewards: opp.apy.rewards
    },
    riskLevel: opp.riskLevel,     // low | medium | high
    ilRisk: opp.impermanentLossRisk
  }));
}

// Find best yield opportunities
const bestYields = await discoverYields(ethereum, 10_000_000, 10);

console.log('\n🏆 Top Yield Opportunities (TVL > $10M, APY > 10%)\n');
bestYields.slice(0, 10).forEach((opp, i) => {
  console.log(````${i + 1}. ${opp.protocol} — ${opp.poolName}````);
  console.log(````   Tokens: ${opp.tokens.join('/')}````);
  console.log(````   TVL: $${(opp.tvlUSD / 1e6).toFixed(1)}M | APY: ${opp.apy.total.toFixed(2)}%````);
  console.log(````   Risk: ${opp.riskLevel} | IL Risk: ${opp.ilRisk || 'N/A'}````);
  console.log();
});

// Bridge + Zap In (cross-chain position entry)
async function bridgeAndZap(
  fromChain: string,       // Source chain
  toChain: string,          // Destination chain
  fromToken: string,
  amount: string,
  targetProtocol: string,
  targetPool: string
) {
  const route = await client.v2.bridge.getBridgeRoute({
    fromChain,
    toChain,
    fromToken,
    amount,
    recipient: '0xMyAddress...'
  });

  // Step 1: Bridge transaction
  const bridgeTx = await wallet.sendTransaction({
    to: route.bridgeContract,
    data: route.bridgeData,
    value: route.value
  });

  console.log(````Bridge tx: ${bridgeTx.hash}````);

  // Wait for bridge completion
  await client.v2.bridge.waitForBridge(bridgeTx.hash, fromChain, toChain);

  // Step 2: Zap into position on destination chain
  const zapTx = await client.v2.zap.generateZapInTransaction({
    fromToken: route.destToken,
    amount: route.destAmount,
    toProtocol: targetProtocol,
    toPool: targetPool
  });

  const receipt = await destChainWallet.sendTransaction({
    to: zapTx.to,
    data: zapTx.data,
    value: zapTx.value,
    gasLimit: zapTx.gasEstimate * 120n / 100n
  });

  return receipt.hash;
}

// Real-time portfolio updates via WebSocket
import { ZapperWebSocket } from '@zapper-fi/zapper-api';

const ws = new ZapperWebSocket({
  apiKey: process.env.ZAPPER_API_KEY,
  url: 'wss://ws.zapper.xyz'
});

// Subscribe to address updates
ws.subscribe('address:0xMyAddress...', (update: any) => {
  switch (update.type) {
    case balance_change: console.log(````💰 Balance update: ${update.token} = ${update.newBalance}````);
      break;
    case new_position: console.log(````📈 New position detected: ${update.protocol} — ${update.valueUSD}````);
      break;
    case yield_claimed: console.log(````🎁 Rewards claimed: ${update.amount} ${update.token}````);
      break;
    case nft_transfer: console.log(````🖼️ NFT transferred: ${update.collection} #${update.tokenId}````);
      break;
  }
});

// Connection management
ws.onConnect(() => console.log('Connected to Zapper WS'));
ws.onDisconnect(() => console.log('Disconnected, retrying...'));
ws.onError((err) => console.error('WS Error:', err));

// Historical portfolio performance
async function getHistoricalPerformance(
  address: string,
  days: number = 90
) {
  const history = await client.v2.analytics.getHistoricalBalances({
    address,
    granularity: daily,
    daysBack: days
  });

  const performance = {
    startValue: history.data[0]?.totalUSD || 0,
    endValue: history.data[history.data.length - 1]?.totalUSD || 0,
    peakValue: Math.max(...history.data.map((d: any) => d.totalUSD)),
    troughValue: Math.min(...history.data.map((d: any) => d.totalUSD)),
    dailyChanges: [] as any[]
  };

  // Calculate daily changes
  for (let i = 1; i < history.data.length; i++) {
    const prev = history.data[i - 1].totalUSD;
    const curr = history.data[i].totalUSD;
    const change = curr - prev;
    const changePct = (change / prev) * 100;

    performance.dailyChanges.push({
      date: history.data[i].timestamp,
      value: curr,
      change,
      changePct
    });
  }

  // Summary metrics
  const totalReturn = performance.endValue - performance.startValue;
  const totalReturnPct = (totalReturn / performance.startValue) * 100;

  console.log('\n📈 Portfolio Performance (Last 90 Days)');
  console.log(````Starting Value: $${performance.startValue.toLocaleString()}````);
  console.log(````Current Value: $${performance.endValue.toLocaleString()}````);
  console.log(````Peak Value: $${performance.peakValue.toLocaleString()}````);
  console.log(````Total Return: $${totalReturn.toLocaleString()} (${totalReturnPct.toFixed(2)}%)````);
  console.log(````Max Drawdown: ${((performance.peakValue - performance.troughValue) / performance.peakValue * 100).toFixed(2)}%````);

  return performance;
}

// Protocol-specific P&L
async function getProtocolPnL(
  address: string,
  protocol: string,
  days: number = 30
) {
  const pnl = await client.v2.analytics.getProtocolPnL({
    address,
    protocol,
    period: ````${days}d````
  });

  return {
    deposits: pnl.data.totalDeposited,
    withdrawals: pnl.data.totalWithdrawn,
    feesEarned: pnl.data.feesEarned,
    rewardsClaimed: pnl.data.rewardsClaimed,
    impermanentLoss: pnl.data.impermanentLoss,
    netPnL: pnl.data.netPnL
  };
}

// Batch portfolio queries for multiple addresses
async function batchPortfolioQuery(addresses: string[]) {
  const batchSize = 20;  // Max 20 addresses per request
  const results = [];

  for (let i = 0; i < addresses.length; i += batchSize) {
    const batch = addresses.slice(i, i + batchSize);

    const response = await client.v2.balances.getBalances({
      addresses: batch,
      networks: [ethereum, arbitrum, polygon]
    });

    results.push(...response.data);
  }

  // Aggregate across all addresses
  const aggregate = {
    totalValue: 0,
    protocolExposure: new Map<string, number>(),
    tokenExposure: new Map<string, number>()
  };

  results.forEach((portfolio: any) => {
    aggregate.totalValue += portfolio.totalUSD;
    
    // Protocol exposure
    portfolio.positions.forEach((pos: any) => {
      const current = aggregate.protocolExposure.get(pos.appName) || 0;
      aggregate.protocolExposure.set(pos.appName, current + pos.balanceUSD);
    });
  });

  return aggregate;
}

// Usage: Whale wallet analysis
const whaleAddresses = [
  '0x...',  // Known whale 1
  '0x...',  // Known whale 2
  // ... more addresses
];

const whaleData = await batchPortfolioQuery(whaleAddresses);
console.log(````Combined Portfolio Value: $${whaleData.totalValue.toLocaleString()}````);

// Top protocol exposure
const sortedExposure = [...whaleData.protocolExposure.entries()]
  .sort((a, b) => b[1] - a[1])
  .slice(0, 10);

console.log('\nTop Protocol Exposure:');
sortedExposure.forEach(([protocol, value]) => {
  console.log(````  ${protocol}: $${value.toLocaleString()}````);
});

// React hook for Zapper portfolio data
import { useState, useEffect } from react;
import { ZapperClient } from '@zapper-fi/zapper-api';

const client = new ZapperClient({ apiKey: process.env.REACT_APP_ZAPPER_KEY });

export function usePortfolio(address: string | undefined) {
  const [portfolio, setPortfolio] = useState<any>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    if (!address) return;

    const fetchPortfolio = async () => {
      setLoading(true);
      setError(null);

      try {
        const response = await client.v2.balances.getBalances({
          addresses: [address],
          networks: [ethereum, polygon, arbitrum]
        });

        setPortfolio(response.data);
      } catch (err) {
        setError(err instanceof Error ? err.message : 'Failed to fetch');
      } finally {
        setLoading(false);
      }
    };

    fetchPortfolio();

    // Auto-refresh every 60 seconds
    const interval = setInterval(fetchPortfolio, 60000);
    return () => clearInterval(interval);
  }, [address]);

  return { portfolio, loading, error };
}

// Dashboard component
export function PortfolioDashboard({ address }: { address: string }) {
  const { portfolio, loading, error } = usePortfolio(address);

  if (loading) return <div>Loading portfolio...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!portfolio) return null;

  return (
    <div className="dashboard">
      <h1>Portfolio Overview</h1>
      
      <div className="total-value">
        <h2>${portfolio.totalUSD?.toLocaleString()}</h2>
        <span>Total Net Worth</span>
      </div>

      <div className="positions-grid">
        {portfolio.positions?.map((pos: any) => (
          <PositionCard key={pos.key} position={pos} />
        ))}
      </div>
    </div>
  );
}

function PositionCard({ position }: { position: any }) {
  return (
    <div className="position-card">
      <div className="protocol">
        <img src={position.appImg} alt={position.appName} />
        <span>{position.appName}</span>
      </div>
      <div className="value">
        ${position.balanceUSD?.toLocaleString()}
      </div>
      {position.yield?.apy > 0 && (
        <div className="apy">
          APY: {position.yield.apy.toFixed(2)}%
        </div>
      )}
    </div>
  );
}

// Automated yield monitoring and alerts
import { schedule } from 'node-cron';

interface YieldAlert {
  condition: apy_drop | apy_spike | il_warning | reward_change;
  threshold: number;
  protocol?: string;
  action: notify | auto_compound | exit;
}

class YieldMonitor {
  private client: ZapperClient;
  private alerts: YieldAlert[] = [];

  constructor(apiKey: string) {
    this.client = new ZapperClient({ apiKey });
  }

  addAlert(alert: YieldAlert) {
    this.alerts.push(alert);
  }

  async checkPositions(address: string) {
    const positions = await this.getYieldPositions(address);
    const previous = await this.loadPreviousData(address);

    for (const position of positions) {
      const prev = previous.get(position.poolName);

      for (const alert of this.alerts) {
        if (alert.protocol && alert.protocol !== position.protocol) continue;

        switch (alert.condition) {
          case apy_drop: if (prev && (position.apy.total / prev.apy - 1) * 100 < -alert.threshold) {
              await this.sendAlert(````🚨 APY dropped ${alert.threshold}% on ${position.poolName}: ${position.apy.total.toFixed(2)}%````);
            }
            break;

          case il_warning: if (position.impermanentLoss && position.impermanentLoss > alert.threshold) {
              await this.sendAlert(````⚠️ IL warning on ${position.poolName}: ${position.impermanentLoss.toFixed(2)}%````);
            }
            break;

          case reward_change: const rewardChange = position.rewardTokens.reduce(
              (sum, r) => sum + r.dailyValueUSD, 0
            );
            if (prev && Math.abs(rewardChange - prev.dailyRewards) > alert.threshold) {
              await this.sendAlert(````💰 Reward change on ${position.poolName}: $${rewardChange.toFixed(2)}/day````);
            }
            break;
        }
      }
    }

    // Save current data for next comparison
    await this.saveCurrentData(address, positions);
  }

  private async sendAlert(message: string) {
    // Send to Telegram, Discord, or email
    await fetch(process.env.ALERT_WEBHOOK_URL, {
      method: POST,
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text: message })
    });
  }

  startMonitoring(address: string, interval: string = '*/15 * * * *') {
    // Check every 15 minutes by default
    schedule(interval, () => this.checkPositions(address));
    console.log(````Yield monitoring started for ${address}````);
  }
}

// Usage
const monitor = new YieldMonitor(process.env.ZAPPER_API_KEY);

monitor.addAlert({
  condition: apy_drop,
  threshold: 20,  // Alert if APY drops 20%
  action: notify
});

monitor.addAlert({
  condition: il_warning,
  threshold: 5,   // Alert if IL exceeds 5%
  action: notify
});

monitor.startMonitoring('0xMyAddress...');