v3.5.0

changelog.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 2025-11-07 - 3.5.0 - feat(stocks)
+Add provider fetch limits, intraday incremental fetch, cache deduplication, and provider safety/warning improvements
+
+- Add maxRecords and defaultIntradayLimit to IProviderConfig to control maximum records per request and default intraday limits.
+- CoinGecko provider: enforce maxRecords when processing historical data, warn when large historical/intraday results are returned without explicit limits, preserve priority mappings when rebuilding the coin cache, and improve cache load logging.
+- Marketstack provider: make safety maxRecords configurable, apply a configurable default intraday limit, warn when no explicit limit is provided, and ensure effective limits are applied to returned results.
+- StockPriceService: always attempt incremental fetch for intraday requests without a date to fetch only new data since the last cached timestamp and fall back to full fetch when necessary.
+- StockPriceService: deduplicate price arrays by timestamp before caching and after merges to avoid duplicate timestamps and reduce cache bloat.
+- Introduce StockDataService for unified access to prices and fundamentals with automatic enrichment (market cap, P/E, price-to-book) and caching improvements.
+- Various cache/TTL improvements and safer default behaviors for intraday, historical and live data to improve performance and memory usage.
+
+## 2025-11-06 - 3.4.0 - feat(stocks)
+Introduce unified stock data service, new providers, improved caching and German business data tooling
+
+- Add StockDataService: unified API to fetch price + fundamentals with automatic enrichment and batch support
+- Introduce BaseProviderService abstraction and refactor provider management, caching and retry logic
+- Enhance StockPriceService: unified getData, discriminated union request types, data-type aware TTLs and smarter cache keys
+- Add Marketstack provider with intraday/EOD selection, pagination, OHLCV and exchange filtering
+- Add CoinGecko provider with robust rate-limiting, coin ID resolution and crypto support (current, historical, intraday)
+- Add SEC EDGAR fundamentals provider: CIK lookup, company facts parsing, rate limiting and caching
+- Improve FundamentalsService: unified fetching, caching and enrichment helpers (enrichWithPrice, enrichBatchWithPrices)
+- Enhance Yahoo provider and other provider mappings for better company metadata and market state handling
+- Add German business data tooling: JsonlDataProcessor for JSONL bulk imports, HandelsRegister browser automation with download handling and parsing
+- Expose OpenData entry points: DB init, JSONL processing and Handelsregister integration; add readme/docs and usage examples
+
+## 2025-11-02 - 3.3.0 - feat(stocks/CoinGeckoProvider)
+Add CoinGecko provider for cryptocurrency prices, export and tests, and update documentation
+
+- Implemented CoinGeckoProvider with rate limiting, coin-id resolution, and support for current, batch, historical and intraday price endpoints
+- Added unit/integration tests for CoinGecko: test/test.coingecko.node+bun+deno.ts
+- Exported CoinGeckoProvider from ts/stocks/index.ts
+- Updated README and readme.hints.md with CoinGecko usage, provider notes and examples
+- Added .claude/settings.local.json with webfetch and bash permissions required for testing and CI
+
 ## 2025-11-01 - 3.2.2 - fix(handelsregister)
 Correct screenshot path handling in HandelsRegister and add local tool permissions
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fin.cx/opendata",
-  "version": "3.2.2",
+  "version": "3.5.0",
   "private": false,
   "description": "A comprehensive TypeScript library for accessing business data and real-time financial information. Features include German company data management with MongoDB integration, JSONL bulk processing, automated Handelsregister interactions, and real-time stock market data from multiple providers.",
   "main": "dist_ts/index.js",

readme.hints.md

@@ -3,7 +3,7 @@
 ## Stocks Module
 
 ### Overview
-The stocks module provides real-time stock price data through various provider implementations. Currently supports Yahoo Finance with an extensible architecture for additional providers.
+The stocks module provides real-time stock price data and cryptocurrency prices through various provider implementations. Currently supports Yahoo Finance, Marketstack, and CoinGecko with an extensible architecture for additional providers.
 
 ### Architecture
 - **Provider Pattern**: Each stock data source implements the `IStockProvider` interface
@@ -31,11 +31,55 @@ const price = await stockService.getPrice({ ticker: 'AAPL' });
 console.log(`${price.ticker}: $${price.price}`);
 ```
 
+### CoinGecko Provider Notes
+- Cryptocurrency price provider supporting 13M+ tokens
+- Three main endpoints:
+  - `/simple/price` - Current prices with market data (batch supported)
+  - `/coins/{id}/market_chart` - Historical and intraday prices with OHLCV
+  - `/coins/list` - Complete coin list for ticker-to-ID mapping
+- **Rate Limiting**:
+  - Free tier: 5-15 calls/minute (no registration)
+  - Demo plan: 30 calls/minute, 10,000/month (free with registration)
+  - Custom rate limiter tracks requests per minute
+- **Ticker Resolution**:
+  - Accepts both ticker symbols (BTC, ETH) and CoinGecko IDs (bitcoin, ethereum)
+  - Lazy-loads coin list on first ticker resolution
+  - Caches coin mappings for 24 hours
+  - IDs with hyphens (wrapped-bitcoin) assumed to be CoinGecko IDs
+- **24/7 Markets**: Crypto markets always return `marketState: 'REGULAR'`
+- **Optional API Key**: Pass key to constructor for higher rate limits
+  - Demo plan: `x-cg-demo-api-key` header
+  - Paid plans: `x-cg-pro-api-key` header
+- **Data Granularity**:
+  - Historical: Daily data for date ranges
+  - Intraday: Hourly data only (1-90 days based on `days` param)
+  - Current: Real-time prices with 24h change and volume
+
+### Usage Example (Crypto)
+```typescript
+import { StockPriceService, CoinGeckoProvider } from '@fin.cx/opendata';
+
+const stockService = new StockPriceService({ ttl: 30000 });
+const coingeckoProvider = new CoinGeckoProvider(); // or new CoinGeckoProvider('api-key')
+stockService.register(coingeckoProvider);
+
+// Using ticker symbol
+const btc = await stockService.getPrice({ ticker: 'BTC' });
+console.log(`${btc.ticker}: $${btc.price}`);
+
+// Using CoinGecko ID
+const ethereum = await stockService.getPrice({ ticker: 'ethereum' });
+
+// Batch fetch
+const cryptos = await stockService.getPrices({ tickers: ['BTC', 'ETH', 'USDT'] });
+```
+
 ### Testing
 - Tests use real API calls (be mindful of rate limits)
 - Mock invalid ticker 'INVALID_TICKER_XYZ' for error testing
 - Clear cache between tests to ensure fresh data
 - The spark endpoint may return fewer results than requested
+- CoinGecko tests may take longer due to rate limiting (wait between requests)
 
 ### Future Providers
 To add a new provider:

readme.md

@@ -87,6 +87,56 @@ const apple = await stockService.getData({ type: 'current', ticker: 'AAPL' });
 console.log(`${apple.companyFullName}: $${apple.price}`);
 ```
 
+### 🪙 Cryptocurrency Prices
+
+Get real-time crypto prices with the CoinGecko provider:
+
+```typescript
+import { StockPriceService, CoinGeckoProvider } from '@fin.cx/opendata';
+
+const stockService = new StockPriceService({ ttl: 30000 });
+
+// Optional: Pass API key for higher rate limits
+// const provider = new CoinGeckoProvider('your-api-key');
+const provider = new CoinGeckoProvider();
+
+stockService.register(provider);
+
+// Fetch single crypto price (using ticker symbol)
+const btc = await stockService.getPrice({ ticker: 'BTC' });
+console.log(`${btc.ticker}: $${btc.price.toLocaleString()}`);
+console.log(`24h Change: ${btc.changePercent.toFixed(2)}%`);
+console.log(`24h Volume: $${btc.volume?.toLocaleString()}`);
+
+// Or use CoinGecko ID directly
+const ethereum = await stockService.getPrice({ ticker: 'ethereum' });
+
+// Batch fetch multiple cryptos
+const cryptos = await stockService.getPrices({
+  tickers: ['BTC', 'ETH', 'USDT', 'BNB', 'SOL']
+});
+
+cryptos.forEach(crypto => {
+  console.log(`${crypto.ticker}: $${crypto.price.toFixed(2)} (${crypto.changePercent >= 0 ? '+' : ''}${crypto.changePercent.toFixed(2)}%)`);
+});
+
+// Historical crypto prices
+const history = await stockService.getData({
+  type: 'historical',
+  ticker: 'BTC',
+  from: new Date('2025-01-01'),
+  to: new Date('2025-01-31')
+});
+
+// Intraday crypto prices (hourly)
+const intraday = await stockService.getData({
+  type: 'intraday',
+  ticker: 'ETH',
+  interval: '1hour',
+  limit: 24 // Last 24 hours
+});
+```
+
 ### 💰 Fundamentals-Only Data (Alternative)
 
 If you only need fundamentals without prices:
@@ -149,9 +199,10 @@ const details = await openData.handelsregister.getSpecificCompany({
 
 ## Features
 
-### 📊 Stock Market Module
+### 📊 Stock & Crypto Market Module
 
-- **Real-Time Prices** - Live and EOD stock prices from Yahoo Finance and Marketstack
+- **Real-Time Prices** - Live and EOD prices from Yahoo Finance, Marketstack, and CoinGecko
+- **Cryptocurrency Support** - 13M+ crypto tokens with 24/7 market data via CoinGecko
 - **Company Names** - Automatic company name extraction (e.g., "Apple Inc (NASDAQ:AAPL)")
 - **Historical Data** - Up to 15 years of daily EOD prices with pagination
 - **OHLCV Data** - Open, High, Low, Close, Volume for technical analysis
@@ -622,6 +673,15 @@ interface IStockFundamentals {
 - ✅ Company names included
 - ⚠️ Rate limits may apply
 
+**CoinGeckoProvider**
+- ✅ Cryptocurrency prices (Bitcoin, Ethereum, 13M+ tokens)
+- ✅ Current, historical, and intraday data
+- ✅ 24/7 market data (crypto never closes)
+- ✅ OHLCV data with market cap and volume
+- ✅ Supports both ticker symbols (BTC, ETH) and CoinGecko IDs (bitcoin, ethereum)
+- ✅ 240+ networks, 1600+ exchanges
+- ℹ️ Optional API key (free tier: 30 requests/min, 10K/month)
+
 **OpenData**
 - `start()` - Initialize MongoDB connection
 - `buildInitialDb()` - Import bulk data

test/test.cache-inspection.node+bun+deno.ts

@@ -0,0 +1,395 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as opendata from '../ts/index.js';
+
+/**
+ * Test to inspect actual cache contents and verify data integrity
+ */
+
+class MockProvider implements opendata.IStockProvider {
+  name = 'MockProvider';
+  priority = 100;
+  requiresAuth = false;
+
+  public callLog: Array<{ type: string; ticker: string; timestamp: Date }> = [];
+
+  async fetchData(request: opendata.IStockDataRequest): Promise<opendata.IStockPrice | opendata.IStockPrice[]> {
+    this.callLog.push({
+      type: request.type,
+      ticker: request.type === 'batch' ? request.tickers.join(',') : (request as any).ticker,
+      timestamp: new Date()
+    });
+
+    if (request.type === 'intraday') {
+      const count = request.limit || 10;
+      const prices: opendata.IStockPrice[] = [];
+      const baseTime = request.date || new Date('2025-01-07T09:30:00.000Z');
+
+      for (let i = 0; i < count; i++) {
+        prices.push({
+          ticker: request.ticker,
+          price: 100 + i,
+          currency: 'USD',
+          timestamp: new Date(baseTime.getTime() + i * 60 * 1000),
+          fetchedAt: new Date(),
+          provider: this.name,
+          dataType: 'intraday',
+          marketState: 'REGULAR',
+          open: 100,
+          high: 101,
+          low: 99,
+          volume: 1000000,
+          change: 0,
+          changePercent: 0,
+          previousClose: 100
+        });
+      }
+
+      return prices;
+    }
+
+    // Default single price
+    return {
+      ticker: (request as any).ticker,
+      price: 150,
+      currency: 'USD',
+      timestamp: new Date(),
+      fetchedAt: new Date(),
+      provider: this.name,
+      dataType: 'eod',
+      marketState: 'CLOSED',
+      open: 149,
+      high: 151,
+      low: 148,
+      volume: 5000000,
+      change: 1,
+      changePercent: 0.67,
+      previousClose: 149
+    };
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return true;
+  }
+}
+
+let stockService: opendata.StockPriceService;
+let mockProvider: MockProvider;
+
+tap.test('Cache Inspection - Setup', async () => {
+  stockService = new opendata.StockPriceService({
+    ttl: 60000,
+    maxEntries: 100
+  });
+
+  mockProvider = new MockProvider();
+  stockService.register(mockProvider);
+
+  console.log('✓ Service and provider initialized');
+});
+
+tap.test('Cache Inspection - Verify Cache Key Generation', async () => {
+  await tap.test('should generate unique cache keys for different requests', async () => {
+    stockService.clearCache();
+    mockProvider.callLog = [];
+
+    // Fetch with different parameters
+    await stockService.getData({ type: 'intraday', ticker: 'AAPL', interval: '1min', limit: 10 });
+    await stockService.getData({ type: 'intraday', ticker: 'AAPL', interval: '1min', limit: 20 });
+    await stockService.getData({ type: 'intraday', ticker: 'AAPL', interval: '5min', limit: 10 });
+    await stockService.getData({ type: 'intraday', ticker: 'MSFT', interval: '1min', limit: 10 });
+
+    // Should have made 4 provider calls (all different cache keys)
+    expect(mockProvider.callLog.length).toEqual(4);
+
+    console.log('✓ Cache keys are unique for different parameters');
+    console.log(`  Total provider calls: ${mockProvider.callLog.length}`);
+  });
+
+  await tap.test('should reuse cache for identical requests', async () => {
+    stockService.clearCache();
+    mockProvider.callLog = [];
+
+    // Same request 3 times
+    const result1 = await stockService.getData({ type: 'intraday', ticker: 'AAPL', interval: '1min', limit: 10 });
+    const result2 = await stockService.getData({ type: 'intraday', ticker: 'AAPL', interval: '1min', limit: 10 });
+    const result3 = await stockService.getData({ type: 'intraday', ticker: 'AAPL', interval: '1min', limit: 10 });
+
+    // Should have made only 1 provider call
+    expect(mockProvider.callLog.length).toEqual(1);
+
+    // All results should be identical (same reference from cache)
+    expect((result1 as opendata.IStockPrice[]).length).toEqual((result2 as opendata.IStockPrice[]).length);
+    expect((result1 as opendata.IStockPrice[]).length).toEqual((result3 as opendata.IStockPrice[]).length);
+
+    // Verify timestamps match (exact same cached data)
+    const ts1 = (result1 as opendata.IStockPrice[])[0].timestamp.getTime();
+    const ts2 = (result2 as opendata.IStockPrice[])[0].timestamp.getTime();
+    const ts3 = (result3 as opendata.IStockPrice[])[0].timestamp.getTime();
+
+    expect(ts1).toEqual(ts2);
+    expect(ts2).toEqual(ts3);
+
+    console.log('✓ Cache reused for identical requests');
+    console.log(`  3 requests → 1 provider call`);
+  });
+});
+
+tap.test('Cache Inspection - Verify Data Structure', async () => {
+  await tap.test('should cache complete IStockPrice objects', async () => {
+    stockService.clearCache();
+
+    const result = await stockService.getData({
+      type: 'intraday',
+      ticker: 'TSLA',
+      interval: '1min',
+      limit: 5
+    });
+
+    expect(result).toBeArray();
+    const prices = result as opendata.IStockPrice[];
+
+    // Verify structure of cached data
+    for (const price of prices) {
+      expect(price).toHaveProperty('ticker');
+      expect(price).toHaveProperty('price');
+      expect(price).toHaveProperty('currency');
+      expect(price).toHaveProperty('timestamp');
+      expect(price).toHaveProperty('fetchedAt');
+      expect(price).toHaveProperty('provider');
+      expect(price).toHaveProperty('dataType');
+      expect(price).toHaveProperty('marketState');
+      expect(price).toHaveProperty('open');
+      expect(price).toHaveProperty('high');
+      expect(price).toHaveProperty('low');
+      expect(price).toHaveProperty('volume');
+
+      // Verify types
+      expect(typeof price.ticker).toEqual('string');
+      expect(typeof price.price).toEqual('number');
+      expect(price.timestamp).toBeInstanceOf(Date);
+      expect(price.fetchedAt).toBeInstanceOf(Date);
+    }
+
+    console.log('✓ Cached data has complete IStockPrice structure');
+    console.log(`  Sample: ${prices[0].ticker} @ $${prices[0].price} (${prices[0].timestamp.toISOString()})`);
+  });
+
+  await tap.test('should preserve array order in cache', async () => {
+    stockService.clearCache();
+
+    const result1 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'AAPL',
+      interval: '1min',
+      limit: 10
+    });
+
+    const result2 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'AAPL',
+      interval: '1min',
+      limit: 10
+    });
+
+    const prices1 = result1 as opendata.IStockPrice[];
+    const prices2 = result2 as opendata.IStockPrice[];
+
+    // Verify order is preserved
+    for (let i = 0; i < prices1.length; i++) {
+      expect(prices1[i].timestamp.getTime()).toEqual(prices2[i].timestamp.getTime());
+      expect(prices1[i].price).toEqual(prices2[i].price);
+    }
+
+    console.log('✓ Array order preserved in cache');
+  });
+});
+
+tap.test('Cache Inspection - Verify TTL Behavior', async () => {
+  await tap.test('should respect cache TTL for intraday data', async (testArg) => {
+    // Create service with very short TTL for testing
+    const shortTTLService = new opendata.StockPriceService({
+      ttl: 100, // 100ms
+      maxEntries: 100
+    });
+
+    const testProvider = new MockProvider();
+    shortTTLService.register(testProvider);
+
+    // First fetch
+    await shortTTLService.getData({
+      type: 'intraday',
+      ticker: 'TEST',
+      interval: '1min',
+      limit: 5
+    });
+
+    const callCount1 = testProvider.callLog.length;
+
+    // Immediate second fetch - should hit cache
+    await shortTTLService.getData({
+      type: 'intraday',
+      ticker: 'TEST',
+      interval: '1min',
+      limit: 5
+    });
+
+    const callCount2 = testProvider.callLog.length;
+    expect(callCount2).toEqual(callCount1); // No new call
+
+    // Wait for TTL to expire
+    await new Promise(resolve => setTimeout(resolve, 150));
+
+    // Third fetch - should hit provider (cache expired)
+    await shortTTLService.getData({
+      type: 'intraday',
+      ticker: 'TEST',
+      interval: '1min',
+      limit: 5
+    });
+
+    const callCount3 = testProvider.callLog.length;
+    expect(callCount3).toBeGreaterThan(callCount2); // New call made
+
+    console.log('✓ Cache TTL working correctly');
+    console.log(`  Before expiry: ${callCount2 - callCount1} new calls`);
+    console.log(`  After expiry: ${callCount3 - callCount2} new calls`);
+  });
+});
+
+tap.test('Cache Inspection - Memory Efficiency', async () => {
+  await tap.test('should store deduplicated data in cache', async () => {
+    stockService.clearCache();
+    mockProvider.callLog = [];
+
+    // Fetch data
+    const result1 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'AAPL',
+      interval: '1min',
+      limit: 100
+    });
+
+    const prices = result1 as opendata.IStockPrice[];
+
+    // Verify no duplicate timestamps in cached data
+    const timestamps = prices.map(p => p.timestamp.getTime());
+    const uniqueTimestamps = new Set(timestamps);
+
+    expect(uniqueTimestamps.size).toEqual(timestamps.length);
+
+    console.log('✓ No duplicate timestamps in cached data');
+    console.log(`  Records: ${prices.length}`);
+    console.log(`  Unique timestamps: ${uniqueTimestamps.size}`);
+  });
+
+  await tap.test('should estimate memory usage', async () => {
+    stockService.clearCache();
+
+    // Fetch various sizes
+    await stockService.getData({ type: 'intraday', ticker: 'AAPL', interval: '1min', limit: 100 });
+    await stockService.getData({ type: 'intraday', ticker: 'MSFT', interval: '1min', limit: 100 });
+    await stockService.getData({ type: 'intraday', ticker: 'GOOGL', interval: '5min', limit: 50 });
+
+    // Estimate memory (rough calculation)
+    // Each IStockPrice is approximately 300-400 bytes
+    const totalRecords = 100 + 100 + 50;
+    const estimatedBytes = totalRecords * 350; // Average 350 bytes per record
+    const estimatedKB = (estimatedBytes / 1024).toFixed(2);
+
+    console.log('✓ Cache memory estimation:');
+    console.log(`  Total records cached: ${totalRecords}`);
+    console.log(`  Estimated memory: ~${estimatedKB} KB`);
+    console.log(`  Average per record: ~350 bytes`);
+  });
+});
+
+tap.test('Cache Inspection - Edge Cases', async () => {
+  await tap.test('should handle empty results', async () => {
+    const emptyProvider = new MockProvider();
+    emptyProvider.fetchData = async () => [];
+
+    const emptyService = new opendata.StockPriceService();
+    emptyService.register(emptyProvider);
+
+    const result = await emptyService.getData({
+      type: 'intraday',
+      ticker: 'EMPTY',
+      interval: '1min'
+    });
+
+    expect(result).toBeArray();
+    expect((result as opendata.IStockPrice[]).length).toEqual(0);
+
+    // Second fetch should still hit cache (even though empty)
+    const result2 = await emptyService.getData({
+      type: 'intraday',
+      ticker: 'EMPTY',
+      interval: '1min'
+    });
+
+    expect(result2).toBeArray();
+    expect((result2 as opendata.IStockPrice[]).length).toEqual(0);
+
+    console.log('✓ Empty results cached correctly');
+  });
+
+  await tap.test('should handle single record', async () => {
+    stockService.clearCache();
+
+    const result = await stockService.getData({
+      type: 'intraday',
+      ticker: 'SINGLE',
+      interval: '1min',
+      limit: 1
+    });
+
+    expect(result).toBeArray();
+    expect((result as opendata.IStockPrice[]).length).toEqual(1);
+
+    console.log('✓ Single record cached correctly');
+  });
+});
+
+tap.test('Cache Inspection - Verify fetchedAt Timestamps', async () => {
+  await tap.test('should preserve fetchedAt in cached data', async () => {
+    stockService.clearCache();
+
+    const beforeFetch = Date.now();
+    const result = await stockService.getData({
+      type: 'intraday',
+      ticker: 'AAPL',
+      interval: '1min',
+      limit: 5
+    });
+    const afterFetch = Date.now();
+
+    const prices = result as opendata.IStockPrice[];
+
+    for (const price of prices) {
+      const fetchedTime = price.fetchedAt.getTime();
+      expect(fetchedTime).toBeGreaterThanOrEqual(beforeFetch);
+      expect(fetchedTime).toBeLessThanOrEqual(afterFetch);
+    }
+
+    // Fetch again - fetchedAt should be the same (from cache)
+    await new Promise(resolve => setTimeout(resolve, 50)); // Small delay
+
+    const result2 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'AAPL',
+      interval: '1min',
+      limit: 5
+    });
+
+    const prices2 = result2 as opendata.IStockPrice[];
+
+    // Verify fetchedAt matches (same cached data)
+    for (let i = 0; i < prices.length; i++) {
+      expect(prices2[i].fetchedAt.getTime()).toEqual(prices[i].fetchedAt.getTime());
+    }
+
+    console.log('✓ fetchedAt timestamps preserved in cache');
+  });
+});
+
+export default tap.start();

test/test.coingecko.node+bun+deno.ts

@@ -0,0 +1,261 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as opendata from '../ts/index.js';
+
+// Test data
+const testCryptos = ['BTC', 'ETH', 'USDT'];
+const testCryptoIds = ['bitcoin', 'ethereum', 'tether'];
+const invalidCrypto = 'INVALID_CRYPTO_XYZ_12345';
+
+let stockService: opendata.StockPriceService;
+let coingeckoProvider: opendata.CoinGeckoProvider;
+
+tap.test('should create StockPriceService instance', async () => {
+  stockService = new opendata.StockPriceService({
+    ttl: 30000, // 30 seconds cache
+    maxEntries: 100
+  });
+  expect(stockService).toBeInstanceOf(opendata.StockPriceService);
+});
+
+tap.test('should create CoinGeckoProvider instance without API key', async () => {
+  coingeckoProvider = new opendata.CoinGeckoProvider();
+  expect(coingeckoProvider).toBeInstanceOf(opendata.CoinGeckoProvider);
+  expect(coingeckoProvider.name).toEqual('CoinGecko');
+  expect(coingeckoProvider.requiresAuth).toEqual(false);
+  expect(coingeckoProvider.priority).toEqual(90);
+});
+
+tap.test('should register CoinGecko provider with the service', async () => {
+  stockService.register(coingeckoProvider);
+  const providers = stockService.getAllProviders();
+  expect(providers).toContainEqual(coingeckoProvider);
+  expect(stockService.getProvider('CoinGecko')).toEqual(coingeckoProvider);
+});
+
+tap.test('should check CoinGecko provider health', async () => {
+  const health = await stockService.checkProvidersHealth();
+  expect(health.get('CoinGecko')).toEqual(true);
+});
+
+tap.test('should fetch single crypto price using ticker symbol (BTC)', async () => {
+  const price = await stockService.getPrice({ ticker: 'BTC' });
+
+  expect(price).toHaveProperty('ticker');
+  expect(price).toHaveProperty('price');
+  expect(price).toHaveProperty('currency');
+  expect(price).toHaveProperty('change');
+  expect(price).toHaveProperty('changePercent');
+  expect(price).toHaveProperty('previousClose');
+  expect(price).toHaveProperty('timestamp');
+  expect(price).toHaveProperty('provider');
+  expect(price).toHaveProperty('marketState');
+
+  expect(price.ticker).toEqual('BTC');
+  expect(price.price).toBeGreaterThan(0);
+  expect(price.currency).toEqual('USD');
+  expect(price.provider).toEqual('CoinGecko');
+  expect(price.marketState).toEqual('REGULAR'); // Crypto is 24/7
+  expect(price.timestamp).toBeInstanceOf(Date);
+  expect(price.dataType).toEqual('live');
+
+  console.log(`\n📊 BTC Price: $${price.price.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`);
+  console.log(`   Change: ${price.changePercent >= 0 ? '+' : ''}${price.changePercent.toFixed(2)}%`);
+});
+
+tap.test('should fetch single crypto price using CoinGecko ID (bitcoin)', async () => {
+  // Clear cache to ensure fresh fetch
+  stockService.clearCache();
+
+  const price = await stockService.getPrice({ ticker: 'bitcoin' });
+
+  expect(price.ticker).toEqual('BITCOIN');
+  expect(price.price).toBeGreaterThan(0);
+  expect(price.provider).toEqual('CoinGecko');
+  expect(price.companyName).toInclude('Bitcoin');
+});
+
+tap.test('should fetch multiple crypto prices (batch)', async () => {
+  stockService.clearCache();
+
+  const prices = await stockService.getPrices({
+    tickers: testCryptos
+  });
+
+  expect(prices).toBeArray();
+  expect(prices.length).toEqual(testCryptos.length);
+
+  for (const price of prices) {
+    expect(testCryptos).toContain(price.ticker);
+    expect(price.price).toBeGreaterThan(0);
+    expect(price.provider).toEqual('CoinGecko');
+    expect(price.marketState).toEqual('REGULAR');
+
+    console.log(`\n💰 ${price.ticker}: $${price.price.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 8 })}`);
+    console.log(`   Change 24h: ${price.changePercent >= 0 ? '+' : ''}${price.changePercent.toFixed(2)}%`);
+    if (price.volume) {
+      console.log(`   Volume 24h: $${price.volume.toLocaleString('en-US')}`);
+    }
+  }
+});
+
+tap.test('should fetch historical crypto prices', async () => {
+  // Add delay to avoid rate limiting
+  await new Promise(resolve => setTimeout(resolve, 3000));
+
+  const to = new Date();
+  const from = new Date(to.getTime() - 7 * 24 * 60 * 60 * 1000); // 7 days ago
+
+  const prices = await stockService.getData({
+    type: 'historical',
+    ticker: 'BTC',
+    from: from,
+    to: to
+  });
+
+  expect(prices).toBeArray();
+  expect((prices as opendata.IStockPrice[]).length).toBeGreaterThan(0);
+
+  const pricesArray = prices as opendata.IStockPrice[];
+  console.log(`\n📈 Historical BTC Prices (${pricesArray.length} days):`);
+
+  // Show first few and last few
+  const toShow = Math.min(3, pricesArray.length);
+  for (let i = 0; i < toShow; i++) {
+    const price = pricesArray[i];
+    const date = price.timestamp.toISOString().split('T')[0];
+    console.log(`   ${date}: $${price.price.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`);
+  }
+
+  if (pricesArray.length > toShow * 2) {
+    console.log('   ...');
+  }
+
+  for (let i = Math.max(toShow, pricesArray.length - toShow); i < pricesArray.length; i++) {
+    const price = pricesArray[i];
+    const date = price.timestamp.toISOString().split('T')[0];
+    console.log(`   ${date}: $${price.price.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`);
+  }
+
+  // Validate first entry
+  const firstPrice = pricesArray[0];
+  expect(firstPrice.ticker).toEqual('BTC');
+  expect(firstPrice.dataType).toEqual('eod');
+  expect(firstPrice.provider).toEqual('CoinGecko');
+});
+
+tap.test('should fetch intraday crypto prices (hourly)', async () => {
+  // Add delay to avoid rate limiting
+  await new Promise(resolve => setTimeout(resolve, 3000));
+
+  const prices = await stockService.getData({
+    type: 'intraday',
+    ticker: 'ETH',
+    interval: '1hour',
+    limit: 12 // Last 12 hours
+  });
+
+  expect(prices).toBeArray();
+  expect((prices as opendata.IStockPrice[]).length).toBeGreaterThan(0);
+
+  const pricesArray = prices as opendata.IStockPrice[];
+  console.log(`\n⏰ Intraday ETH Prices (hourly, last ${pricesArray.length} hours):`);
+
+  // Show first few entries
+  const toShow = Math.min(5, pricesArray.length);
+  for (let i = 0; i < toShow; i++) {
+    const price = pricesArray[i];
+    const time = price.timestamp.toISOString().replace('T', ' ').substring(0, 16);
+    console.log(`   ${time}: $${price.price.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`);
+  }
+
+  // Validate first entry
+  const firstPrice = pricesArray[0];
+  expect(firstPrice.ticker).toEqual('ETH');
+  expect(firstPrice.dataType).toEqual('intraday');
+  expect(firstPrice.provider).toEqual('CoinGecko');
+});
+
+tap.test('should serve cached prices on subsequent requests', async () => {
+  // First request - should hit the API
+  const firstRequest = await stockService.getPrice({ ticker: 'BTC' });
+
+  // Second request - should be served from cache
+  const secondRequest = await stockService.getPrice({ ticker: 'BTC' });
+
+  expect(secondRequest.ticker).toEqual(firstRequest.ticker);
+  expect(secondRequest.price).toEqual(firstRequest.price);
+  expect(secondRequest.timestamp).toEqual(firstRequest.timestamp);
+  expect(secondRequest.fetchedAt).toEqual(firstRequest.fetchedAt);
+});
+
+tap.test('should handle invalid crypto ticker gracefully', async () => {
+  try {
+    await stockService.getPrice({ ticker: invalidCrypto });
+    throw new Error('Should have thrown an error for invalid ticker');
+  } catch (error) {
+    expect(error.message).toInclude('Failed to fetch');
+  }
+});
+
+tap.test('should support market checking', async () => {
+  expect(coingeckoProvider.supportsMarket('CRYPTO')).toEqual(true);
+  expect(coingeckoProvider.supportsMarket('BTC')).toEqual(true);
+  expect(coingeckoProvider.supportsMarket('ETH')).toEqual(true);
+  expect(coingeckoProvider.supportsMarket('NASDAQ')).toEqual(false);
+});
+
+tap.test('should support ticker validation', async () => {
+  expect(coingeckoProvider.supportsTicker('BTC')).toEqual(true);
+  expect(coingeckoProvider.supportsTicker('bitcoin')).toEqual(true);
+  expect(coingeckoProvider.supportsTicker('wrapped-bitcoin')).toEqual(true);
+  expect(coingeckoProvider.supportsTicker('BTC!')).toEqual(false);
+  expect(coingeckoProvider.supportsTicker('BTC@USD')).toEqual(false);
+});
+
+tap.test('should display provider statistics', async () => {
+  const stats = stockService.getProviderStats();
+  const coingeckoStats = stats.get('CoinGecko');
+
+  expect(coingeckoStats).toBeTruthy();
+  expect(coingeckoStats.successCount).toBeGreaterThan(0);
+
+  console.log('\n📊 CoinGecko Provider Statistics:');
+  console.log(`   Success Count: ${coingeckoStats.successCount}`);
+  console.log(`   Error Count: ${coingeckoStats.errorCount}`);
+  if (coingeckoStats.lastError) {
+    console.log(`   Last Error: ${coingeckoStats.lastError}`);
+  }
+});
+
+tap.test('should display crypto price dashboard', async () => {
+  // Add delay to avoid rate limiting
+  await new Promise(resolve => setTimeout(resolve, 3000));
+
+  stockService.clearCache();
+
+  const cryptos = ['BTC', 'ETH', 'BNB', 'SOL', 'ADA'];
+  const prices = await stockService.getPrices({ tickers: cryptos });
+
+  console.log('\n╔═══════════════════════════════════════════════════════════╗');
+  console.log('║           🌐 CRYPTOCURRENCY PRICE DASHBOARD              ║');
+  console.log('╠═══════════════════════════════════════════════════════════╣');
+
+  for (const price of prices) {
+    const priceStr = `$${price.price.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 8 })}`;
+    const changeStr = `${price.changePercent >= 0 ? '+' : ''}${price.changePercent.toFixed(2)}%`;
+    const changeIcon = price.changePercent >= 0 ? '📈' : '📉';
+
+    console.log(`║ ${price.ticker.padEnd(6)} ${changeIcon} ${priceStr.padStart(20)} │ ${changeStr.padStart(10)} ║`);
+  }
+
+  console.log('╚═══════════════════════════════════════════════════════════╝');
+  console.log(`Provider: ${prices[0].provider} | Market State: ${prices[0].marketState} (24/7)`);
+  console.log(`Fetched at: ${prices[0].fetchedAt.toISOString()}`);
+});
+
+tap.test('should clear cache', async () => {
+  stockService.clearCache();
+  // Cache is cleared, no assertions needed
+});
+
+export default tap.start();

test/test.incremental-cache.node+bun+deno.ts

@@ -0,0 +1,582 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as opendata from '../ts/index.js';
+
+/**
+ * Mock provider for testing incremental cache behavior
+ * Allows precise control over what data is returned to test cache logic
+ */
+class MockIntradayProvider implements opendata.IStockProvider {
+  name = 'MockIntraday';
+  priority = 100;
+  requiresAuth = false;
+
+  // Track fetch calls for testing
+  public fetchCallCount = 0;
+  public lastRequest: opendata.IStockDataRequest | null = null;
+
+  // Mock data to return
+  private mockData: opendata.IStockPrice[] = [];
+
+  /**
+   * Set the mock data that will be returned on next fetch
+   */
+  public setMockData(data: opendata.IStockPrice[]): void {
+    this.mockData = data;
+  }
+
+  /**
+   * Reset fetch tracking
+   */
+  public resetTracking(): void {
+    this.fetchCallCount = 0;
+    this.lastRequest = null;
+  }
+
+  async fetchData(request: opendata.IStockDataRequest): Promise<opendata.IStockPrice | opendata.IStockPrice[]> {
+    this.fetchCallCount++;
+    this.lastRequest = request;
+
+    // For intraday requests, return filtered data based on date
+    if (request.type === 'intraday') {
+      let filteredData = [...this.mockData];
+
+      // Filter by date if specified (simulate incremental fetch)
+      if (request.date) {
+        filteredData = filteredData.filter(p => p.timestamp > request.date!);
+      }
+
+      // Apply limit
+      if (request.limit) {
+        filteredData = filteredData.slice(-request.limit);
+      }
+
+      return filteredData;
+    }
+
+    // For other requests, return first item or empty array
+    if (this.mockData.length > 0) {
+      return this.mockData[0];
+    }
+
+    throw new Error('No mock data available');
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return true;
+  }
+}
+
+/**
+ * Helper to generate mock intraday prices
+ */
+function generateMockIntradayPrices(
+  ticker: string,
+  count: number,
+  startTime: Date,
+  intervalMinutes: number = 1
+): opendata.IStockPrice[] {
+  const prices: opendata.IStockPrice[] = [];
+  let basePrice = 100;
+
+  for (let i = 0; i < count; i++) {
+    const timestamp = new Date(startTime.getTime() + i * intervalMinutes * 60 * 1000);
+    basePrice += (Math.random() - 0.5) * 2; // Random walk
+
+    prices.push({
+      ticker,
+      price: basePrice,
+      currency: 'USD',
+      timestamp,
+      fetchedAt: new Date(),
+      provider: 'MockIntraday',
+      dataType: 'intraday',
+      marketState: 'REGULAR',
+      open: basePrice - 0.5,
+      high: basePrice + 1,
+      low: basePrice - 1,
+      volume: 1000000,
+      change: 0,
+      changePercent: 0,
+      previousClose: basePrice
+    });
+  }
+
+  return prices;
+}
+
+let stockService: opendata.StockPriceService;
+let mockProvider: MockIntradayProvider;
+
+tap.test('Incremental Cache Setup', async () => {
+  await tap.test('should create StockPriceService and MockProvider', async () => {
+    stockService = new opendata.StockPriceService({
+      ttl: 60000, // 1 minute default (will be overridden by smart TTL)
+      maxEntries: 1000
+    });
+    expect(stockService).toBeInstanceOf(opendata.StockPriceService);
+
+    mockProvider = new MockIntradayProvider();
+    stockService.register(mockProvider);
+
+    const providers = stockService.getEnabledProviders();
+    expect(providers).toContainEqual(mockProvider);
+
+    console.log('✓ Test setup complete');
+  });
+});
+
+tap.test('Incremental Cache - Basic Behavior', async () => {
+  await tap.test('should cache intraday data on first fetch', async () => {
+    stockService.clearCache();
+    mockProvider.resetTracking();
+
+    const startTime = new Date('2025-01-07T09:30:00.000Z');
+    const mockData = generateMockIntradayPrices('AAPL', 10, startTime, 1);
+    mockProvider.setMockData(mockData);
+
+    // First fetch - should hit provider
+    const result1 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'AAPL',
+      interval: '1min',
+      limit: 10
+    });
+
+    expect(result1).toBeArray();
+    expect((result1 as opendata.IStockPrice[]).length).toEqual(10);
+    expect(mockProvider.fetchCallCount).toEqual(1);
+
+    console.log('✓ First fetch cached 10 records');
+  });
+
+  await tap.test('should serve from cache on second identical request', async () => {
+    mockProvider.resetTracking();
+
+    // Second fetch - should hit cache (no provider call)
+    const result2 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'AAPL',
+      interval: '1min',
+      limit: 10
+    });
+
+    expect(result2).toBeArray();
+    expect((result2 as opendata.IStockPrice[]).length).toEqual(10);
+    expect(mockProvider.fetchCallCount).toEqual(0); // Should NOT call provider
+
+    console.log('✓ Second fetch served from cache (0 provider calls)');
+  });
+});
+
+tap.test('Incremental Cache - Incremental Fetch', async () => {
+  await tap.test('should only fetch NEW data on refresh', async () => {
+    stockService.clearCache();
+    mockProvider.resetTracking();
+
+    const startTime = new Date('2025-01-07T09:30:00.000Z');
+
+    // First fetch: 10 records from 9:30-9:39
+    const mockData1 = generateMockIntradayPrices('MSFT', 10, startTime, 1);
+    mockProvider.setMockData(mockData1);
+
+    const result1 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'MSFT',
+      interval: '1min'
+    });
+
+    expect((result1 as opendata.IStockPrice[]).length).toEqual(10);
+    expect(mockProvider.fetchCallCount).toEqual(1);
+
+    const latestTimestamp1 = (result1 as opendata.IStockPrice[])[9].timestamp;
+    console.log(`✓ First fetch: 10 records, latest timestamp: ${latestTimestamp1.toISOString()}`);
+
+    // Simulate 5 minutes passing - 5 new records available
+    mockProvider.resetTracking();
+    const mockData2 = generateMockIntradayPrices('MSFT', 15, startTime, 1); // 15 total (10 old + 5 new)
+    mockProvider.setMockData(mockData2);
+
+    // Second fetch - should detect cache and only fetch NEW data
+    const result2 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'MSFT',
+      interval: '1min'
+    });
+
+    expect((result2 as opendata.IStockPrice[]).length).toEqual(15);
+    expect(mockProvider.fetchCallCount).toEqual(1); // Should call provider
+
+    // Verify the request had a date filter (incremental fetch)
+    expect(mockProvider.lastRequest).not.toEqual(null);
+    expect(mockProvider.lastRequest!.type).toEqual('intraday');
+    expect((mockProvider.lastRequest as opendata.IStockIntradayRequest).date).not.toEqual(undefined);
+
+    const requestDate = (mockProvider.lastRequest as opendata.IStockIntradayRequest).date;
+    console.log(`✓ Incremental fetch requested data since: ${requestDate!.toISOString()}`);
+    console.log(`✓ Total records after merge: ${(result2 as opendata.IStockPrice[]).length}`);
+    console.log('✓ Only fetched NEW data (incremental fetch working)');
+  });
+
+  await tap.test('should return cached data when no new records available', async () => {
+    stockService.clearCache();
+    mockProvider.resetTracking();
+
+    const startTime = new Date('2025-01-07T09:30:00.000Z');
+    const mockData = generateMockIntradayPrices('GOOGL', 10, startTime, 1);
+    mockProvider.setMockData(mockData);
+
+    // First fetch
+    const result1 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'GOOGL',
+      interval: '1min'
+    });
+
+    expect((result1 as opendata.IStockPrice[]).length).toEqual(10);
+
+    // Second fetch - same data (no new records)
+    mockProvider.resetTracking();
+    mockProvider.setMockData(mockData); // Same data
+
+    const result2 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'GOOGL',
+      interval: '1min'
+    });
+
+    expect((result2 as opendata.IStockPrice[]).length).toEqual(10);
+    expect(mockProvider.fetchCallCount).toEqual(1); // Incremental fetch attempted
+
+    console.log('✓ No new records - returned cached data');
+  });
+});
+
+tap.test('Incremental Cache - Deduplication', async () => {
+  await tap.test('should deduplicate by timestamp in merged data', async () => {
+    stockService.clearCache();
+    mockProvider.resetTracking();
+
+    const startTime = new Date('2025-01-07T09:30:00.000Z');
+
+    // First fetch: 10 records
+    const mockData1 = generateMockIntradayPrices('TSLA', 10, startTime, 1);
+    mockProvider.setMockData(mockData1);
+
+    const result1 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'TSLA',
+      interval: '1min'
+    });
+
+    expect((result1 as opendata.IStockPrice[]).length).toEqual(10);
+
+    // Second fetch: Return overlapping data (last 5 old + 5 new)
+    // This simulates provider returning some duplicate timestamps
+    mockProvider.resetTracking();
+    const mockData2 = generateMockIntradayPrices('TSLA', 15, startTime, 1);
+    mockProvider.setMockData(mockData2);
+
+    const result2 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'TSLA',
+      interval: '1min'
+    });
+
+    // Should have 15 unique timestamps (deduplication worked)
+    expect((result2 as opendata.IStockPrice[]).length).toEqual(15);
+
+    // Verify timestamps are unique
+    const timestamps = (result2 as opendata.IStockPrice[]).map(p => p.timestamp.getTime());
+    const uniqueTimestamps = new Set(timestamps);
+    expect(uniqueTimestamps.size).toEqual(15);
+
+    console.log('✓ Deduplication working - 15 unique timestamps');
+  });
+});
+
+tap.test('Incremental Cache - Limit Handling', async () => {
+  await tap.test('should respect limit parameter in merged results', async () => {
+    stockService.clearCache();
+    mockProvider.resetTracking();
+
+    const startTime = new Date('2025-01-07T09:30:00.000Z');
+
+    // First fetch with limit 100
+    const mockData1 = generateMockIntradayPrices('AMZN', 100, startTime, 1);
+    mockProvider.setMockData(mockData1);
+
+    const result1 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'AMZN',
+      interval: '1min',
+      limit: 100
+    });
+
+    expect((result1 as opendata.IStockPrice[]).length).toEqual(100);
+
+    // Second fetch: 10 new records available
+    mockProvider.resetTracking();
+    const mockData2 = generateMockIntradayPrices('AMZN', 110, startTime, 1);
+    mockProvider.setMockData(mockData2);
+
+    const result2 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'AMZN',
+      interval: '1min',
+      limit: 100 // Same limit
+    });
+
+    // Should still return 100 (most recent 100 after merge)
+    expect((result2 as opendata.IStockPrice[]).length).toEqual(100);
+
+    // Verify we got the most RECENT 100 (should include new data)
+    const lastTimestamp = (result2 as opendata.IStockPrice[])[99].timestamp;
+    const expectedLastTimestamp = mockData2[109].timestamp;
+    expect(lastTimestamp.getTime()).toEqual(expectedLastTimestamp.getTime());
+
+    console.log('✓ Limit respected - returned most recent 100 records');
+  });
+
+  await tap.test('should handle different limits without cache collision', async () => {
+    stockService.clearCache();
+    mockProvider.resetTracking();
+
+    const startTime = new Date('2025-01-07T09:30:00.000Z');
+    const mockData = generateMockIntradayPrices('NVDA', 1000, startTime, 1);
+    mockProvider.setMockData(mockData);
+
+    // Fetch with limit 100
+    const result1 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'NVDA',
+      interval: '1min',
+      limit: 100
+    });
+    expect((result1 as opendata.IStockPrice[]).length).toEqual(100);
+
+    mockProvider.resetTracking();
+
+    // Fetch with limit 500 (should NOT use cached limit:100 data)
+    const result2 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'NVDA',
+      interval: '1min',
+      limit: 500
+    });
+    expect((result2 as opendata.IStockPrice[]).length).toEqual(500);
+
+    // Should have made a new provider call (different cache key)
+    expect(mockProvider.fetchCallCount).toBeGreaterThan(0);
+
+    console.log('✓ Different limits use different cache keys');
+  });
+});
+
+tap.test('Incremental Cache - Dashboard Polling Scenario', async () => {
+  await tap.test('should efficiently handle repeated polling requests', async () => {
+    stockService.clearCache();
+    mockProvider.resetTracking();
+
+    const startTime = new Date('2025-01-07T09:30:00.000Z');
+    let currentDataSize = 100;
+
+    // Initial fetch: 100 records
+    let mockData = generateMockIntradayPrices('AAPL', currentDataSize, startTime, 1);
+    mockProvider.setMockData(mockData);
+
+    const result1 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'AAPL',
+      interval: '1min',
+      limit: 1000
+    });
+
+    expect((result1 as opendata.IStockPrice[]).length).toEqual(100);
+    const initialFetchCount = mockProvider.fetchCallCount;
+
+    console.log(`✓ Initial fetch: ${(result1 as opendata.IStockPrice[]).length} records (${initialFetchCount} API calls)`);
+
+    // Simulate 5 dashboard refreshes (1 new record each time)
+    let totalNewRecords = 0;
+    for (let i = 0; i < 5; i++) {
+      mockProvider.resetTracking();
+      currentDataSize += 1; // 1 new record
+      totalNewRecords += 1;
+
+      mockData = generateMockIntradayPrices('AAPL', currentDataSize, startTime, 1);
+      mockProvider.setMockData(mockData);
+
+      const result = await stockService.getData({
+        type: 'intraday',
+        ticker: 'AAPL',
+        interval: '1min',
+        limit: 1000
+      });
+
+      expect((result as opendata.IStockPrice[]).length).toEqual(currentDataSize);
+      expect(mockProvider.fetchCallCount).toEqual(1); // Incremental fetch
+    }
+
+    console.log(`✓ Dashboard polling: 5 refreshes with ${totalNewRecords} new records`);
+    console.log('✓ Each refresh only fetched NEW data (incremental cache working)');
+  });
+});
+
+tap.test('Incremental Cache - Memory Impact', async () => {
+  await tap.test('should demonstrate memory savings from deduplication', async () => {
+    stockService.clearCache();
+    mockProvider.resetTracking();
+
+    const startTime = new Date('2025-01-07T09:30:00.000Z');
+
+    // Create data with intentional duplicates
+    const baseData = generateMockIntradayPrices('MSFT', 1000, startTime, 1);
+    const duplicatedData = [...baseData, ...baseData.slice(-100)]; // Duplicate last 100
+
+    expect(duplicatedData.length).toEqual(1100); // Before deduplication
+
+    mockProvider.setMockData(duplicatedData);
+
+    const result = await stockService.getData({
+      type: 'intraday',
+      ticker: 'MSFT',
+      interval: '1min'
+    });
+
+    // Should have 1000 unique records (100 duplicates removed)
+    expect((result as opendata.IStockPrice[]).length).toEqual(1000);
+
+    console.log('✓ Deduplication removed 100 duplicate timestamps');
+    console.log(`✓ Memory saved: ~${Math.round((100 / 1100) * 100)}%`);
+  });
+});
+
+tap.test('Incremental Cache - Fallback Behavior', async () => {
+  await tap.test('should not use incremental fetch for requests with date filter', async () => {
+    stockService.clearCache();
+    mockProvider.resetTracking();
+
+    const startTime = new Date('2025-01-07T09:30:00.000Z');
+    const mockData = generateMockIntradayPrices('GOOGL', 100, startTime, 1);
+    mockProvider.setMockData(mockData);
+
+    // First fetch without date
+    await stockService.getData({
+      type: 'intraday',
+      ticker: 'GOOGL',
+      interval: '1min'
+    });
+
+    mockProvider.resetTracking();
+
+    // Second fetch WITH date filter - should NOT use incremental cache
+    const result = await stockService.getData({
+      type: 'intraday',
+      ticker: 'GOOGL',
+      interval: '1min',
+      date: new Date('2025-01-07T10:00:00.000Z') // Explicit date filter
+    });
+
+    // Should have made normal fetch (not incremental)
+    expect(mockProvider.fetchCallCount).toEqual(1);
+    expect((mockProvider.lastRequest as opendata.IStockIntradayRequest).date).not.toEqual(undefined);
+
+    console.log('✓ Incremental cache skipped for requests with explicit date filter');
+  });
+});
+
+tap.test('Incremental Cache - Performance Benchmark', async () => {
+  await tap.test('should demonstrate API call reduction', async () => {
+    stockService.clearCache();
+    mockProvider.resetTracking();
+
+    const startTime = new Date('2025-01-07T09:30:00.000Z');
+
+    // Initial dataset: 1000 records
+    let mockData = generateMockIntradayPrices('BENCHMARK', 1000, startTime, 1);
+    mockProvider.setMockData(mockData);
+
+    // Initial fetch
+    await stockService.getData({
+      type: 'intraday',
+      ticker: 'BENCHMARK',
+      interval: '1min',
+      limit: 1000
+    });
+
+    expect(mockProvider.fetchCallCount).toEqual(1);
+    console.log('✓ Initial fetch: 1000 records');
+
+    let totalProviderCalls = 1;
+    let totalNewRecords = 0;
+
+    // Simulate 10 refreshes (5 new records each)
+    for (let i = 0; i < 10; i++) {
+      mockProvider.resetTracking();
+
+      // Add 5 new records
+      const newCount = 5;
+      mockData = generateMockIntradayPrices('BENCHMARK', 1000 + totalNewRecords + newCount, startTime, 1);
+      mockProvider.setMockData(mockData);
+
+      await stockService.getData({
+        type: 'intraday',
+        ticker: 'BENCHMARK',
+        interval: '1min',
+        limit: 1000
+      });
+
+      totalProviderCalls += mockProvider.fetchCallCount;
+      totalNewRecords += newCount;
+    }
+
+    console.log('\n📊 Performance Benchmark:');
+    console.log(`  Total refreshes: 10`);
+    console.log(`  New records fetched: ${totalNewRecords}`);
+    console.log(`  Total provider calls: ${totalProviderCalls}`);
+    console.log(`  Without incremental cache: ${11} calls (1 initial + 10 full refreshes)`);
+    console.log(`  With incremental cache: ${totalProviderCalls} calls (1 initial + 10 incremental)`);
+    console.log(`  Data transfer reduction: ~${Math.round((1 - (totalNewRecords / (10 * 1000))) * 100)}%`);
+    console.log('  (Only fetched NEW data instead of refetching all 1000 records each time)');
+  });
+});
+
+tap.test('Incremental Cache - Timestamp Ordering', async () => {
+  await tap.test('should maintain timestamp order after merge', async () => {
+    stockService.clearCache();
+    mockProvider.resetTracking();
+
+    const startTime = new Date('2025-01-07T09:30:00.000Z');
+
+    // First fetch
+    const mockData1 = generateMockIntradayPrices('TSLA', 10, startTime, 1);
+    mockProvider.setMockData(mockData1);
+
+    await stockService.getData({
+      type: 'intraday',
+      ticker: 'TSLA',
+      interval: '1min'
+    });
+
+    // Second fetch with new data
+    mockProvider.resetTracking();
+    const mockData2 = generateMockIntradayPrices('TSLA', 15, startTime, 1);
+    mockProvider.setMockData(mockData2);
+
+    const result = await stockService.getData({
+      type: 'intraday',
+      ticker: 'TSLA',
+      interval: '1min'
+    });
+
+    // Verify ascending timestamp order
+    const timestamps = (result as opendata.IStockPrice[]).map(p => p.timestamp.getTime());
+    for (let i = 1; i < timestamps.length; i++) {
+      expect(timestamps[i]).toBeGreaterThan(timestamps[i - 1]);
+    }
+
+    console.log('✓ Timestamps correctly ordered (ascending)');
+  });
+});
+
+export default tap.start();

test/test.stale-data-fix.node+bun+deno.ts

@@ -0,0 +1,365 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as opendata from '../ts/index.js';
+
+/**
+ * Test to verify we NEVER return stale intraday data
+ * Even when cache hasn't expired, we should check for new data
+ */
+
+class MockIntradayProvider implements opendata.IStockProvider {
+  name = 'MockIntradayProvider';
+  priority = 100;
+  requiresAuth = false;
+
+  public fetchCount = 0;
+  public lastRequestDate: Date | undefined;
+  private currentDataCount = 10; // Start with 10 records
+  private baseTime = new Date('2025-01-07T09:30:00.000Z');
+
+  async fetchData(request: opendata.IStockDataRequest): Promise<opendata.IStockPrice | opendata.IStockPrice[]> {
+    this.fetchCount++;
+
+    if (request.type === 'intraday') {
+      this.lastRequestDate = request.date;
+
+      const startTime = request.date || this.baseTime;
+      const prices: opendata.IStockPrice[] = [];
+
+      // Simulate provider returning data AFTER the requested date
+      for (let i = 0; i < this.currentDataCount; i++) {
+        const timestamp = new Date(startTime.getTime() + i * 60 * 1000);
+
+        // Only return data AFTER request date if date filter is present
+        if (request.date && timestamp <= request.date) {
+          continue;
+        }
+
+        prices.push({
+          ticker: request.ticker,
+          price: 100 + i,
+          currency: 'USD',
+          timestamp,
+          fetchedAt: new Date(),
+          provider: this.name,
+          dataType: 'intraday',
+          marketState: 'REGULAR',
+          open: 100,
+          high: 101,
+          low: 99,
+          volume: 1000000,
+          change: 0,
+          changePercent: 0,
+          previousClose: 100
+        });
+      }
+
+      return prices;
+    }
+
+    throw new Error('Only intraday supported in this mock');
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return true;
+  }
+
+  public addNewRecords(count: number): void {
+    this.currentDataCount += count;
+  }
+
+  public advanceTime(minutes: number): void {
+    this.baseTime = new Date(this.baseTime.getTime() + minutes * 60 * 1000);
+  }
+}
+
+let stockService: opendata.StockPriceService;
+let mockProvider: MockIntradayProvider;
+
+tap.test('Stale Data Fix - Setup', async () => {
+  // Use LONG TTL so cache doesn't expire during test
+  stockService = new opendata.StockPriceService({
+    ttl: 300000, // 5 minutes
+    maxEntries: 1000
+  });
+
+  mockProvider = new MockIntradayProvider();
+  stockService.register(mockProvider);
+
+  console.log('✓ Service initialized with 5-minute cache TTL');
+});
+
+tap.test('Stale Data Fix - Check for New Data Even When Cache Valid', async () => {
+  await tap.test('should return cached data if less than 1 minute old (freshness check)', async () => {
+    stockService.clearCache();
+    mockProvider.fetchCount = 0;
+    mockProvider.currentDataCount = 10;
+
+    console.log('\n📊 Scenario: Request twice within 1 minute\n');
+
+    // First request - fetch 10 records
+    console.log('⏰ First request (initial fetch)');
+    const result1 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'AAPL',
+      interval: '1min',
+      limit: 1000
+    });
+
+    expect(result1).toBeArray();
+    expect((result1 as opendata.IStockPrice[]).length).toEqual(10);
+    expect(mockProvider.fetchCount).toEqual(1);
+
+    const latestTimestamp1 = (result1 as opendata.IStockPrice[])[9].timestamp;
+    console.log(`  ✓ Fetched 10 records, latest: ${latestTimestamp1.toISOString()}`);
+
+    // Second request immediately - should return cache (data < 1min old)
+    console.log('\n⏰ Second request (< 1 minute later)');
+    mockProvider.fetchCount = 0;
+    mockProvider.addNewRecords(10); // New data available, but won't fetch yet
+
+    const result2 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'AAPL',
+      interval: '1min',
+      limit: 1000
+    });
+
+    // Should return cached data (freshness check prevents fetch)
+    expect((result2 as opendata.IStockPrice[]).length).toEqual(10);
+    expect(mockProvider.fetchCount).toEqual(0); // No provider call
+
+    console.log(`  ✓ Returned cached 10 records (no provider call)`);
+    console.log(`  ✓ Freshness check: Data < 1min old, no fetch needed`);
+  });
+
+  await tap.test('should fetch NEW data when cache is > 1 minute old', async () => {
+    stockService.clearCache();
+    mockProvider.fetchCount = 0;
+    mockProvider.currentDataCount = 10;
+
+    console.log('\n📊 Scenario: Request after 2 minutes (data > 1min old)\n');
+
+    // First request - fetch 10 records at 9:30am
+    console.log('⏰ 9:30:00 - First request (initial fetch)');
+    const result1 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'MSFT',
+      interval: '1min',
+      limit: 1000
+    });
+
+    expect(result1).toBeArray();
+    expect((result1 as opendata.IStockPrice[]).length).toEqual(10);
+    const latestTimestamp1 = (result1 as opendata.IStockPrice[])[9].timestamp;
+    console.log(`  ✓ Fetched 10 records, latest: ${latestTimestamp1.toISOString()}`);
+
+    // Advance time by 2 minutes - now data is > 1 minute old
+    console.log('\n⏰ 9:32:00 - Second request (2 minutes later, data > 1min old)');
+    console.log('  📝 Advancing provider time by 2 minutes...');
+
+    mockProvider.fetchCount = 0;
+    mockProvider.advanceTime(2); // Advance 2 minutes
+    mockProvider.addNewRecords(10); // Now provider has 20 records total
+
+    const result2 = await stockService.getData({
+      type: 'intraday',
+      ticker: 'MSFT',
+      interval: '1min',
+      limit: 1000
+    });
+
+    expect(result2).toBeArray();
+    const prices2 = result2 as opendata.IStockPrice[];
+
+    // Should have 20 records (10 cached + 10 new)
+    expect(prices2.length).toEqual(20);
+
+    // Should have made a provider call (data was stale)
+    expect(mockProvider.fetchCount).toBeGreaterThan(0);
+
+    const latestTimestamp2 = prices2[prices2.length - 1].timestamp;
+    console.log(`  ✓ Now have ${prices2.length} records, latest: ${latestTimestamp2.toISOString()}`);
+    console.log(`  ✓ Provider calls: ${mockProvider.fetchCount} (fetched new data)`);
+    console.log(`  ✓ Data was > 1min old, incremental fetch triggered!`);
+
+    // Verify we got NEW data
+    expect(latestTimestamp2.getTime()).toBeGreaterThan(latestTimestamp1.getTime());
+
+    console.log('\n✅ SUCCESS: Fetched new data when cache was stale!');
+  });
+
+  await tap.test('should handle polling with > 1 minute intervals efficiently', async () => {
+    stockService.clearCache();
+    mockProvider.fetchCount = 0;
+    mockProvider.currentDataCount = 100;
+
+    console.log('\n📊 Scenario: Dashboard polling every 2 minutes\n');
+
+    // Initial request at 9:30am
+    console.log('⏰ 9:30:00 - Request 1 (initial fetch)');
+    await stockService.getData({
+      type: 'intraday',
+      ticker: 'GOOGL',
+      interval: '1min',
+      limit: 1000
+    });
+
+    expect(mockProvider.fetchCount).toEqual(1);
+    console.log(`  ✓ Fetched 100 records (provider calls: 1)`);
+
+    let totalProviderCalls = 1;
+    let totalNewRecords = 0;
+
+    // Simulate 3 polling refreshes (2 minutes apart, 5 new records each)
+    for (let i = 2; i <= 4; i++) {
+      mockProvider.fetchCount = 0;
+      mockProvider.advanceTime(2); // Advance 2 minutes (triggers freshness check)
+      mockProvider.addNewRecords(5);
+      totalNewRecords += 5;
+
+      const minutes = (i - 1) * 2;
+      console.log(`\n⏰ 9:${30 + minutes}:00 - Request ${i} (${minutes} minutes later, +5 new records)`);
+
+      const result = await stockService.getData({
+        type: 'intraday',
+        ticker: 'GOOGL',
+        interval: '1min',
+        limit: 1000
+      });
+
+      const expectedTotal = 100 + totalNewRecords;
+      expect((result as opendata.IStockPrice[]).length).toEqual(expectedTotal);
+
+      // Should have made exactly 1 provider call (incremental fetch)
+      expect(mockProvider.fetchCount).toEqual(1);
+      totalProviderCalls++;
+
+      console.log(`  ✓ Now have ${expectedTotal} records (incremental fetch: 1 call)`);
+    }
+
+    console.log(`\n📊 Summary:`);
+    console.log(`  Total requests: 4`);
+    console.log(`  Total provider calls: ${totalProviderCalls}`);
+    console.log(`  New records fetched: ${totalNewRecords}`);
+    console.log(`  Without incremental cache: Would fetch 100 records × 3 refreshes = 300 records`);
+    console.log(`  With incremental cache: Only fetched ${totalNewRecords} new records`);
+    console.log(`  Data transfer reduction: ${Math.round((1 - (totalNewRecords / 300)) * 100)}%`);
+    console.log('\n✅ SUCCESS: Only fetched NEW data on each refresh!');
+  });
+});
+
+tap.test('Stale Data Fix - Verify No Regression for Other Request Types', async () => {
+  await tap.test('historical requests should still use simple cache', async () => {
+    stockService.clearCache();
+
+    // Mock provider that counts calls
+    let historicalCallCount = 0;
+    const historicalProvider: opendata.IStockProvider = {
+      name: 'HistoricalMock',
+      priority: 100,
+      requiresAuth: false,
+      async fetchData() {
+        historicalCallCount++;
+        return [{
+          ticker: 'TEST',
+          price: 100,
+          currency: 'USD',
+          timestamp: new Date('2025-01-01'),
+          fetchedAt: new Date(),
+          provider: 'HistoricalMock',
+          dataType: 'eod',
+          marketState: 'CLOSED',
+          open: 99,
+          high: 101,
+          low: 98,
+          volume: 1000000,
+          change: 1,
+          changePercent: 1,
+          previousClose: 99
+        }];
+      },
+      async isAvailable() { return true; }
+    };
+
+    const testService = new opendata.StockPriceService({ ttl: 60000 });
+    testService.register(historicalProvider);
+
+    // First request
+    await testService.getData({
+      type: 'historical',
+      ticker: 'TEST',
+      from: new Date('2025-01-01'),
+      to: new Date('2025-01-31')
+    });
+
+    expect(historicalCallCount).toEqual(1);
+
+    // Second request - should use cache (not incremental fetch)
+    await testService.getData({
+      type: 'historical',
+      ticker: 'TEST',
+      from: new Date('2025-01-01'),
+      to: new Date('2025-01-31')
+    });
+
+    // Should still be 1 (used cache)
+    expect(historicalCallCount).toEqual(1);
+
+    console.log('✓ Historical requests use simple cache (no incremental fetch)');
+  });
+
+  await tap.test('current price requests should still use simple cache', async () => {
+    stockService.clearCache();
+
+    let currentCallCount = 0;
+    const currentProvider: opendata.IStockProvider = {
+      name: 'CurrentMock',
+      priority: 100,
+      requiresAuth: false,
+      async fetchData() {
+        currentCallCount++;
+        return {
+          ticker: 'TEST',
+          price: 150,
+          currency: 'USD',
+          timestamp: new Date(),
+          fetchedAt: new Date(),
+          provider: 'CurrentMock',
+          dataType: 'eod',
+          marketState: 'CLOSED',
+          open: 149,
+          high: 151,
+          low: 148,
+          volume: 5000000,
+          change: 1,
+          changePercent: 0.67,
+          previousClose: 149
+        };
+      },
+      async isAvailable() { return true; }
+    };
+
+    const testService = new opendata.StockPriceService({ ttl: 60000 });
+    testService.register(currentProvider);
+
+    // First request
+    await testService.getData({
+      type: 'current',
+      ticker: 'TEST'
+    });
+
+    expect(currentCallCount).toEqual(1);
+
+    // Second request - should use cache
+    await testService.getData({
+      type: 'current',
+      ticker: 'TEST'
+    });
+
+    expect(currentCallCount).toEqual(1);
+
+    console.log('✓ Current price requests use simple cache');
+  });
+});
+
+export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '3.2.2',
+  version: '3.5.0',
   description: 'A comprehensive TypeScript library for accessing business data and real-time financial information. Features include German company data management with MongoDB integration, JSONL bulk processing, automated Handelsregister interactions, and real-time stock market data from multiple providers.'
 }

ts/stocks/classes.stockservice.ts

@@ -156,12 +156,23 @@ export class StockPriceService implements IProviderRegistry {
    */
   public async getData(request: IStockDataRequest): Promise<IStockPrice | IStockPrice[]> {
     const cacheKey = this.getDataCacheKey(request);
-    const cached = this.getFromCache(cacheKey);
 
+    // For intraday requests without date filter, ALWAYS try incremental fetch
+    // This ensures we check for new data even if cache hasn't expired
+    if (request.type === 'intraday' && !request.date) {
+      const incrementalResult = await this.tryIncrementalFetch(request, cacheKey);
+      if (incrementalResult) {
+        return incrementalResult;
+      }
+      // If incremental fetch returns null, continue to normal fetch below
+    } else {
+      // For other request types (historical, current, batch), use simple cache
+      const cached = this.getFromCache(cacheKey);
       if (cached) {
         console.log(`Cache hit for ${this.getRequestDescription(request)}`);
         return cached;
       }
+    }
 
     const providers = this.getEnabledProviders();
     if (providers.length === 0) {
@@ -204,6 +215,137 @@ export class StockPriceService implements IProviderRegistry {
     );
   }
 
+  /**
+   * Try incremental fetch: Only fetch NEW data since last cached timestamp
+   * Returns merged result if successful, null if incremental fetch not applicable
+   */
+  private async tryIncrementalFetch(
+    request: IStockDataRequest,
+    cacheKey: string
+  ): Promise<IStockPrice[] | null> {
+    // Only applicable for intraday requests without date filter
+    if (request.type !== 'intraday' || request.date) {
+      return null;
+    }
+
+    // Check if we have similar cached data (same ticker, interval, but any limit/date)
+    const baseKey = `intraday:${request.ticker}:${request.interval}:latest`;
+    let cachedData: IStockPrice[] | null = null;
+    let matchedKey: string | null = null;
+
+    // Find any cached intraday data for this ticker+interval
+    for (const [key, entry] of this.cache.entries()) {
+      if (key.startsWith(baseKey)) {
+        const age = Date.now() - entry.timestamp.getTime();
+        if (entry.ttl !== Infinity && age > entry.ttl) {
+          continue; // Expired
+        }
+        cachedData = Array.isArray(entry.price) ? entry.price as IStockPrice[] : null;
+        matchedKey = key;
+        break;
+      }
+    }
+
+    if (!cachedData || cachedData.length === 0) {
+      return null; // No cached data to build on
+    }
+
+    // Find latest timestamp in cached data
+    const latestCached = cachedData.reduce((latest, price) => {
+      return price.timestamp > latest ? price.timestamp : latest;
+    }, new Date(0));
+
+    // Freshness check: If latest data is less than 1 minute old, just return cache
+    const dataAge = Date.now() - latestCached.getTime();
+    const freshnessThreshold = 60 * 1000; // 1 minute
+
+    if (dataAge < freshnessThreshold) {
+      console.log(`🔄 Incremental cache: Latest data is ${Math.round(dataAge / 1000)}s old (< 1min), returning cached data`);
+      return cachedData;
+    }
+
+    console.log(`🔄 Incremental cache: Found ${cachedData.length} cached records, latest: ${latestCached.toISOString()} (${Math.round(dataAge / 1000)}s old)`);
+
+    // Fetch only NEW data since latest cached timestamp
+    // Create a modified request with date filter
+    const modifiedRequest: IStockIntradayRequest = {
+      ...request,
+      date: latestCached // Fetch from this date forward
+    };
+
+    const providers = this.getEnabledProviders();
+    for (const provider of providers) {
+      const entry = this.providers.get(provider.name)!;
+
+      try {
+        const newData = await this.fetchWithRetry(
+          () => provider.fetchData(modifiedRequest),
+          entry.config
+        ) as IStockPrice[];
+
+        entry.successCount++;
+
+        // Filter out data at or before latest cached timestamp (avoid duplicates)
+        const filteredNew = newData.filter(p => p.timestamp > latestCached);
+
+        if (filteredNew.length === 0) {
+          console.log(`🔄 Incremental cache: No new data since ${latestCached.toISOString()}, using cache`);
+          return cachedData;
+        }
+
+        console.log(`🔄 Incremental cache: Fetched ${filteredNew.length} new records since ${latestCached.toISOString()}`);
+
+        // Merge cached + new data
+        const merged = [...cachedData, ...filteredNew];
+
+        // Sort by timestamp (ascending)
+        merged.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+
+        // Deduplicate by timestamp (keep latest)
+        const deduped = this.deduplicateByTimestamp(merged);
+
+        // Apply limit if specified in original request
+        const effectiveLimit = request.limit || deduped.length;
+        const result = deduped.slice(-effectiveLimit); // Take most recent N
+
+        // Update cache with merged result
+        const ttl = this.getRequestTTL(request, result);
+        this.addToCache(cacheKey, result, ttl);
+
+        console.log(`🔄 Incremental cache: Returning ${result.length} total records (${cachedData.length} cached + ${filteredNew.length} new)`);
+        return result;
+
+      } catch (error) {
+        entry.errorCount++;
+        entry.lastError = error as Error;
+        entry.lastErrorTime = new Date();
+        console.warn(`Incremental fetch failed for ${provider.name}, falling back to full fetch`);
+        continue; // Try next provider or fall back to normal fetch
+      }
+    }
+
+    return null; // Incremental fetch failed, fall back to normal fetch
+  }
+
+  /**
+   * Deduplicate array of prices by timestamp, keeping the latest data for each timestamp
+   */
+  private deduplicateByTimestamp(prices: IStockPrice[]): IStockPrice[] {
+    const seen = new Map<number, IStockPrice>();
+
+    for (const price of prices) {
+      const ts = price.timestamp.getTime();
+      const existing = seen.get(ts);
+
+      // Keep the entry with the latest fetchedAt (most recent data)
+      if (!existing || price.fetchedAt > existing.fetchedAt) {
+        seen.set(ts, price);
+      }
+    }
+
+    return Array.from(seen.values());
+  }
+
   /**
    * Get TTL based on request type and result
    */
@@ -328,7 +470,8 @@ export class StockPriceService implements IProviderRegistry {
         return `historical:${request.ticker}:${fromStr}:${toStr}${request.exchange ? `:${request.exchange}` : ''}`;
       case 'intraday':
         const dateStr = request.date ? request.date.toISOString().split('T')[0] : 'latest';
-        return `intraday:${request.ticker}:${request.interval}:${dateStr}${request.exchange ? `:${request.exchange}` : ''}`;
+        const limitStr = request.limit ? `:limit${request.limit}` : '';
+        return `intraday:${request.ticker}:${request.interval}:${dateStr}${limitStr}${request.exchange ? `:${request.exchange}` : ''}`;
       case 'batch':
         const tickers = request.tickers.sort().join(',');
         return `batch:${tickers}${request.exchange ? `:${request.exchange}` : ''}`;
@@ -355,6 +498,15 @@ export class StockPriceService implements IProviderRegistry {
   }
 
   private addToCache(key: string, price: IStockPrice | IStockPrice[], ttl?: number): void {
+    // Deduplicate array entries by timestamp before caching
+    if (Array.isArray(price)) {
+      const beforeCount = price.length;
+      price = this.deduplicateByTimestamp(price);
+      if (price.length < beforeCount) {
+        console.log(`Deduplicated ${beforeCount - price.length} duplicate timestamps in cache entry for ${key}`);
+      }
+    }
+
     // Enforce max entries limit
     if (this.cache.size >= this.cacheConfig.maxEntries) {
       // Remove oldest entry

ts/stocks/index.ts

@@ -16,3 +16,4 @@ export * from './classes.baseproviderservice.js';
 export * from './providers/provider.yahoo.js';
 export * from './providers/provider.marketstack.js';
 export * from './providers/provider.secedgar.js';
+export * from './providers/provider.coingecko.js';

ts/stocks/interfaces/provider.ts

@@ -24,6 +24,8 @@ export interface IProviderConfig {
   timeout?: number;
   retryAttempts?: number;
   retryDelay?: number;
+  maxRecords?: number; // Maximum records to fetch per request (default: 10000)
+  defaultIntradayLimit?: number; // Default limit for intraday requests without explicit limit (default: 1000)
 }
 
 export interface IProviderRegistry {

ts/stocks/providers/provider.coingecko.ts

@@ -0,0 +1,791 @@
+import * as plugins from '../../plugins.js';
+import type { IStockProvider, IProviderConfig } from '../interfaces/provider.js';
+import type {
+  IStockPrice,
+  IStockDataRequest,
+  IStockCurrentRequest,
+  IStockHistoricalRequest,
+  IStockIntradayRequest,
+  IStockBatchCurrentRequest
+} from '../interfaces/stockprice.js';
+
+/**
+ * Custom error for rate limit exceeded responses
+ */
+class RateLimitError extends Error {
+  constructor(
+    message: string,
+    public waitTime: number,
+    public retryAfter?: number
+  ) {
+    super(message);
+    this.name = 'RateLimitError';
+  }
+}
+
+/**
+ * Rate limiter for CoinGecko API
+ * Free tier (Demo): 30 requests per minute
+ * Without registration: 5-15 requests per minute
+ */
+class RateLimiter {
+  private requestTimes: number[] = [];
+  private maxRequestsPerMinute: number;
+  private consecutiveRateLimitErrors: number = 0;
+
+  constructor(maxRequestsPerMinute: number = 30) {
+    this.maxRequestsPerMinute = maxRequestsPerMinute;
+  }
+
+  public async waitForSlot(): Promise<void> {
+    const now = Date.now();
+    const oneMinuteAgo = now - 60000;
+
+    // Remove requests older than 1 minute
+    this.requestTimes = this.requestTimes.filter(time => time > oneMinuteAgo);
+
+    // If we've hit the limit, wait
+    if (this.requestTimes.length >= this.maxRequestsPerMinute) {
+      const oldestRequest = this.requestTimes[0];
+      const waitTime = 60000 - (now - oldestRequest) + 100; // +100ms buffer
+      await plugins.smartdelay.delayFor(waitTime);
+      return this.waitForSlot(); // Recursively check again
+    }
+
+    // Record this request
+    this.requestTimes.push(now);
+  }
+
+  /**
+   * Get time in milliseconds until next request slot is available
+   */
+  public getTimeUntilNextSlot(): number {
+    const now = Date.now();
+    const oneMinuteAgo = now - 60000;
+
+    // Clean old requests
+    const recentRequests = this.requestTimes.filter(time => time > oneMinuteAgo);
+
+    if (recentRequests.length < this.maxRequestsPerMinute) {
+      return 0; // Slot available now
+    }
+
+    // Calculate wait time until oldest request expires
+    const oldestRequest = recentRequests[0];
+    return Math.max(0, 60000 - (now - oldestRequest) + 100);
+  }
+
+  /**
+   * Handle rate limit error with exponential backoff
+   * Returns wait time in milliseconds
+   */
+  public handleRateLimitError(): number {
+    this.consecutiveRateLimitErrors++;
+
+    // Exponential backoff: 1s, 2s, 4s, 8s, 16s, 32s, 60s (max)
+    const baseWait = 1000; // 1 second
+    const exponent = this.consecutiveRateLimitErrors - 1;
+    const backoff = Math.min(
+      baseWait * Math.pow(2, exponent),
+      60000 // max 60 seconds
+    );
+
+    // After 3 consecutive 429s, reduce rate limit to 80% as safety measure
+    if (this.consecutiveRateLimitErrors >= 3) {
+      const newLimit = Math.floor(this.maxRequestsPerMinute * 0.8);
+      if (newLimit < this.maxRequestsPerMinute) {
+        console.warn(
+          `Adjusting rate limit from ${this.maxRequestsPerMinute} to ${newLimit} requests/min due to repeated 429 errors`
+        );
+        this.maxRequestsPerMinute = newLimit;
+      }
+    }
+
+    return backoff;
+  }
+
+  /**
+   * Reset consecutive error count on successful request
+   */
+  public resetErrors(): void {
+    if (this.consecutiveRateLimitErrors > 0) {
+      this.consecutiveRateLimitErrors = 0;
+    }
+  }
+}
+
+/**
+ * Interface for coin list response
+ */
+interface ICoinListItem {
+  id: string;
+  symbol: string;
+  name: string;
+}
+
+/**
+ * CoinGecko Crypto Price Provider
+ *
+ * Documentation: https://docs.coingecko.com/v3.0.1/reference/endpoint-overview
+ *
+ * Features:
+ * - Current crypto prices (single and batch)
+ * - Historical price data with OHLCV
+ * - 13M+ tokens, 240+ networks, 1600+ exchanges
+ * - Accepts both ticker symbols (BTC, ETH) and CoinGecko IDs (bitcoin, ethereum)
+ * - 24/7 market data (crypto never closes)
+ *
+ * Rate Limits:
+ * - Free tier (no key): 5-15 requests/minute
+ * - Demo plan (free with registration): ~30 requests/minute, 10,000/month
+ * - Paid plans: Higher limits
+ *
+ * API Authentication:
+ * - Optional API key for Demo/paid plans
+ * - Header: x-cg-demo-api-key (Demo) or x-cg-pro-api-key (paid)
+ */
+export class CoinGeckoProvider implements IStockProvider {
+  public name = 'CoinGecko';
+  public priority = 90; // High priority for crypto, between Yahoo (100) and Marketstack (80)
+  public readonly requiresAuth = false; // API key is optional
+  public readonly rateLimit = {
+    requestsPerMinute: 30, // Demo plan default
+    requestsPerDay: 10000 // Demo plan monthly quota / 30
+  };
+
+  private logger = console;
+  private baseUrl = 'https://api.coingecko.com/api/v3';
+  private apiKey?: string;
+  private rateLimiter: RateLimiter;
+
+  // Coin mapping cache
+  private coinMapCache = new Map<string, string>(); // ticker/id -> coingecko id
+  private coinListLoadedAt: Date | null = null;
+  private readonly coinListCacheTTL = 24 * 60 * 60 * 1000; // 24 hours
+
+  // Priority map for common crypto tickers (to avoid conflicts)
+  private readonly priorityTickerMap = new Map<string, string>([
+    ['btc', 'bitcoin'],
+    ['eth', 'ethereum'],
+    ['usdt', 'tether'],
+    ['bnb', 'binancecoin'],
+    ['sol', 'solana'],
+    ['usdc', 'usd-coin'],
+    ['xrp', 'ripple'],
+    ['ada', 'cardano'],
+    ['doge', 'dogecoin'],
+    ['trx', 'tron'],
+    ['dot', 'polkadot'],
+    ['matic', 'matic-network'],
+    ['ltc', 'litecoin'],
+    ['shib', 'shiba-inu'],
+    ['avax', 'avalanche-2'],
+    ['link', 'chainlink'],
+    ['atom', 'cosmos'],
+    ['uni', 'uniswap'],
+    ['etc', 'ethereum-classic'],
+    ['xlm', 'stellar']
+  ]);
+
+  constructor(apiKey?: string, private config?: IProviderConfig) {
+    this.apiKey = apiKey;
+    this.rateLimiter = new RateLimiter(this.rateLimit.requestsPerMinute);
+  }
+
+  /**
+   * Unified data fetching method supporting all request types
+   */
+  public async fetchData(request: IStockDataRequest): Promise<IStockPrice | IStockPrice[]> {
+    switch (request.type) {
+      case 'current':
+        return this.fetchCurrentPrice(request);
+      case 'batch':
+        return this.fetchBatchCurrentPrices(request);
+      case 'historical':
+        return this.fetchHistoricalPrices(request);
+      case 'intraday':
+        return this.fetchIntradayPrices(request);
+      default:
+        throw new Error(`Unsupported request type: ${(request as any).type}`);
+    }
+  }
+
+  /**
+   * Fetch current price for a single crypto
+   */
+  private async fetchCurrentPrice(request: IStockCurrentRequest): Promise<IStockPrice> {
+    return this.fetchWithRateLimitRetry(async () => {
+      // Resolve ticker to CoinGecko ID
+      const coinId = await this.resolveCoinId(request.ticker);
+
+      // Build URL
+      const params = new URLSearchParams({
+        ids: coinId,
+        vs_currencies: 'usd',
+        include_market_cap: 'true',
+        include_24hr_vol: 'true',
+        include_24hr_change: 'true',
+        include_last_updated_at: 'true'
+      });
+
+      const url = `${this.baseUrl}/simple/price?${params}`;
+
+      // Wait for rate limit slot
+      await this.rateLimiter.waitForSlot();
+
+      // Make request
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(url)
+        .headers(this.buildHeaders())
+        .timeout(this.config?.timeout || 10000)
+        .get();
+
+      const responseData = await response.json() as any;
+
+      // Check for rate limit error
+      if (this.isRateLimitError(responseData)) {
+        const waitTime = this.rateLimiter.handleRateLimitError();
+        throw new RateLimitError(
+          `Rate limit exceeded for ${request.ticker}`,
+          waitTime
+        );
+      }
+
+      if (!responseData[coinId]) {
+        throw new Error(`No data found for ${request.ticker} (${coinId})`);
+      }
+
+      return this.mapToStockPrice(request.ticker, coinId, responseData[coinId], 'live');
+    }, `current price for ${request.ticker}`);
+  }
+
+  /**
+   * Fetch batch current prices for multiple cryptos
+   */
+  private async fetchBatchCurrentPrices(request: IStockBatchCurrentRequest): Promise<IStockPrice[]> {
+    return this.fetchWithRateLimitRetry(async () => {
+      // Resolve all tickers to CoinGecko IDs
+      const coinIds = await Promise.all(
+        request.tickers.map(ticker => this.resolveCoinId(ticker))
+      );
+
+      // Build URL with comma-separated IDs
+      const params = new URLSearchParams({
+        ids: coinIds.join(','),
+        vs_currencies: 'usd',
+        include_market_cap: 'true',
+        include_24hr_vol: 'true',
+        include_24hr_change: 'true',
+        include_last_updated_at: 'true'
+      });
+
+      const url = `${this.baseUrl}/simple/price?${params}`;
+
+      // Wait for rate limit slot
+      await this.rateLimiter.waitForSlot();
+
+      // Make request
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(url)
+        .headers(this.buildHeaders())
+        .timeout(this.config?.timeout || 15000)
+        .get();
+
+      const responseData = await response.json() as any;
+
+      // Check for rate limit error
+      if (this.isRateLimitError(responseData)) {
+        const waitTime = this.rateLimiter.handleRateLimitError();
+        throw new RateLimitError(
+          `Rate limit exceeded for batch request`,
+          waitTime
+        );
+      }
+
+      const prices: IStockPrice[] = [];
+
+      // Map responses back to original tickers
+      for (let i = 0; i < request.tickers.length; i++) {
+        const ticker = request.tickers[i];
+        const coinId = coinIds[i];
+
+        if (responseData[coinId]) {
+          try {
+            prices.push(this.mapToStockPrice(ticker, coinId, responseData[coinId], 'live'));
+          } catch (error) {
+            this.logger.warn(`Failed to parse data for ${ticker}:`, error);
+          }
+        } else {
+          this.logger.warn(`No data returned for ${ticker} (${coinId})`);
+        }
+      }
+
+      if (prices.length === 0) {
+        throw new Error('No valid price data received from batch request');
+      }
+
+      return prices;
+    }, `batch prices for ${request.tickers.length} tickers`);
+  }
+
+  /**
+   * Fetch historical prices with OHLCV data
+   */
+  private async fetchHistoricalPrices(request: IStockHistoricalRequest): Promise<IStockPrice[]> {
+    return this.fetchWithRateLimitRetry(async () => {
+      const coinId = await this.resolveCoinId(request.ticker);
+
+      // Calculate days between dates
+      const days = Math.ceil((request.to.getTime() - request.from.getTime()) / (1000 * 60 * 60 * 24));
+
+      // Build URL
+      const params = new URLSearchParams({
+        vs_currency: 'usd',
+        days: days.toString(),
+        interval: 'daily' // Explicit daily granularity for historical data
+      });
+
+      const url = `${this.baseUrl}/coins/${coinId}/market_chart?${params}`;
+
+      // Wait for rate limit slot
+      await this.rateLimiter.waitForSlot();
+
+      // Make request
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(url)
+        .headers(this.buildHeaders())
+        .timeout(this.config?.timeout || 20000)
+        .get();
+
+      const responseData = await response.json() as any;
+
+      // Check for rate limit error
+      if (this.isRateLimitError(responseData)) {
+        const waitTime = this.rateLimiter.handleRateLimitError();
+        throw new RateLimitError(
+          `Rate limit exceeded for historical ${request.ticker}`,
+          waitTime
+        );
+      }
+
+      if (!responseData.prices || !Array.isArray(responseData.prices)) {
+        this.logger.error(`Invalid API response for ${request.ticker}:`, JSON.stringify(responseData).substring(0, 500));
+        throw new Error(`Invalid response format for ${request.ticker}: ${JSON.stringify(responseData).substring(0, 200)}`);
+      }
+
+      const prices: IStockPrice[] = [];
+      const priceData = responseData.prices;
+      const marketCapData = responseData.market_caps || [];
+      const volumeData = responseData.total_volumes || [];
+
+      // Warn if processing large amount of historical data
+      const maxRecords = this.config?.maxRecords || 10000;
+      if (priceData.length > maxRecords) {
+        this.logger.warn(
+          `Historical request for ${request.ticker} returned ${priceData.length} records, ` +
+          `which exceeds maxRecords limit of ${maxRecords}. Processing first ${maxRecords} only.`
+        );
+      }
+
+      // Process each data point (up to maxRecords)
+      const recordsToProcess = Math.min(priceData.length, maxRecords);
+      for (let i = 0; i < recordsToProcess; i++) {
+        const [timestamp, price] = priceData[i];
+        const date = new Date(timestamp);
+
+        // Filter by date range
+        if (date < request.from || date > request.to) continue;
+
+        const marketCap = marketCapData[i]?.[1];
+        const volume = volumeData[i]?.[1];
+
+        // Calculate previous close for change calculation
+        const previousClose = i > 0 ? priceData[i - 1][1] : price;
+        const change = price - previousClose;
+        const changePercent = previousClose !== 0 ? (change / previousClose) * 100 : 0;
+
+        prices.push({
+          ticker: request.ticker.toUpperCase(),
+          price: price,
+          currency: 'USD',
+          change: change,
+          changePercent: changePercent,
+          previousClose: previousClose,
+          timestamp: date,
+          provider: this.name,
+          marketState: 'REGULAR', // Crypto markets are always open
+
+          // OHLCV data (note: market_chart doesn't provide OHLC, only close prices)
+          volume: volume,
+
+          dataType: 'eod',
+          fetchedAt: new Date(),
+
+          companyName: coinId.charAt(0).toUpperCase() + coinId.slice(1)
+        });
+      }
+
+      return prices;
+    }, `historical prices for ${request.ticker}`);
+  }
+
+  /**
+   * Fetch intraday prices with hourly intervals
+   */
+  private async fetchIntradayPrices(request: IStockIntradayRequest): Promise<IStockPrice[]> {
+    return this.fetchWithRateLimitRetry(async () => {
+      const coinId = await this.resolveCoinId(request.ticker);
+
+      // Map interval to days parameter (CoinGecko auto-granularity)
+      // For hourly data, request 1-7 days
+      let days = 1;
+      switch (request.interval) {
+        case '1min':
+        case '5min':
+        case '10min':
+        case '15min':
+        case '30min':
+          throw new Error('CoinGecko only supports hourly intervals in market_chart. Use interval: "1hour"');
+        case '1hour':
+          days = 1; // Last 24 hours with hourly granularity
+          break;
+      }
+
+      // Build URL (omit interval param for automatic granularity based on days)
+      const params = new URLSearchParams({
+        vs_currency: 'usd',
+        days: days.toString()
+      });
+
+      const url = `${this.baseUrl}/coins/${coinId}/market_chart?${params}`;
+
+      // Wait for rate limit slot
+      await this.rateLimiter.waitForSlot();
+
+      // Make request
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(url)
+        .headers(this.buildHeaders())
+        .timeout(this.config?.timeout || 15000)
+        .get();
+
+      const responseData = await response.json() as any;
+
+      // Check for rate limit error
+      if (this.isRateLimitError(responseData)) {
+        const waitTime = this.rateLimiter.handleRateLimitError();
+        throw new RateLimitError(
+          `Rate limit exceeded for intraday ${request.ticker}`,
+          waitTime
+        );
+      }
+
+      if (!responseData.prices || !Array.isArray(responseData.prices)) {
+        this.logger.error(`Invalid API response for ${request.ticker}:`, JSON.stringify(responseData).substring(0, 500));
+        throw new Error(`Invalid response format for ${request.ticker}: ${JSON.stringify(responseData).substring(0, 200)}`);
+      }
+
+      const prices: IStockPrice[] = [];
+      const priceData = responseData.prices;
+      const marketCapData = responseData.market_caps || [];
+      const volumeData = responseData.total_volumes || [];
+
+      // Apply default limit if user didn't specify one (performance optimization)
+      const effectiveLimit = request.limit || this.config?.defaultIntradayLimit || 1000;
+
+      // Warn if fetching large amount of data without explicit limit
+      if (!request.limit && priceData.length > effectiveLimit) {
+        this.logger.warn(
+          `Intraday request for ${request.ticker} returned ${priceData.length} records but no limit specified. ` +
+          `Applying default limit of ${effectiveLimit}. Consider adding a limit to the request for better performance.`
+        );
+      }
+
+      // Apply limit (take most recent data)
+      const limit = Math.min(effectiveLimit, priceData.length);
+      const dataToProcess = priceData.slice(-limit);
+
+      for (let i = 0; i < dataToProcess.length; i++) {
+        const actualIndex = priceData.length - limit + i;
+        const [timestamp, price] = dataToProcess[i];
+        const date = new Date(timestamp);
+
+        const marketCap = marketCapData[actualIndex]?.[1];
+        const volume = volumeData[actualIndex]?.[1];
+
+        const previousClose = i > 0 ? dataToProcess[i - 1][1] : price;
+        const change = price - previousClose;
+        const changePercent = previousClose !== 0 ? (change / previousClose) * 100 : 0;
+
+        prices.push({
+          ticker: request.ticker.toUpperCase(),
+          price: price,
+          currency: 'USD',
+          change: change,
+          changePercent: changePercent,
+          previousClose: previousClose,
+          timestamp: date,
+          provider: this.name,
+          marketState: 'REGULAR',
+
+          volume: volume,
+
+          dataType: 'intraday',
+          fetchedAt: new Date(),
+
+          companyName: coinId.charAt(0).toUpperCase() + coinId.slice(1)
+        });
+      }
+
+      return prices;
+    }, `intraday prices for ${request.ticker}`);
+  }
+
+  /**
+   * Check if CoinGecko API is available
+   */
+  public async isAvailable(): Promise<boolean> {
+    try {
+      const url = `${this.baseUrl}/simple/price?ids=bitcoin&vs_currencies=usd`;
+
+      await this.rateLimiter.waitForSlot();
+
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(url)
+        .headers(this.buildHeaders())
+        .timeout(5000)
+        .get();
+
+      const responseData = await response.json() as any;
+      return responseData.bitcoin?.usd !== undefined;
+    } catch (error) {
+      this.logger.warn('CoinGecko provider is not available:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Check if a market/network is supported
+   * CoinGecko supports 240+ networks
+   */
+  public supportsMarket(market: string): boolean {
+    // CoinGecko has extensive crypto network coverage
+    const supportedNetworks = [
+      'CRYPTO', 'BTC', 'ETH', 'BSC', 'POLYGON', 'AVALANCHE',
+      'SOLANA', 'ARBITRUM', 'OPTIMISM', 'BASE'
+    ];
+    return supportedNetworks.includes(market.toUpperCase());
+  }
+
+  /**
+   * Check if a ticker format is supported
+   * Supports both ticker symbols (BTC) and CoinGecko IDs (bitcoin)
+   */
+  public supportsTicker(ticker: string): boolean {
+    // Accept alphanumeric with hyphens (for coin IDs like 'wrapped-bitcoin')
+    return /^[A-Za-z0-9\-]{1,50}$/.test(ticker);
+  }
+
+  /**
+   * Resolve ticker symbol or CoinGecko ID to canonical CoinGecko ID
+   * Supports both formats: "BTC" -> "bitcoin", "bitcoin" -> "bitcoin"
+   */
+  private async resolveCoinId(tickerOrId: string): Promise<string> {
+    const normalized = tickerOrId.toLowerCase();
+
+    // Check priority map first (for common cryptos)
+    if (this.priorityTickerMap.has(normalized)) {
+      const coinId = this.priorityTickerMap.get(normalized)!;
+      this.coinMapCache.set(normalized, coinId);
+      return coinId;
+    }
+
+    // Check cache
+    if (this.coinMapCache.has(normalized)) {
+      return this.coinMapCache.get(normalized)!;
+    }
+
+    // Check if it's already a valid CoinGecko ID (contains hyphens or is all lowercase with original case)
+    if (normalized.includes('-') || normalized === tickerOrId) {
+      // Assume it's a CoinGecko ID, cache it
+      this.coinMapCache.set(normalized, normalized);
+      return normalized;
+    }
+
+    // Load coin list if needed
+    if (!this.coinListLoadedAt ||
+        Date.now() - this.coinListLoadedAt.getTime() > this.coinListCacheTTL) {
+      await this.loadCoinList();
+    }
+
+    // Try to find in cache after loading
+    if (this.coinMapCache.has(normalized)) {
+      return this.coinMapCache.get(normalized)!;
+    }
+
+    // Not found - return as-is and let API handle the error
+    this.logger.warn(`Could not resolve ticker ${tickerOrId} to CoinGecko ID, using as-is`);
+    return normalized;
+  }
+
+  /**
+   * Load complete coin list from CoinGecko API
+   */
+  private async loadCoinList(): Promise<void> {
+    try {
+      const url = `${this.baseUrl}/coins/list`;
+
+      await this.rateLimiter.waitForSlot();
+
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(url)
+        .headers(this.buildHeaders())
+        .timeout(10000)
+        .get();
+
+      const coinList = await response.json() as ICoinListItem[];
+
+      // Clear cache before rebuilding to prevent memory leak
+      // Keep only entries that are in priorityTickerMap
+      const priorityEntries = new Map<string, string>();
+      for (const [key, value] of this.priorityTickerMap) {
+        priorityEntries.set(key, value);
+      }
+      this.coinMapCache.clear();
+
+      // Restore priority mappings
+      for (const [key, value] of priorityEntries) {
+        this.coinMapCache.set(key, value);
+      }
+
+      // Build mapping: symbol -> id
+      for (const coin of coinList) {
+        const symbol = coin.symbol.toLowerCase();
+        const id = coin.id.toLowerCase();
+
+        // Don't overwrite priority mappings
+        if (!this.priorityTickerMap.has(symbol)) {
+          this.coinMapCache.set(symbol, id);
+        }
+        // Always cache the ID mapping (id -> id for when users pass CoinGecko IDs directly)
+        this.coinMapCache.set(id, id);
+      }
+
+      this.coinListLoadedAt = new Date();
+      this.logger.info(`Loaded ${coinList.length} coins from CoinGecko (cache: ${this.coinMapCache.size} entries)`);
+    } catch (error) {
+      this.logger.error('Failed to load coin list from CoinGecko:', error);
+      // Don't throw - we can still work with direct IDs
+    }
+  }
+
+  /**
+   * Map CoinGecko simple/price response to IStockPrice
+   */
+  private mapToStockPrice(
+    ticker: string,
+    coinId: string,
+    data: any,
+    dataType: 'live' | 'eod' | 'intraday'
+  ): IStockPrice {
+    const price = data.usd;
+    const change24h = data.usd_24h_change || 0;
+
+    // Calculate previous close from 24h change
+    const changePercent = change24h;
+    const change = (price * changePercent) / 100;
+    const previousClose = price - change;
+
+    // Parse last updated timestamp
+    const timestamp = data.last_updated_at
+      ? new Date(data.last_updated_at * 1000)
+      : new Date();
+
+    return {
+      ticker: ticker.toUpperCase(),
+      price: price,
+      currency: 'USD',
+      change: change,
+      changePercent: changePercent,
+      previousClose: previousClose,
+      timestamp: timestamp,
+      provider: this.name,
+      marketState: 'REGULAR', // Crypto markets are 24/7
+
+      // Volume and market cap
+      volume: data.usd_24h_vol,
+
+      dataType: dataType,
+      fetchedAt: new Date(),
+
+      // Company identification (use coin name)
+      companyName: coinId.charAt(0).toUpperCase() + coinId.slice(1),
+      companyFullName: `${coinId.charAt(0).toUpperCase() + coinId.slice(1)} (${ticker.toUpperCase()})`
+    };
+  }
+
+  /**
+   * Build HTTP headers with optional API key
+   */
+  private buildHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Accept': 'application/json'
+    };
+
+    if (this.apiKey) {
+      // Use Demo or Pro API key header
+      // CoinGecko accepts both x-cg-demo-api-key and x-cg-pro-api-key
+      headers['x-cg-demo-api-key'] = this.apiKey;
+    }
+
+    return headers;
+  }
+
+  /**
+   * Check if response indicates a rate limit error (429)
+   */
+  private isRateLimitError(responseData: any): boolean {
+    return responseData?.status?.error_code === 429;
+  }
+
+  /**
+   * Wrapper for fetch operations with automatic rate limit retry and exponential backoff
+   */
+  private async fetchWithRateLimitRetry<T>(
+    fetchFn: () => Promise<T>,
+    operationName: string,
+    maxRetries: number = 3
+  ): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        const result = await fetchFn();
+        this.rateLimiter.resetErrors();
+        return result;
+      } catch (error) {
+        lastError = error as Error;
+
+        if (error instanceof RateLimitError) {
+          const attemptInfo = `${attempt + 1}/${maxRetries}`;
+          this.logger.warn(
+            `Rate limit hit for ${operationName}, waiting ${error.waitTime}ms before retry ${attemptInfo}`
+          );
+
+          if (attempt < maxRetries - 1) {
+            await plugins.smartdelay.delayFor(error.waitTime);
+            continue;
+          } else {
+            this.logger.error(`Max retries (${maxRetries}) exceeded for ${operationName} due to rate limiting`);
+            throw error;
+          }
+        }
+
+        // Non-rate-limit errors: throw immediately
+        throw error;
+      }
+    }
+
+    throw lastError!;
+  }
+}

ts/stocks/providers/provider.marketstack.ts

@@ -10,32 +10,39 @@ import type {
 } from '../interfaces/stockprice.js';
 
 /**
- * Marketstack API v2 Provider - Enhanced
+ * Marketstack API v2 Provider - Professional Plan with Intelligent Intraday Support
  * Documentation: https://docs.apilayer.com/marketstack/docs/marketstack-api-v2-v-2-0-0
  *
  * Features:
+ * - Intelligent endpoint selection based on market hours
+ * - Real-time intraday pricing with multiple intervals (1min, 5min, 10min, 15min, 30min, 1hour)
  * - End-of-Day (EOD) stock prices with historical data
- * - Intraday pricing with multiple intervals (1min, 5min, 15min, 30min, 1hour)
+ * - Market state detection (PRE, REGULAR, POST, CLOSED)
  * - Exchange filtering via MIC codes (XNAS, XNYS, XLON, etc.)
  * - Supports 500,000+ tickers across 72+ exchanges worldwide
  * - OHLCV data (Open, High, Low, Close, Volume)
  * - Pagination for large datasets
+ * - Automatic fallback from intraday to EOD on errors
  * - Requires API key authentication
  *
+ * Intelligent Endpoint Selection:
+ * - During market hours (PRE/REGULAR/POST): Uses intraday endpoints for fresh data
+ * - After market close (CLOSED): Uses EOD endpoints to save API credits
+ * - Automatic fallback to EOD if intraday fails (rate limits, plan restrictions, etc.)
+ *
  * Rate Limits:
  * - Free Plan: 100 requests/month (EOD only)
- * - Basic Plan: 10,000 requests/month
+ * - Basic Plan: 10,000 requests/month (EOD only)
- * - Professional Plan: 100,000 requests/month (intraday access)
+ * - Professional Plan: 100,000 requests/month (intraday + EOD)
  *
- * Phase 1 Enhancements:
+ * Intraday Access:
- * - Historical data retrieval with date ranges
+ * - Intervals below 15min (1min, 5min, 10min) require Professional Plan or higher
- * - Exchange filtering
+ * - Real-time data from IEX Exchange for US tickers
- * - OHLCV data support
+ * - Symbol formatting: Periods replaced with hyphens for intraday (BRK.B → BRK-B)
- * - Pagination handling
  */
 export class MarketstackProvider implements IStockProvider {
   public name = 'Marketstack';
-  public priority = 80; // Lower than Yahoo (100) due to rate limits and EOD-only data
+  public priority = 90; // Increased from 80 - now supports real-time intraday data during market hours
   public readonly requiresAuth = true;
   public readonly rateLimit = {
     requestsPerMinute: undefined, // No per-minute limit specified
@@ -73,10 +80,78 @@ export class MarketstackProvider implements IStockProvider {
   }
 
   /**
-   * Fetch current/latest EOD price for a single ticker (new API)
+   * Fetch current/latest price with intelligent endpoint selection
+   * Uses intraday during market hours (PRE, REGULAR, POST) for fresh data
+   * Uses EOD after market close (CLOSED) to save API credits
    */
   private async fetchCurrentPrice(request: IStockCurrentRequest): Promise<IStockPrice> {
     try {
+      // Determine current market state
+      const marketState = this.getUsMarketState();
+      const useIntraday = this.shouldUseIntradayEndpoint(marketState);
+
+      if (useIntraday) {
+        // Use intraday endpoint for fresh data during market hours
+        return await this.fetchCurrentPriceIntraday(request, marketState);
+      } else {
+        // Use EOD endpoint for after-close data
+        return await this.fetchCurrentPriceEod(request);
+      }
+    } catch (error) {
+      // If intraday fails, fallback to EOD with warning
+      if (error.message?.includes('intraday') || error.message?.includes('Marketstack API error')) {
+        this.logger.warn(`Intraday endpoint failed for ${request.ticker}, falling back to EOD:`, error.message);
+        try {
+          return await this.fetchCurrentPriceEod(request);
+        } catch (eodError) {
+          // Both failed, throw original error
+          throw error;
+        }
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Fetch current price using intraday endpoint (during market hours)
+   * Uses 1min interval for most recent data
+   */
+  private async fetchCurrentPriceIntraday(
+    request: IStockCurrentRequest,
+    marketState: 'PRE' | 'REGULAR' | 'POST' | 'CLOSED'
+  ): Promise<IStockPrice> {
+    const formattedSymbol = this.formatSymbolForIntraday(request.ticker);
+    let url = `${this.baseUrl}/tickers/${formattedSymbol}/intraday/latest?access_key=${this.apiKey}`;
+    url += `&interval=1min`; // Use 1min for most recent data
+
+    // Add exchange filter if specified
+    if (request.exchange) {
+      url += `&exchange=${request.exchange}`;
+    }
+
+    const response = await plugins.smartrequest.SmartRequest.create()
+      .url(url)
+      .timeout(this.config?.timeout || 10000)
+      .get();
+
+    const responseData = await response.json() as any;
+
+    // Check for API errors
+    if (responseData.error) {
+      throw new Error(`Marketstack API error: ${responseData.error.message || JSON.stringify(responseData.error)}`);
+    }
+
+    if (!responseData || !responseData.close) {
+      throw new Error(`No intraday data found for ticker ${request.ticker}`);
+    }
+
+    return this.mapToStockPrice(responseData, 'intraday', marketState);
+  }
+
+  /**
+   * Fetch current price using EOD endpoint (after market close)
+   */
+  private async fetchCurrentPriceEod(request: IStockCurrentRequest): Promise<IStockPrice> {
     let url = `${this.baseUrl}/tickers/${request.ticker}/eod/latest?access_key=${this.apiKey}`;
 
     // Add exchange filter if specified
@@ -102,10 +177,6 @@ export class MarketstackProvider implements IStockProvider {
     }
 
     return this.mapToStockPrice(responseData, 'eod');
-    } catch (error) {
-      this.logger.error(`Failed to fetch current price for ${request.ticker}:`, error);
-      throw new Error(`Marketstack: Failed to fetch current price for ${request.ticker}: ${error.message}`);
-    }
   }
 
   /**
@@ -116,7 +187,7 @@ export class MarketstackProvider implements IStockProvider {
       const allPrices: IStockPrice[] = [];
       let offset = request.offset || 0;
       const limit = request.limit || 1000; // Max per page
-      const maxRecords = 10000; // Safety limit
+      const maxRecords = this.config?.maxRecords || 10000; // Safety limit (configurable)
 
       while (true) {
         let url = `${this.baseUrl}/eod?access_key=${this.apiKey}`;
@@ -179,17 +250,182 @@ export class MarketstackProvider implements IStockProvider {
   }
 
   /**
-   * Fetch intraday prices with specified interval (Phase 2 placeholder)
+   * Fetch intraday prices with specified interval
+   * Supports intervals: 1min, 5min, 10min, 15min, 30min, 1hour
+   * Note: Intervals below 15min require Professional Plan or higher
    */
   private async fetchIntradayPrices(request: IStockIntradayRequest): Promise<IStockPrice[]> {
-    throw new Error('Intraday data support coming in Phase 2. For now, use EOD data with type: "current" or "historical"');
+    try {
+      const allPrices: IStockPrice[] = [];
+      let offset = 0;
+      const limit = 1000; // Max per page for intraday
+      const maxRecords = this.config?.maxRecords || 10000; // Safety limit (configurable)
+
+      // Apply default limit if user didn't specify one (performance optimization)
+      const effectiveLimit = request.limit || this.config?.defaultIntradayLimit || 1000;
+
+      // Warn if fetching large amount of data without explicit limit
+      if (!request.limit && effectiveLimit > 1000) {
+        this.logger.warn(
+          `Intraday request for ${request.ticker} without explicit limit will fetch up to ${effectiveLimit} records. ` +
+          `Consider adding a limit to the request for better performance.`
+        );
+      }
+
+      // Format symbol for intraday endpoint (replace . with -)
+      const formattedSymbol = this.formatSymbolForIntraday(request.ticker);
+
+      while (true) {
+        let url = `${this.baseUrl}/tickers/${formattedSymbol}/intraday?access_key=${this.apiKey}`;
+        url += `&interval=${request.interval}`;
+        url += `&limit=${limit}`;
+        url += `&offset=${offset}`;
+
+        // Add date filter if specified
+        if (request.date) {
+          url += `&date_from=${this.formatDate(request.date)}`;
+          url += `&date_to=${this.formatDate(request.date)}`;
+        }
+
+        // Add exchange filter if specified
+        if (request.exchange) {
+          url += `&exchange=${request.exchange}`;
+        }
+
+        const response = await plugins.smartrequest.SmartRequest.create()
+          .url(url)
+          .timeout(this.config?.timeout || 15000)
+          .get();
+
+        const responseData = await response.json() as any;
+
+        // Check for API errors
+        if (responseData.error) {
+          throw new Error(`Marketstack API error: ${responseData.error.message || JSON.stringify(responseData.error)}`);
+        }
+
+        if (!responseData?.data || !Array.isArray(responseData.data)) {
+          throw new Error('Invalid response format from Marketstack API');
+        }
+
+        // Map data to stock prices
+        for (const data of responseData.data) {
+          try {
+            allPrices.push(this.mapToStockPrice(data, 'intraday'));
+          } catch (error) {
+            this.logger.warn(`Failed to parse intraday data for ${data.symbol}:`, error);
+          }
+        }
+
+        // Check if we have more pages
+        const pagination = responseData.pagination;
+        const hasMore = pagination && offset + limit < pagination.total;
+
+        // Honor effective limit or safety maxRecords
+        if (!hasMore || allPrices.length >= effectiveLimit || allPrices.length >= maxRecords) {
+          break;
+        }
+
+        offset += limit;
+      }
+
+      // Apply effective limit
+      if (allPrices.length > effectiveLimit) {
+        return allPrices.slice(0, effectiveLimit);
+      }
+
+      return allPrices;
+    } catch (error) {
+      this.logger.error(`Failed to fetch intraday prices for ${request.ticker}:`, error);
+      throw new Error(`Marketstack: Failed to fetch intraday prices for ${request.ticker}: ${error.message}`);
+    }
   }
 
   /**
-   * Fetch current prices for multiple tickers (new API)
+   * Fetch current prices for multiple tickers with intelligent endpoint selection
+   * Uses intraday during market hours (PRE, REGULAR, POST) for fresh data
+   * Uses EOD after market close (CLOSED) to save API credits
    */
   private async fetchBatchCurrentPrices(request: IStockBatchCurrentRequest): Promise<IStockPrice[]> {
     try {
+      // Determine current market state
+      const marketState = this.getUsMarketState();
+      const useIntraday = this.shouldUseIntradayEndpoint(marketState);
+
+      if (useIntraday) {
+        return await this.fetchBatchCurrentPricesIntraday(request, marketState);
+      } else {
+        return await this.fetchBatchCurrentPricesEod(request);
+      }
+    } catch (error) {
+      // Fallback to EOD if intraday fails
+      if (error.message?.includes('intraday') || error.message?.includes('Marketstack API error')) {
+        this.logger.warn(`Intraday batch endpoint failed, falling back to EOD:`, error.message);
+        try {
+          return await this.fetchBatchCurrentPricesEod(request);
+        } catch (eodError) {
+          // Both failed, throw original error
+          throw error;
+        }
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Fetch batch current prices using intraday endpoint
+   */
+  private async fetchBatchCurrentPricesIntraday(
+    request: IStockBatchCurrentRequest,
+    marketState: 'PRE' | 'REGULAR' | 'POST' | 'CLOSED'
+  ): Promise<IStockPrice[]> {
+    // Format symbols for intraday (replace . with -)
+    const formattedSymbols = request.tickers.map(t => this.formatSymbolForIntraday(t)).join(',');
+
+    let url = `${this.baseUrl}/intraday/latest?access_key=${this.apiKey}`;
+    url += `&symbols=${formattedSymbols}`;
+    url += `&interval=1min`; // Use 1min for most recent data
+
+    if (request.exchange) {
+      url += `&exchange=${request.exchange}`;
+    }
+
+    const response = await plugins.smartrequest.SmartRequest.create()
+      .url(url)
+      .timeout(this.config?.timeout || 15000)
+      .get();
+
+    const responseData = await response.json() as any;
+
+    if (responseData.error) {
+      throw new Error(`Marketstack API error: ${responseData.error.message || JSON.stringify(responseData.error)}`);
+    }
+
+    if (!responseData?.data || !Array.isArray(responseData.data)) {
+      throw new Error('Invalid response format from Marketstack API');
+    }
+
+    const prices: IStockPrice[] = [];
+
+    for (const data of responseData.data) {
+      try {
+        prices.push(this.mapToStockPrice(data, 'intraday', marketState));
+      } catch (error) {
+        this.logger.warn(`Failed to parse intraday data for ${data.symbol}:`, error);
+      }
+    }
+
+    if (prices.length === 0) {
+      throw new Error('No valid price data received from batch intraday request');
+    }
+
+    return prices;
+  }
+
+  /**
+   * Fetch batch current prices using EOD endpoint
+   */
+  private async fetchBatchCurrentPricesEod(request: IStockBatchCurrentRequest): Promise<IStockPrice[]> {
     const symbols = request.tickers.join(',');
     let url = `${this.baseUrl}/eod/latest?access_key=${this.apiKey}&symbols=${symbols}`;
 
@@ -229,10 +465,6 @@ export class MarketstackProvider implements IStockProvider {
     }
 
     return prices;
-    } catch (error) {
-      this.logger.error(`Failed to fetch batch current prices:`, error);
-      throw new Error(`Marketstack: Failed to fetch batch current prices: ${error.message}`);
-    }
   }
 
   /**
@@ -283,8 +515,15 @@ export class MarketstackProvider implements IStockProvider {
 
   /**
    * Map Marketstack API response to IStockPrice interface
+   * @param data - API response data
+   * @param dataType - Type of data (eod, intraday, live)
+   * @param explicitMarketState - Override market state (used for intraday data fetched during known market hours)
    */
-  private mapToStockPrice(data: any, dataType: 'eod' | 'intraday' | 'live' = 'eod'): IStockPrice {
+  private mapToStockPrice(
+    data: any,
+    dataType: 'eod' | 'intraday' | 'live' = 'eod',
+    explicitMarketState?: 'PRE' | 'REGULAR' | 'POST' | 'CLOSED'
+  ): IStockPrice {
     if (!data.close) {
       throw new Error('Missing required price data');
     }
@@ -301,6 +540,23 @@ export class MarketstackProvider implements IStockProvider {
     const timestamp = data.date ? new Date(data.date) : new Date();
     const fetchedAt = new Date();
 
+    // Determine market state intelligently
+    let marketState: 'PRE' | 'REGULAR' | 'POST' | 'CLOSED';
+
+    if (explicitMarketState) {
+      // Use provided market state (for intraday data fetched during known market hours)
+      marketState = explicitMarketState;
+    } else if (dataType === 'eod') {
+      // EOD data is always for closed markets
+      marketState = 'CLOSED';
+    } else if (dataType === 'intraday') {
+      // For intraday data without explicit state, determine from timestamp
+      marketState = this.getUsMarketState(timestamp.getTime());
+    } else {
+      // Default fallback
+      marketState = 'CLOSED';
+    }
+
     const stockPrice: IStockPrice = {
       ticker: data.symbol.toUpperCase(),
       price: currentPrice,
@@ -310,7 +566,7 @@ export class MarketstackProvider implements IStockProvider {
       previousClose: previousClose,
       timestamp: timestamp,
       provider: this.name,
-      marketState: 'CLOSED', // EOD data is always for closed markets
+      marketState: marketState, // Now dynamic based on data type, timestamp, and explicit state
       exchange: data.exchange,
       exchangeName: data.exchange_code || data.name,
 
@@ -373,4 +629,76 @@ export class MarketstackProvider implements IStockProvider {
     const day = String(date.getDate()).padStart(2, '0');
     return `${year}-${month}-${day}`;
   }
+
+  /**
+   * Get US market state based on Eastern Time
+   * Regular hours: 9:30 AM - 4:00 PM ET
+   * Pre-market: 4:00 AM - 9:30 AM ET
+   * After-hours: 4:00 PM - 8:00 PM ET
+   *
+   * @param timestampMs - Optional timestamp in milliseconds (defaults to current time)
+   * @returns Market state: PRE, REGULAR, POST, or CLOSED
+   */
+  private getUsMarketState(timestampMs?: number): 'PRE' | 'REGULAR' | 'POST' | 'CLOSED' {
+    const now = timestampMs ? new Date(timestampMs) : new Date();
+
+    // Convert to ET (UTC-5 or UTC-4 depending on DST)
+    // For simplicity, we'll use a rough approximation
+    // TODO: Add proper timezone library for production use
+    const etOffset = -5; // Standard time, adjust for DST if needed
+    const etTime = new Date(now.getTime() + (etOffset * 60 * 60 * 1000));
+
+    // Get day of week (0 = Sunday, 6 = Saturday)
+    const dayOfWeek = etTime.getUTCDay();
+
+    // Check if weekend
+    if (dayOfWeek === 0 || dayOfWeek === 6) {
+      return 'CLOSED';
+    }
+
+    // Get hour and minute in ET
+    const hours = etTime.getUTCHours();
+    const minutes = etTime.getUTCMinutes();
+    const timeInMinutes = hours * 60 + minutes;
+
+    // Define market hours in minutes
+    const preMarketStart = 4 * 60; // 4:00 AM
+    const regularMarketStart = 9 * 60 + 30; // 9:30 AM
+    const regularMarketEnd = 16 * 60; // 4:00 PM
+    const afterHoursEnd = 20 * 60; // 8:00 PM
+
+    if (timeInMinutes >= preMarketStart && timeInMinutes < regularMarketStart) {
+      return 'PRE';
+    } else if (timeInMinutes >= regularMarketStart && timeInMinutes < regularMarketEnd) {
+      return 'REGULAR';
+    } else if (timeInMinutes >= regularMarketEnd && timeInMinutes < afterHoursEnd) {
+      return 'POST';
+    } else {
+      return 'CLOSED';
+    }
+  }
+
+  /**
+   * Determine if intraday endpoint should be used based on market state
+   * Uses intraday for PRE, REGULAR, and POST market states
+   * Uses EOD for CLOSED state to save API credits
+   *
+   * @param marketState - Current market state
+   * @returns true if intraday endpoint should be used
+   */
+  private shouldUseIntradayEndpoint(marketState: 'PRE' | 'REGULAR' | 'POST' | 'CLOSED'): boolean {
+    return marketState !== 'CLOSED';
+  }
+
+  /**
+   * Format ticker symbol for intraday endpoints
+   * Marketstack intraday API requires periods to be replaced with hyphens
+   * Example: BRK.B → BRK-B
+   *
+   * @param symbol - Original ticker symbol
+   * @returns Formatted symbol for intraday endpoints
+   */
+  private formatSymbolForIntraday(symbol: string): string {
+    return symbol.replace(/\./g, '-');
+  }
 }