Findata Hub - Financial Data API Server

A comprehensive Node.js Express API server that serves financial data from Yahoo Finance and CoinStats. Features 26 REST endpoints for stocks, cryptocurrencies, market data, and more. Includes 5 MCP (Model Context Protocol) tools for LLM integration, supports multiple tickers in a single request with arrays as results and partial failure handling.

⚠️ Disclaimer

This is an unofficial implementation and has no affiliation with Yahoo Inc., CoinStats, or any of their subsidiaries. This project is not endorsed by, sponsored by, or otherwise connected to Yahoo or CoinStats. All data is sourced from public APIs through the yahoo-finance2 and CoinStats libraries.

🙏 Credits

Special thanks to the authors and maintainers of the yahoo-finance2 library for providing the Yahoo Finance API wrapper, and to CoinStats for their comprehensive cryptocurrency API.

Features

• 26 REST API Endpoints for stock quotes, cryptocurrencies, history, company info, search, market data, recommendations, insights, screeners, performance analysis, financial statements, news, holdings, events, statistics, and article content extraction
• Cryptocurrency Support - Real-time crypto data from CoinStats API with full filtering, sorting, and pagination
• 5 MCP Tools (Model Context Protocol) for LLM integration using official @modelcontextprotocol/sdk - see MCP.md for detailed documentation
• OpenAPI Client Compatibility - Full support for OpenAI function calling format via ?format=openai
• CORS Support - Cross-origin resource sharing enabled for web applications
• Multi-ticker support for quotes and historical data endpoints with partial failure handling
• Response caching with configurable TTL
• Rate limiting per IP address
• Comprehensive API logging with configurable levels (error, warn, info, debug)
• Docker multi-stage build with multi-architecture support (AMD64, ARM64, ARMv7)
• Health checks and proper error handling
• Jest tests with comprehensive coverage (173 tests across 20 test suites)
• Interactive API Documentation at /api-docs (Swagger UI)
• OpenAPI JSON Specification at /api-docs.json
• Modular architecture with separated concerns
• TypeScript - Fully typed codebase with strict TypeScript configuration

Quick Start

# Clone the repository
git clone https://github.com/caplaz/findata-hub.git
cd findata-hub

# Install dependencies
npm install

# Start the server
npm start

The server will be available at http://localhost:3000 with API docs at http://localhost:3000/api-docs.

API Endpoints

Core Endpoints

• GET /health - Health check
• GET /quote/:symbols - Current stock quotes (multi-ticker support)
• GET /history/:symbols - Historical price data (multi-ticker support)
• GET /search/:query - Symbol and news search
• GET /news-reader/* - Article content extraction

Cryptocurrency Endpoints

• GET /crypto/coins - Cryptocurrency list with full filtering, sorting, and pagination
• GET /crypto/coins/:coinId - Specific cryptocurrency data
• GET /crypto/market - Global cryptocurrency market statistics
• GET /crypto/insights/btc-dominance - Bitcoin dominance data over time
• GET /crypto/insights/fear-greed - Crypto Fear & Greed Index
• GET /crypto/insights/rainbow-chart/:coinId - Rainbow Chart technical analysis
• GET /crypto/news - Cryptocurrency news by type with pagination

Ticker Endpoints

• GET /ticker/:ticker - Company information
• GET /ticker/:ticker/insights - Comprehensive stock insights
• GET /ticker/:ticker/news - Company-specific news
• GET /ticker/:ticker/holdings - ETF/mutual fund holdings
• GET /ticker/:ticker/events - Calendar events, earnings, and earnings history
• GET /ticker/:ticker/statistics - Key statistics and financial data
• GET /ticker/:ticker/recommendations - Similar stock recommendations
• GET /ticker/:ticker/:type - Financial statements (income, balance, cashflow)

Market Data Endpoints

• GET /market/indices - Major market indices (S&P 500, Dow Jones, NASDAQ, Russell 2000, VIX)
• GET /market/summary - Comprehensive market overview (indices, trending, gainers/losers, news)
• GET /market/sectors - Sector performance via sector ETFs
• GET /market/currencies - Major currency exchange rates
• GET /market/commodities - Commodity prices (gold, oil, copper, etc.)
• GET /market/breadth - Market breadth indicators (advancers/decliners ratio)
• GET /market/sentiment - Market sentiment indicators (VIX, fear & greed index)
• GET /market/trending/:region - Regional trending symbols
• GET /market/screener/:type - Stock screeners (day_gainers, day_losers, most_actives)
• GET /market/news - General market news

MCP Endpoints

• POST /mcp - MCP protocol endpoint (official SDK transport)

For detailed API documentation, see the interactive Swagger UI or MCP.md for MCP integration details.

Installation

1. Clone the repository:

git clone https://github.com/caplaz/findata-hub.git
cd findata-hub

2. Install dependencies:

npm install

3. Start the server:

npm start

The server will be available at http://localhost:3000 with API docs at http://localhost:3000/api-docs.

Development

Running in Development Mode

npm run dev

This uses tsx to automatically restart the server when files change and provides TypeScript support without pre-compilation.

Building the Project

npm run build

This compiles TypeScript source files to JavaScript in the dist/ directory using the TypeScript compiler.

Running Tests

npm test

This runs the Jest test suite covering 173 test cases across 20 test files.

Environment Variables

Configure the server using environment variables:

Variable	Default	Description
PORT	3000	Server port
LOG_LEVEL	info	Logging level: error, warn, info, debug
CACHE_MODE	nodecache	Cache backend: nodecache, memcached, none
CACHE_HOST	localhost:11211	Memcached host:port (for memcached mode)
CACHE_TTL	300	Cache TTL in seconds (5 minutes)
RATE_LIMIT_WINDOW_MS	900000	Rate limit window in ms (15 minutes)
RATE_LIMIT_MAX	100	Max requests per window per IP
SWAGGER_SERVER_URL	http://localhost:3000	Base URL for Swagger API documentation
COINSTATS_API_KEY	demo-api-key	CoinStats API key for cryptocurrency data

Examples:

# Run with debug logging
LOG_LEVEL=debug npm start

# Run with custom rate limiting
RATE_LIMIT_MAX=200 RATE_LIMIT_WINDOW_MS=600000 npm start

# Run with cache disabled
CACHE_MODE=none npm start

# Run with memcached (default host)
CACHE_MODE=memcached npm start

# Run with custom memcached host
CACHE_MODE=memcached CACHE_HOST=memcached-server:11211 npm start

# Run on custom port with all custom settings
PORT=8080 LOG_LEVEL=debug CACHE_MODE=nodecache CACHE_TTL=600 npm start

# Run in Docker container (Docker Desktop)
SWAGGER_SERVER_URL=http://host.docker.internal:3000 npm start

# Run in Docker container (Linux)
SWAGGER_SERVER_URL=http://172.17.0.1:3000 npm start

# Run with CoinStats API key
COINSTATS_API_KEY=your-api-key-here npm start

Cryptocurrency API Setup

To use the cryptocurrency endpoints, you'll need a CoinStats API key:

1. Visit CoinStats API and sign up for an account
2. Get your API key from the dashboard
3. Set the COINSTATS_API_KEY environment variable or add it to your .env file

Example .env file:

COINSTATS_API_KEY=your-api-key-here

CORS (Cross-Origin Resource Sharing)

The API server includes CORS support to allow cross-origin requests from web applications. CORS is configured to allow requests from any origin, enabling integration with web applications hosted on different domains.

CORS Configuration:

• Allowed Origins: * (all origins)
• Allowed Methods: GET, POST, PUT, DELETE, OPTIONS
• Allowed Headers: Content-Type, Authorization, X-Requested-With
• Credentials: Supported

Example CORS Headers in Response:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With
Access-Control-Allow-Credentials: true

This allows web applications (like finance.caplaz.com) to make direct API calls to the Yahoo Finance Server without proxy requirements.

API Documentation

For detailed API documentation, see the interactive Swagger UI or OpenAPI JSON specification.

Releases

This project follows Semantic Versioning. Releases are automatically created when version tags (e.g., v2.0.0) are pushed to the repository.

Creating a Release

1. Update the version in package.json
2. Update CHANGELOG.md with the new changes
3. Commit the changes
4. Create and push a version tag:

git tag v2.0.0
git push origin v2.0.0

The CI/CD pipeline will automatically:

• Run tests
• Build and push Docker images to GitHub Packages
• Create a GitHub release

Changelog

See CHANGELOG.md for a detailed list of changes in each version.

License

Apache-2.0