feat(stocks/CoinGeckoProvider): Add CoinGecko provider for cryptocurrency prices, export and tests, and update documentation

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: