Portfolio Operations

/**
 * Get token balances for an address across multiple chains
 * @param owner - Address to get portfolio for
 * @param options - Portfolio query options
 * @returns Promise resolving to token balances
 */
getTokenBalances(
  owner: string,
  options?: GetTokenBalancesOptions
): Promise<GetTokenBalancesResponse>;

/**
 * Get detailed token information for an owner
 * @param owner - Address to get tokens for
 * @param options - Query options and filters
 * @returns Promise resolving to detailed token data
 */
getTokensForOwner(
  owner: string,
  options?: GetTokensForOwnerOptions
): Promise<GetTokensForOwnerResponse>;

interface GetTokenBalancesOptions {
  networks?: Network[];
  tokenAddresses?: string[];
  includeMetadata?: boolean;
  includeNativeBalance?: boolean;
  excludeSpam?: boolean;
}

interface GetTokenBalancesResponse {
  address: string;
  balances: CrossChainTokenBalance[];
  totalValueUsd?: number;
  lastUpdated: string;
}

interface CrossChainTokenBalance {
  network: Network;
  contractAddress: string;
  name: string;
  symbol: string;
  decimals: number;
  balance: string;
  balanceFormatted: string;
  valueUsd?: number;
  price?: number;
  priceChange24h?: number;
  logo?: string;
}

interface GetTokensForOwnerOptions {
  networks?: Network[];
  contractAddresses?: string[];
  pageKey?: string;
  pageSize?: number;
  includeNfts?: boolean;
  includeNativeTokens?: boolean;
}

interface GetTokensForOwnerResponse {
  address: string;
  tokens: PortfolioToken[];
  nfts?: PortfolioNft[];
  pageKey?: string;
  totalValue?: PortfolioValue;
}

interface PortfolioToken {
  network: Network;
  contractAddress: string;
  name: string;
  symbol: string;
  decimals: number;
  balance: string;
  balanceFormatted: string;
  metadata: TokenMetadata;
  valueUsd?: number;
  allocation?: number; // percentage of total portfolio
}

interface PortfolioNft {
  network: Network;
  contractAddress: string;
  tokenId: string;
  name: string;
  description: string;
  media: Media[];
  floorPrice?: number;
  estimatedValue?: number;
}

interface PortfolioValue {
  totalUsd: number;
  breakdown: PortfolioBreakdown;
}

interface PortfolioBreakdown {
  tokens: number;
  nfts: number;
  defi: number;
  staking: number;
}

/**
 * Get transaction history for an address
 * @param params - Transaction query parameters
 * @returns Promise resolving to transaction history
 */
getTransactions(params: GetTransactionsParams): Promise<GetTransactionsResponse>;

/**
 * Get DeFi activity and positions for an address
 * @param address - Address to get DeFi activity for
 * @param options - DeFi query options
 * @returns Promise resolving to DeFi positions and activity
 */
getDefiActivity(
  address: string,
  options?: GetDefiActivityOptions
): Promise<GetDefiActivityResponse>;

interface GetTransactionsParams {
  address: string;
  networks?: Network[];
  fromBlock?: number;
  toBlock?: number;
  category?: TransactionCategory[];
  order?: SortingOrder;
  pageKey?: string;
  pageSize?: number;
  includeTokenTransfers?: boolean;
  includeNftTransfers?: boolean;
}

interface GetTransactionsResponse {
  address: string;
  transactions: PortfolioTransaction[];
  pageKey?: string;
  totalCount?: number;
}

interface PortfolioTransaction {
  hash: string;
  network: Network;
  blockNumber: number;
  timestamp: number;
  from: string;
  to: string;
  value: string;
  valueUsd?: number;
  gasUsed: string;
  gasPrice: string;
  category: TransactionCategory;
  method?: string;
  tokenTransfers?: TokenTransfer[];
  nftTransfers?: NftTransfer[];
  status: TransactionStatus;
}

interface GetDefiActivityOptions {
  networks?: Network[];
  protocols?: string[];
  includeHistorical?: boolean;
}

interface GetDefiActivityResponse {
  address: string;
  positions: DefiPosition[];
  totalValueLocked: number;
  protocolBreakdown: ProtocolBreakdown[];
}

interface DefiPosition {
  protocol: string;
  network: Network;
  position: string; // liquidity provider, lender, borrower, etc.
  tokens: DefiToken[];
  valueUsd: number;
  apy?: number;
  rewards?: DefiReward[];
}

interface DefiToken {
  address: string;
  symbol: string;
  amount: string;
  valueUsd: number;
}

interface DefiReward {
  token: string;
  symbol: string;
  amount: string;
  valueUsd: number;
  claimable: boolean;
}

enum TransactionCategory {
  SEND = "send",
  RECEIVE = "receive",
  SWAP = "swap",
  MINT = "mint",
  BURN = "burn",
  DEFI = "defi",
  NFT = "nft",
  CONTRACT_INTERACTION = "contract_interaction",
}

enum TransactionStatus {
  SUCCESS = "success",
  FAILED = "failed",
  PENDING = "pending",
}

/**
 * Get portfolio performance metrics
 * @param address - Address to analyze
 * @param timeframe - Analysis timeframe
 * @returns Promise resolving to performance metrics
 */
getPortfolioPerformance(
  address: string,
  timeframe: PerformanceTimeframe
): Promise<PortfolioPerformanceResponse>;

/**
 * Get portfolio allocation breakdown
 * @param address - Address to analyze
 * @returns Promise resolving to allocation analysis
 */
getPortfolioAllocation(address: string): Promise<PortfolioAllocationResponse>;

/**
 * Get portfolio risk metrics
 * @param address - Address to analyze
 * @returns Promise resolving to risk analysis
 */
getPortfolioRisk(address: string): Promise<PortfolioRiskResponse>;

interface PortfolioPerformanceResponse {
  address: string;
  timeframe: PerformanceTimeframe;
  performance: PerformanceMetrics;
  historical: PerformancePoint[];
}

interface PerformanceMetrics {
  totalReturn: number;
  totalReturnPercentage: number;
  annualizedReturn: number;
  sharpeRatio: number;
  maxDrawdown: number;
  volatility: number;
  bestDay: number;
  worstDay: number;
}

interface PerformancePoint {
  timestamp: number;
  value: number;
  return: number;
  returnPercentage: number;
}

interface PortfolioAllocationResponse {
  address: string;
  allocation: AllocationBreakdown;
  diversification: DiversificationMetrics;
}

interface AllocationBreakdown {
  byAssetType: AssetTypeAllocation[];
  byNetwork: NetworkAllocation[];
  byProtocol: ProtocolAllocation[];
  topHoldings: TopHolding[];
}

interface AssetTypeAllocation {
  type: AssetType;
  valueUsd: number;
  percentage: number;
  count: number;
}

interface NetworkAllocation {
  network: Network;
  valueUsd: number;
  percentage: number;
  assetCount: number;
}

interface ProtocolAllocation {
  protocol: string;
  valueUsd: number;
  percentage: number;
  positions: number;
}

interface TopHolding {
  symbol: string;
  valueUsd: number;
  percentage: number;
  network: Network;
}

interface PortfolioRiskResponse {
  address: string;
  riskScore: number; // 0-100
  riskLevel: RiskLevel;
  factors: RiskFactor[];
  recommendations: string[];
}

interface RiskFactor {
  factor: string;
  score: number;
  impact: RiskImpact;
  description: string;
}

enum PerformanceTimeframe {
  DAY = "1d",
  WEEK = "7d", 
  MONTH = "30d",
  QUARTER = "90d",
  YEAR = "365d",
  ALL = "all",
}

enum AssetType {
  TOKENS = "tokens",
  NFTS = "nfts",
  DEFI_POSITIONS = "defi_positions",
  STAKING = "staking",
}

enum RiskLevel {
  LOW = "low",
  MEDIUM = "medium",
  HIGH = "high",
  VERY_HIGH = "very_high",
}

enum RiskImpact {
  LOW = "low",
  MEDIUM = "medium",
  HIGH = "high",
}

/**
 * Get cross-chain opportunities for an address
 * @param address - Address to analyze
 * @returns Promise resolving to cross-chain opportunities
 */
getCrossChainOpportunities(address: string): Promise<CrossChainOpportunitiesResponse>;

/**
 * Estimate cross-chain transfer costs
 * @param params - Transfer parameters
 * @returns Promise resolving to cost estimates
 */
estimateCrossChainTransfer(
  params: CrossChainTransferParams
): Promise<CrossChainTransferEstimate>;

interface CrossChainOpportunitiesResponse {
  address: string;
  opportunities: CrossChainOpportunity[];
  savings: SavingsOpportunity[];
}

interface CrossChainOpportunity {
  type: OpportunityType;
  fromNetwork: Network;
  toNetwork: Network;
  token: string;
  potentialSavings: number;
  estimatedCost: number;
  description: string;
}

interface SavingsOpportunity {
  type: SavingsType;
  network: Network;
  protocol: string;
  potentialSavings: number;
  description: string;
}

interface CrossChainTransferParams {
  fromNetwork: Network;
  toNetwork: Network;
  token: string;
  amount: string;
}

interface CrossChainTransferEstimate {
  estimatedCost: number;
  estimatedTime: number; // seconds
  route: TransferRoute[];
  risks: string[];
}

interface TransferRoute {
  step: number;
  action: string;
  network: Network;
  protocol?: string;
  estimatedCost: number;
}

enum OpportunityType {
  ARBITRAGE = "arbitrage",
  YIELD_FARMING = "yield_farming",
  LIQUIDITY_PROVISION = "liquidity_provision",
  STAKING = "staking",
}

enum SavingsType {
  GAS_OPTIMIZATION = "gas_optimization",
  BETTER_YIELDS = "better_yields",
  LOWER_FEES = "lower_fees",
}

import { Alchemy, Network, PerformanceTimeframe } from "alchemy-sdk";

const alchemy = new Alchemy({
  apiKey: "your-api-key",
  network: Network.ETH_MAINNET,
});

// Get comprehensive token balances across chains
const portfolio = await alchemy.portfolio.getTokenBalances("0x...", {
  networks: [Network.ETH_MAINNET, Network.MATIC_MAINNET, Network.ARB_MAINNET],
  includeMetadata: true,
  includeNativeBalance: true,
  excludeSpam: true,
});

console.log("Total portfolio value:", portfolio.totalValueUsd);
console.log("Token holdings:", portfolio.balances);

// Get detailed token information
const tokens = await alchemy.portfolio.getTokensForOwner("0x...", {
  networks: [Network.ETH_MAINNET, Network.MATIC_MAINNET],
  includeNfts: true,
  pageSize: 50,
});

// Get transaction history
const transactions = await alchemy.portfolio.getTransactions({
  address: "0x...",
  networks: [Network.ETH_MAINNET],
  category: [TransactionCategory.SWAP, TransactionCategory.DEFI],
  includeTokenTransfers: true,
  pageSize: 100,
});

// Get DeFi positions
const defiActivity = await alchemy.portfolio.getDefiActivity("0x...", {
  networks: [Network.ETH_MAINNET, Network.MATIC_MAINNET],
  protocols: ["uniswap", "aave", "compound"],
  includeHistorical: true,
});

console.log("Total value locked:", defiActivity.totalValueLocked);
console.log("Active positions:", defiActivity.positions);

// Get portfolio performance
const performance = await alchemy.portfolio.getPortfolioPerformance(
  "0x...",
  PerformanceTimeframe.MONTH
);

console.log("30-day return:", performance.performance.totalReturnPercentage);
console.log("Sharpe ratio:", performance.performance.sharpeRatio);

// Get portfolio allocation breakdown
const allocation = await alchemy.portfolio.getPortfolioAllocation("0x...");
console.log("By asset type:", allocation.allocation.byAssetType);
console.log("By network:", allocation.allocation.byNetwork);
console.log("Top holdings:", allocation.allocation.topHoldings);

// Get portfolio risk analysis
const risk = await alchemy.portfolio.getPortfolioRisk("0x...");
console.log("Risk score:", risk.riskScore);
console.log("Risk level:", risk.riskLevel);
console.log("Recommendations:", risk.recommendations);

// Find cross-chain opportunities
const opportunities = await alchemy.portfolio.getCrossChainOpportunities("0x...");
console.log("Arbitrage opportunities:", opportunities.opportunities);
console.log("Potential savings:", opportunities.savings);