skayn-trading-sdk/src/interfaces/IPriceProvider.js

Professional Bitcoin trading strategy backtesting framework with institutional-grade architecture

/**
 * Real-time Price Provider Interface
 * 
 * Implement this interface to add any price data source (Velo, Coinbase, Binance, etc.)
 * The framework handles caching, rate limiting, and failover automatically.
 */
class IPriceProvider {
  /**
   * Provider metadata - helps with debugging and provider selection
   */
  getMetadata() {
    return {
      name: 'Unknown Provider',
      version: '1.0.0',
      author: 'Unknown',
      description: 'Price data provider',
      supportedPairs: ['BTC-USD'],
      rateLimit: {
        requestsPerMinute: 60,
        requestsPerHour: 1000
      },
      features: {
        realtime: false,
        historical: false,
        orderbook: false,
        trades: false
      }
    };
  }

  /**
   * Get current spot price for a trading pair
   * @param {string} pair - Trading pair (e.g., 'BTC-USD', 'ETH-USD')
   * @returns {Promise<Object>} Price data object
   * @returns {number} return.price - Current price
   * @returns {number} return.timestamp - Unix timestamp
   * @returns {number} return.volume24h - Optional: 24h volume
   * @returns {number} return.change24h - Optional: 24h change percentage
   */
  async getSpotPrice(pair = 'BTC-USD') {
    throw new Error('IPriceProvider.getSpotPrice() must be implemented');
  }

  /**
   * Get multiple prices in one call (more efficient)
   * @param {Array<string>} pairs - Array of trading pairs
   * @returns {Promise<Object>} Map of pair -> price data
   */
  async getBatchPrices(pairs) {
    // Default implementation: call getSpotPrice for each
    const prices = {};
    for (const pair of pairs) {
      prices[pair] = await this.getSpotPrice(pair);
    }
    return prices;
  }

  /**
   * Subscribe to real-time price updates (optional)
   * @param {string} pair - Trading pair
   * @param {Function} callback - Called with price updates
   * @returns {Function} Unsubscribe function
   */
  subscribeToPrice(pair, callback) {
    // Default: no real-time support
    return () => {};
  }

  /**
   * Test connection and API key validity
   * @returns {Promise<Object>} Status object
   */
  async testConnection() {
    try {
      const price = await this.getSpotPrice('BTC-USD');
      return {
        connected: true,
        message: 'Connection successful',
        testPrice: price
      };
    } catch (error) {
      return {
        connected: false,
        message: error.message,
        error
      };
    }
  }

  /**
   * Get provider health status
   * @returns {Promise<Object>} Health status
   */
  async getHealth() {
    return {
      healthy: true,
      latency: 0,
      lastUpdate: Date.now(),
      errors: []
    };
  }
}

module.exports = IPriceProvider;