@fin.cx/opendata 3.2.2 → 3.3.0

package/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:

package/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

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '3.2.2',
+  version: '3.3.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.'
 }

package/ts/stocks/index.ts

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