@autonomaai/mcp-client 1.0.0

package/src/types.ts

@@ -0,0 +1,972 @@
+/**
+ * Unified MCP Client Types for autonoma Trading System
+ * 
+ * This file contains all the type definitions for the MCP client library,
+ * extracted and consolidated from the original implementation.
+ */
+
+// =============================================================================
+// Common Types
+// =============================================================================
+
+export interface ErrorResponse {
+  error: string;
+  detail?: string;
+}
+
+export interface ConfigurationObject {
+  [key: string]: string | number | boolean | ConfigurationObject;
+}
+
+export interface PositionData {
+  symbol: string;
+  size: number;
+  side: 'long' | 'short';
+  entry_price: number;
+  unrealized_pnl: number;
+  [key: string]: string | number;
+}
+
+// =============================================================================
+// Health and Context Types
+// =============================================================================
+
+export interface HummingbotHealthResponse {
+  status: string;
+  version: string;
+  system: string;
+  services: {
+    mcp_server: string;
+    backend_api: string;
+    command_delivery: string;
+    controller_architecture: string;
+    configuration_management: string;
+    live_trading: string;
+    hyperliquid_integration: string;
+  };
+  capabilities: {
+    ai_agent_interface: boolean;
+    real_exchange_connectivity: boolean;
+    controller_based_pools: boolean;
+    database_driven_config: boolean;
+    hot_reload: boolean;
+    live_hyperliquid_trading: boolean;
+    multi_strategy_support: boolean;
+    batch_operations: boolean;
+    real_time_analytics: boolean;
+  };
+  ai_features: {
+    automated_trading: boolean;
+    performance_analytics: boolean;
+    risk_assessment: boolean;
+    optimization_suggestions: boolean;
+    market_intelligence: boolean;
+    predictive_insights: boolean;
+  };
+  trading_capabilities: {
+    supported_exchanges: string[];
+    supported_strategies: string[];
+    live_execution: boolean;
+    real_time_data: boolean;
+    position_management: boolean;
+    risk_controls: boolean;
+  };
+  architecture: {
+    type: string;
+    deployment_model: string;
+    ai_interface: string;
+    backend_integration: string;
+    scalability: string;
+  };
+  timestamp: string;
+}
+
+export interface StrategyInfo {
+  name: string;
+  description: string;
+  parameters: Record<string, string>;
+  supported_exchanges: string[];
+  risk_management: Record<string, string>;
+  performance_features: string[];
+}
+
+export interface ExchangeProfile {
+  name: string;
+  type: string;
+  mode: string;
+  supported_pairs: string[];
+  features: string[];
+  trading_fees: {
+    maker: number;
+    taker: number;
+  };
+  api_rate_limits: Record<string, number>;
+  connection_method: string;
+}
+
+export interface PerformanceCapabilities {
+  max_concurrent_strategies: number;
+  supported_order_types: string[];
+  max_positions: number;
+  risk_management_features: string[];
+  performance_metrics: string[];
+  [key: string]: string | number | string[];
+}
+
+export interface OperationalFeatures {
+  hot_reload: boolean;
+  real_time_monitoring: boolean;
+  automated_risk_management: boolean;
+  multi_exchange_support: boolean;
+  strategy_optimization: boolean;
+  [key: string]: boolean | string | number;
+}
+
+export interface HummingbotContext {
+  name: string;
+  version: string;
+  description: string;
+  endpoints: string[];
+  strategies_supported: StrategyInfo[];
+  exchange_profiles: ExchangeProfile[];
+  features: string[];
+  status: string;
+  uptime: number;
+  timestamp: string;
+  system_architecture: Record<string, string>;
+  performance_capabilities: PerformanceCapabilities;
+  operational_features: OperationalFeatures;
+}
+
+// =============================================================================
+// Controller Types
+// =============================================================================
+
+export interface CreateControllerRequest {
+  name: string;
+  strategy: string;
+  trading_pair: string;
+  config: ConfigurationObject;
+}
+
+export interface ControllerResponse {
+  id: string;
+  name: string;
+  strategy: string;
+  trading_pair: string;
+  status: string;
+  config: ConfigurationObject;
+  created_at: string;
+  updated_at: string;
+  pool_id?: string;
+}
+
+export interface ControllerMetrics {
+  id: string;
+  performance: {
+    total_pnl: number;
+    win_rate: number;
+    total_trades: number;
+    current_positions: Record<string, PositionData>;
+  };
+  status: {
+    is_running: boolean;
+    last_update: string;
+    health_score: number;
+  };
+  trading_stats: {
+    volume_24h: number;
+    fees_paid: number;
+    active_orders: number;
+  };
+}
+
+// =============================================================================
+// Trading Types
+// =============================================================================
+
+export interface ExchangeListResponse {
+  supported_exchanges: string[];
+  count: number;
+  ai_capabilities?: {
+    live_trading: boolean;
+    real_time_data: boolean;
+    multi_strategy: boolean;
+    automated_execution: boolean;
+  };
+  hyperliquid_features?: {
+    perpetual_trading: boolean;
+    spot_trading: boolean;
+    low_fees: boolean;
+    fast_execution: boolean;
+    vault_integration: boolean;
+  };
+}
+
+export interface ConnectExchangeRequest {
+  exchange: string;
+  trading_pair: string;
+  credentials: {
+    wallet_address?: string;
+    private_key?: string;
+    api_key?: string;
+    api_secret?: string;
+  };
+}
+
+export interface TradingConnectionResponse {
+  controller_id: string;
+  exchange: string;
+  trading_pair: string;
+  status: string;
+  connected_at: string;
+  account_balance?: Record<string, number>;
+}
+
+export interface MarketDataResponse {
+  symbol: string;
+  price: number;
+  bid: number;
+  ask: number;
+  volume_24h: number;
+  change_24h: number;
+  timestamp: string;
+  exchange: string;
+}
+
+export interface ExecuteSignalRequest {
+  controller_id: string;
+  signal: {
+    type: string;
+    side: string;
+    amount: number;
+    price?: number;
+    order_type: string;
+  };
+}
+
+export interface SignalExecutionResponse {
+  success: boolean;
+  order_id?: string;
+  message: string;
+  timestamp: string;
+}
+
+// =============================================================================
+// Bot Types (Legacy)
+// =============================================================================
+
+export interface CreateBotRequest {
+  name: string;
+  strategy: string;
+  trading_pair: string;
+  config: ConfigurationObject;
+}
+
+export interface BotResponse {
+  id: string;
+  name: string;
+  strategy: string;
+  trading_pair: string;
+  status: string;
+  config: ConfigurationObject;
+  created_at: string;
+}
+
+// =============================================================================
+// Pool Types
+// =============================================================================
+
+export interface PoolResponse {
+  id: string;
+  name: string;
+  max_controllers: number;
+  current_controllers: number;
+  status: string;
+  created_at: string;
+}
+
+export interface CreatePoolRequest {
+  name?: string;
+  max_controllers?: number;
+}
+
+// =============================================================================
+// Hyperliquid Market Data Types (Legacy)
+// =============================================================================
+
+export interface HyperliquidOrderbook {
+  bids: Array<[string, string]>;
+  asks: Array<[string, string]>;
+  timestamp: number;
+  symbol: string;
+}
+
+export interface HyperliquidSummary {
+  symbol: string;
+  price: number;
+  volume_24h: number;
+  change_24h: number;
+  high_24h: number;
+  low_24h: number;
+  timestamp: number;
+}
+
+// =============================================================================
+// MCP Tools Types (Standardized Interface)
+// =============================================================================
+
+export interface MCPRequest {
+  jsonrpc: string;
+  id: string | number;
+  method: string;
+  params?: any;
+}
+
+export interface MCPResponse {
+  jsonrpc: string;
+  id: string | number;
+  result?: any;
+  error?: {
+    code: number;
+    message: string;
+    data?: any;
+  };
+}
+
+export interface MCPTool {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema?: {
+    type: string;
+    properties: any;
+    required?: string[];
+  };
+}
+
+export interface MCPToolsListResponse {
+  tools: MCPTool[];
+}
+
+export interface MCPToolCallRequest {
+  name: string;
+  arguments?: Record<string, any>;
+}
+
+export interface MCPToolCallResponse {
+  content: Array<{
+    type: string;
+    text: string;
+  }>;
+  meta?: any;
+  isError?: boolean;
+}
+
+// =============================================================================
+// Dexscreener MCP Types
+// =============================================================================
+
+export interface DexscreenerTokenData {
+  name: string;
+  symbol: string;
+  priceUsd: number;
+  liquidityUsd: number;
+  volumeH1: number;
+  priceChangeH1: number;
+  pairAddress: string;
+  pairUrl: string;
+}
+
+export interface DexscreenerMarketAnalysis {
+  tokens: DexscreenerTokenData[];
+  marketSummary: {
+    totalLiquidity: number;
+    totalVolume: number;
+    avgPriceChange: number;
+    peakLiquidity: number;
+    peakVolume: number;
+    peakChange: number;
+  };
+  riskAssessment: {
+    moonshots: number;
+    stableGainers: number;
+    highVolume: number;
+    qualityTokens: number;
+  };
+}
+
+// =============================================================================
+// Data Collector MCP Types
+// =============================================================================
+
+export interface TokenPriceData {
+  token: string;
+  chain: string;
+  price?: number;
+  bid?: number;
+  ask?: number;
+  volume_24h?: number;
+  change_24h?: number;
+  timestamp?: string;
+}
+
+export interface TokenVolumeData {
+  token: string;
+  chain: string;
+  interval: string;
+  volume?: number;
+  tokenFormat?: string;
+  source?: string;
+}
+
+export interface OrderbookData {
+  base: string;
+  quote: string;
+  chain: string;
+  midPrice?: number;
+  spread?: number;
+  bids?: Array<{ price: number; size: number }>;
+  asks?: Array<{ price: number; size: number }>;
+}
+
+export interface EnhancedOHLCVData {
+  token: string;
+  chain: string;
+  interval: string;
+  candles: Array<{
+    timestamp: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+  }>;
+  source?: string;
+  meta?: {
+    construction_method?: string;
+    tick_data_points?: number;
+    total_candles?: number;
+  };
+}
+
+export interface TokenDiscoveryData {
+  chain: string;
+  type: string;
+  tokens: Array<{
+    symbol: string;
+    name?: string;
+    volume?: number;
+    marketCap?: number;
+  }>;
+  sortBy: string;
+  sortOrder: string;
+}
+
+export interface TradingIntensityData {
+  token: string;
+  chain: string;
+  interval: string;
+  tokenFormat: string;
+  metrics: {
+    tradesPerMinute?: number;
+    volumePerMinute?: number;
+    activityScore?: number;
+  };
+  marketState?: string;
+}
+
+export interface SymbolResolutionData {
+  symbol: string;
+  chain: string;
+  resolved: boolean;
+  metadata?: {
+    symbol?: string;
+    type?: string;
+    pair?: string;
+    assetId?: number;
+    verified?: boolean;
+  };
+}
+
+export interface PerformanceMetricsData {
+  chain: string;
+  endpoint: string;
+  metrics: Array<{
+    endpoint: string;
+    average_ms?: number;
+    latency_ms?: number;
+    status?: string;
+  }>;
+}
+
+// =============================================================================
+// Client Configuration Types
+// =============================================================================
+
+export interface MCPClientConfig {
+  baseUrl: string;
+  timeout?: number;
+  retries?: number;
+  retryDelay?: number;
+  enableLogging?: boolean;
+  apiKey?: string;
+  headers?: Record<string, string>;
+}
+
+export interface MCPClientOptions {
+  timeout?: number;
+  retries?: number;
+  retryDelay?: number;
+  headers?: Record<string, string>;
+}
+
+// =============================================================================
+// WebSocket Types (for future real-time features)
+// =============================================================================
+
+export interface WebSocketMessage {
+  type: string;
+  data: any;
+  timestamp: string;
+}
+
+export interface WebSocketConfig {
+  url: string;
+  reconnect?: boolean;
+  reconnectDelay?: number;
+  maxReconnectAttempts?: number;
+} 
+
+// =============================================================================
+// APY Strategy MCP Types (DeFi Yield Optimization)
+// =============================================================================
+
+export interface YieldOpportunity {
+  protocol: string;
+  pool: string;
+  apy: number;
+  tvl: number;
+  risk_score: number;
+  chain: string;
+  asset: string;
+  lockup_period?: number;
+  minimum_deposit?: number;
+  confidence_score: number;
+  last_updated: string;
+}
+
+export interface YieldSearchParams {
+  asset?: string;
+  chain?: string[];
+  min_apy?: number;
+  max_risk?: number;
+  min_tvl?: number;
+  protocols?: string[];
+  limit?: number;
+}
+
+export interface AllocationOptimization {
+  strategy: 'max_sharpe' | 'risk_parity' | 'mean_variance';
+  allocations: Record<string, number>;
+  expected_return: number;
+  expected_risk: number;
+  sharpe_ratio: number;
+  constraints: AllocationConstraints;
+  rebalancing_threshold: number;
+}
+
+export interface AllocationConstraints {
+  max_protocol_allocation: number;
+  max_single_asset: number;
+  min_liquidity: number;
+  max_risk_score: number;
+  required_chains?: string[];
+}
+
+export interface ArbitrageOpportunity {
+  protocol_a: string;
+  protocol_b: string;
+  asset: string;
+  apy_difference: number;
+  potential_profit: number;
+  execution_cost: number;
+  net_profit: number;
+  risk_assessment: string;
+  time_sensitivity: 'low' | 'medium' | 'high';
+}
+
+export interface BacktestResult {
+  strategy_name: string;
+  period: string;
+  total_return: number;
+  annualized_return: number;
+  volatility: number;
+  sharpe_ratio: number;
+  max_drawdown: number;
+  win_rate: number;
+  trade_count: number;
+  transaction_costs: number;
+}
+
+export interface PortfolioRiskAssessment {
+  var_95: number;
+  var_99: number;
+  expected_shortfall: number;
+  portfolio_volatility: number;
+  correlation_risk: number;
+  concentration_risk: number;
+  liquidity_risk: number;
+  overall_risk_score: number;
+  recommendations: string[];
+}
+
+export interface ProtocolRiskAssessment {
+  protocol: string;
+  overall_risk_score: number;
+  smart_contract_risk: number;
+  liquidity_risk: number;
+  governance_risk: number;
+  audit_score: number;
+  tvl_stability: number;
+  track_record: number;
+  risk_factors: string[];
+  recommendation: 'low_risk' | 'medium_risk' | 'high_risk' | 'avoid';
+}
+
+export interface RiskMetrics {
+  score: number; // 0-100 (0 = highest risk, 100 = lowest risk)
+  category: 'low' | 'medium' | 'high' | 'extreme';
+  factors: RiskFactor[];
+  var95: number; // Value at Risk (95% confidence)
+  var99: number; // Value at Risk (99% confidence)
+  sharpeRatio?: number;
+  maxDrawdown?: number;
+  volatility: number;
+}
+
+export interface RiskFactor {
+  type: 'smart_contract' | 'liquidity' | 'impermanent_loss' | 'protocol' | 'market' | 'regulatory';
+  severity: 'low' | 'medium' | 'high' | 'extreme';
+  impact: number; // 0-100
+  description: string;
+  mitigationSuggestion?: string;
+}
+
+export interface PerformanceAlert {
+  type: 'warning' | 'error' | 'info';
+  severity: 'low' | 'medium' | 'high';
+  message: string;
+  timestamp: string;
+  protocol?: string;
+  action_required?: boolean;
+}
+
+export interface PerformanceTracking {
+  portfolio_value: number;
+  total_yield_earned: number;
+  yield_rate: number;
+  position_breakdown: PositionData[];
+  attribution_analysis: AttributionData;
+  risk_metrics: RiskMetrics;
+  alerts: PerformanceAlert[];
+}
+
+export interface PositionData {
+  protocol: string;
+  pool: string;
+  amount_deposited: number;
+  current_value: number;
+  yield_earned: number;
+  apy: number;
+  risk_score: number;
+  allocation_percentage: number;
+}
+
+export interface AttributionData {
+  protocol_contribution: Record<string, number>;
+  asset_contribution: Record<string, number>;
+  chain_contribution: Record<string, number>;
+  strategy_alpha: number;
+}
+
+export interface APYHistoryData {
+  protocol: string;
+  pool: string;
+  historical_data: APYDataPoint[];
+  statistics: APYStatistics;
+  trend_analysis: TrendAnalysis;
+  volatility_metrics: VolatilityMetrics;
+}
+
+export interface APYDataPoint {
+  timestamp: string;
+  apy: number;
+  tvl: number;
+  volume_24h: number;
+  utilization_rate: number;
+}
+
+export interface APYStatistics {
+  mean_apy: number;
+  median_apy: number;
+  std_deviation: number;
+  min_apy: number;
+  max_apy: number;
+  percentile_25: number;
+  percentile_75: number;
+}
+
+export interface TrendAnalysis {
+  trend_direction: 'up' | 'down' | 'stable';
+  trend_strength: number;
+  momentum: number;
+  seasonality: Record<string, number>;
+}
+
+export interface VolatilityMetrics {
+  apy_volatility: number;
+  tvl_volatility: number;
+  stability_score: number;
+  risk_adjusted_return: number;
+}
+
+// =============================================================================
+// APY Strategy Tool Parameters
+// =============================================================================
+
+export interface FindYieldOpportunitiesParams {
+  search_criteria: YieldSearchParams;
+  risk_tolerance: 'conservative' | 'moderate' | 'aggressive';
+  time_horizon: 'short' | 'medium' | 'long';
+}
+
+export interface OptimizeAllocationParams {
+  current_portfolio: PositionData[];
+  available_capital: number;
+  optimization_strategy: 'max_sharpe' | 'risk_parity' | 'mean_variance';
+  constraints: AllocationConstraints;
+  rebalancing_frequency: 'daily' | 'weekly' | 'monthly';
+}
+
+export interface AnalyzeArbitrageParams {
+  asset: string;
+  chains: string[];
+  protocols: string[];
+  min_profit_threshold: number;
+  max_execution_cost: number;
+}
+
+export interface BacktestStrategyParams {
+  strategy_config: {
+    name: string;
+    allocation_method: string;
+    rebalancing_frequency: string;
+    risk_limits: Record<string, number>;
+  };
+  start_date: string;
+  end_date: string;
+  initial_capital: number;
+  include_costs: boolean;
+}
+
+export interface CalculateRiskParams {
+  portfolio: PositionData[];
+  time_horizon: number;
+  confidence_level: number;
+  correlation_window: number;
+}
+
+export interface AssessProtocolRiskParams {
+  protocol: string;
+  include_governance: boolean;
+  include_smart_contract: boolean;
+  include_market: boolean;
+}
+
+export interface TrackPerformanceParams {
+  portfolio_id?: string;
+  time_range: '24h' | '7d' | '30d' | '90d' | '1y';
+  include_attribution: boolean;
+  benchmark?: string;
+}
+
+export interface GetAPYHistoryParams {
+  protocol: string;
+  pool?: string;
+  asset?: string;
+  time_range: '7d' | '30d' | '90d' | '180d' | '1y';
+  granularity: 'hourly' | 'daily' | 'weekly';
+} 
+
+// =============================================================================
+// APY Strategy MCP Tools Types
+// =============================================================================
+
+export interface GetApyHistoryRequest {
+  protocol: string;
+  chain: string;
+  pool?: string;
+  timeframe?: '7d' | '30d' | '90d' | '180d' | '1y';
+  includeRiskMetrics?: boolean;
+  includeStatistics?: boolean;
+  minTvl?: number;
+  maxRiskScore?: number;
+}
+
+export interface FindYieldOpportunitiesRequest {
+  chains?: string[];
+  minApy?: number;
+  maxRisk?: number;
+  minTvl?: number;
+  protocols?: string[];
+  assets?: string[];
+  includeArbitrage?: boolean;
+  riskTolerance?: 'conservative' | 'moderate' | 'aggressive';
+  sortBy?: 'apy' | 'risk_adjusted_return' | 'tvl' | 'risk_score';
+}
+
+export interface AnalyzeArbitrageOpportunitiesRequest {
+  sourceChain: string;
+  targetChain: string;
+  token: string;
+  amount?: number;
+  includeGasCosts?: boolean;
+  slippageTolerance?: number;
+  bridgeProtocols?: string[];
+}
+
+export interface BacktestStrategyRequest {
+  strategy: 'yield_farming' | 'arbitrage' | 'optimization' | 'balanced';
+  protocols?: string[];
+  chains?: string[];
+  startDate: string;
+  endDate: string;
+  initialAmount: number;
+  rebalanceFrequency?: 'daily' | 'weekly' | 'monthly' | 'quarterly';
+  riskTolerance?: 'conservative' | 'moderate' | 'aggressive';
+  includeTransactionCosts?: boolean;
+  optimizationMethod?: 'max_sharpe' | 'risk_parity' | 'mean_variance';
+}
+
+export interface CalculatePortfolioRiskRequest {
+  positions: Array<{
+    protocol: string;
+    chain?: string;
+    asset: string;
+    amount: number;
+    currentApy?: number;
+  }>;
+  riskMetrics?: ('var' | 'correlation' | 'concentration' | 'stress_test')[];
+  confidenceLevel?: 90 | 95 | 99;
+  timeHorizon?: number;
+  stressScenarios?: string[];
+}
+
+export interface OptimizeYieldAllocationRequest {
+  amount: number;
+  riskTolerance: 'conservative' | 'moderate' | 'aggressive';
+  optimizationMethod: 'max_sharpe' | 'risk_parity' | 'mean_variance' | 'min_variance';
+  constraints?: {
+    maxProtocolAllocation?: number;
+    maxChainAllocation?: number;
+    maxRiskScore?: number;
+    minYield?: number;
+  };
+  includeProtocols?: string[];
+  excludeProtocols?: string[];
+  targetChains?: string[];
+  rebalanceFrequency?: 'never' | 'daily' | 'weekly' | 'monthly';
+}
+
+export interface AssessProtocolRiskRequest {
+  protocol: string;
+  chain?: string;
+  includeHistoricalEvents?: boolean;
+  riskCategories?: ('smart_contract' | 'economic' | 'governance' | 'liquidity' | 'oracle')[];
+  depth?: 'basic' | 'detailed' | 'comprehensive';
+}
+
+export interface TrackYieldPerformanceRequest {
+  portfolioId: string;
+  timeframe?: '1d' | '7d' | '30d' | '90d' | '1y' | 'all';
+  includeBenchmarks?: boolean;
+  benchmarks?: string[];
+  attributionAnalysis?: boolean;
+  includeRealTimeData?: boolean;
+  alertThresholds?: {
+    minYield?: number;
+    maxDrawdown?: number;
+    riskScoreChange?: number;
+  };
+  granularity?: 'hourly' | 'daily' | 'weekly';
+}
+
+// APY Strategy Response Types
+export interface YieldOpportunity {
+  protocol: string;
+  chain: string;
+  pool: string;
+  asset: string;
+  apy: number;
+  tvl: number;
+  riskScore: number;
+  riskAdjustedReturn: number;
+  confidence: number;
+}
+
+export interface ArbitrageOpportunity {
+  sourceChain: string;
+  targetChain: string;
+  token: string;
+  sourceApy: number;
+  targetApy: number;
+  apyDifference: number;
+  estimatedProfit: number;
+  bridgeCost: number;
+  gasCost: number;
+  netProfit: number;
+  profitability: number;
+  risk: 'low' | 'medium' | 'high';
+}
+
+export interface BacktestPerformance {
+  totalReturn: number;
+  annualizedReturn: number;
+  sharpeRatio: number;
+  sortinoRatio: number;
+  maxDrawdown: number;
+  volatility: number;
+  winRate: number;
+}
+
+export interface PortfolioRisk {
+  portfolioValue: number;
+  riskScore: number;
+  diversificationScore: number;
+  var: {
+    confidence95: number;
+    confidence99: number;
+    timeHorizon: number;
+  };
+  correlation: {
+    matrix: number[][];
+    averageCorrelation: number;
+  };
+  concentration: {
+    herfindahlIndex: number;
+    maxAllocation: number;
+    protocolExposure: Record<string, number>;
+  };
+}
+
+export interface OptimizedAllocation {
+  protocol: string;
+  chain: string;
+  asset: string;
+  allocation: number;
+  amount: number;
+  expectedApy: number;
+  riskScore: number;
+  weight: number;
+}