https://github.com/verdenroz/finance-query
Open-source API for financial data. Get quotes, historical data, technical indicators, and more.
https://github.com/verdenroz/finance-query
aws-apigateway aws-lambda docker fastapi google-finance python redis stocks websockets yahoo-finance
Last synced: about 2 months ago
JSON representation
Open-source API for financial data. Get quotes, historical data, technical indicators, and more.
- Host: GitHub
- URL: https://github.com/verdenroz/finance-query
- Owner: Verdenroz
- License: mit
- Created: 2024-04-07T00:08:39.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2026-01-12T12:10:43.000Z (5 months ago)
- Last Synced: 2026-01-12T19:36:21.840Z (5 months ago)
- Topics: aws-apigateway, aws-lambda, docker, fastapi, google-finance, python, redis, stocks, websockets, yahoo-finance
- Language: Rust
- Homepage: https://verdenroz.github.io/finance-query/
- Size: 6.94 MB
- Stars: 16
- Watchers: 1
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
Finance Query
[](https://crates.io/crates/finance-query)
[](https://docs.rs/finance-query)
[](https://github.com/Verdenroz/finance-query/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
Rust library, CLI, and HTTP server for querying financial data.
## Hosted API
Free hosted version at **[finance-query.com](https://finance-query.com)**:
```bash
# Get a quote
curl "https://finance-query.com/v2/quote/AAPL"
# Real-time streaming
wscat -c "wss://finance-query.com/v2/stream"
# GraphQL — interactive playground
open "https://finance-query.com/graphql"
# MCP — for AI agents (Claude, Cursor, Windsurf, etc.)
# Add to your MCP client config:
# { "url": "https://finance-query.com/mcp" }
```
## What's in This Repository
- **Library** (`finance-query`) - Core logic
- **CLI** (`finance-query-cli`) - Command-line tool for market data, technical analysis, and backtesting
- **Server** (`finance-query-server`) - HTTP REST API, WebSocket, and GraphQL server
- **MCP Server** (`finance-query-mcp`) - 36 MCP tools for AI agents (Claude, Cursor, Windsurf, etc.)
- **Derive Macros** (`finance-query-derive`) - Procedural macros for Polars DataFrame integration
## Quick Start
### Library
Add to your `Cargo.toml`:
```toml
[dependencies]
finance-query = "2.3"
# Or with additional features
finance-query = { version = "2.3", features = ["dataframe", "indicators", "fred", "crypto", "rss", "risk"] }
```
**Single symbol:**
```rust
use finance_query::Ticker;
#[tokio::main]
async fn main() -> Result<(), Box> {
let ticker = Ticker::builder("AAPL").logo().build().await?;
let quote = ticker.quote().await?;
if let Some(price) = quote.regular_market_price.as_ref().and_then(|v| v.raw) {
println!("AAPL: ${:.2}", price);
}
Ok(())
}
```
**Batch operations:**
```rust
use finance_query::{Tickers, Interval, TimeRange};
#[tokio::main]
async fn main() -> Result<(), Box> {
// Fetch quotes for multiple symbols in one request
let tickers = Tickers::builder(vec!["AAPL", "MSFT", "GOOGL"]).logo().build().await?;
let response = tickers.quotes().await?;
for (symbol, quote) in &response.quotes {
if let Some(price) = quote.regular_market_price.as_ref().and_then(|v| v.raw) {
println!("{}: ${:.2}", symbol, price);
}
}
Ok(())
}
```
**SEC EDGAR filings:**
```rust
use finance_query::edgar;
#[tokio::main]
async fn main() -> Result<(), Box> {
edgar::init("your.email@example.com")?;
// Resolve ticker to CIK
let cik = edgar::resolve_cik("AAPL").await?;
// Get filing history
let submissions = edgar::submissions(cik).await?;
if let Some(name) = &submissions.name {
println!("Company: {}", name);
}
// Get XBRL financial data
let facts = edgar::company_facts(cik).await?;
if let Some(us_gaap) = facts.facts.get("us-gaap") {
if let Some(revenue) = us_gaap.0.get("Revenues") {
if let Some(usd) = revenue.units.get("USD") {
for point in usd.iter().take(3) {
if let (Some(fy), Some(val)) = (point.fy, point.val) {
println!("FY {}: ${}", fy, val);
}
}
}
}
}
Ok(())
}
```
### CLI
Install `fq` (the command-line tool):
```bash
# Linux/macOS
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Verdenroz/finance-query/releases/latest/download/finance-query-cli-installer.sh | sh
# Windows
powershell -c "irm https://github.com/Verdenroz/finance-query/releases/latest/download/finance-query-cli-installer.ps1 | iex"
# From source
git clone https://github.com/Verdenroz/finance-query
cargo install --path finance-query/finance-query-cli
```
Quick examples:
```bash
fq quote AAPL MSFT GOOGL # Get quotes
fq stream AAPL TSLA NVDA # Live prices
fq chart AAPL -r 6mo # Interactive price chart
fq indicator AAPL --indicator rsi:14 # Technical indicators
fq backtest AAPL --preset swing # Strategy backtesting
fq dashboard # Market dashboard
fq alerts add AAPL price-above:200 # Price alerts with notifications
```
See [finance-query-cli/README.md](finance-query-cli/README.md) for full documentation.
### Server
Run the server locally (requires [Rust](https://rustup.rs/)):
```bash
git clone https://github.com/Verdenroz/finance-query.git
cd finance-query
make serve # Compiles and runs v2 server
```
Or run both v1 and v2 with Docker Compose:
```bash
make docker-compose # Starts v1 (port 8002), v2 (port 8001), Redis, and Nginx
```
The v2 server provides REST endpoints at `/v2/*` and WebSocket streaming at `/v2/stream`.
## Documentation
**Package guides:**
- [CLI](finance-query-cli/README.md) - Command-line tool with examples, installation, and features
- [Server](server/README.md) - REST API, WebSocket, and GraphQL server setup and endpoints
- [MCP Server](finance-query-mcp/README.md) - AI agent integration (36 tools, hosted at `finance-query.com/mcp`)
- [Derive Macros](finance-query-derive/README.md) - Procedural macros for Polars DataFrame support
**Full documentation at [verdenroz.github.io/finance-query](https://verdenroz.github.io/finance-query):**
- [Library Getting Started](https://verdenroz.github.io/finance-query/library/getting-started/)
- [Ticker API](https://verdenroz.github.io/finance-query/library/ticker/) - Single symbol operations
- [Tickers API](https://verdenroz.github.io/finance-query/library/tickers/) - Batch operations
- [EDGAR API](https://verdenroz.github.io/finance-query/library/edgar/) - SEC filings
- [Finance Module](https://verdenroz.github.io/finance-query/library/finance/) - Market-wide data
- [REST API Reference](https://verdenroz.github.io/finance-query/server/api-reference/)
- [WebSocket API](https://verdenroz.github.io/finance-query/server/websocket-api-reference/)
- [GraphQL API Reference](https://finance-query.com/graphql)
- [MCP Tools Reference](https://verdenroz.github.io/finance-query/server/mcp-reference/)
- [Contributing](https://verdenroz.github.io/finance-query/development/contributing/)
**API Documentation:**
- [Rust Docs](https://docs.rs/finance-query) - Library API on docs.rs
- [Crates.io](https://crates.io/crates/finance-query) - Published library
## Legacy Python Version (v1)
The original Python implementation is available in the [`v1/`](./v1/) directory. It is no longer actively maintained but remains available for reference.
## Contributing
We welcome contributions! See the [Contributing Guide](https://verdenroz.github.io/finance-query/development/contributing/) for setup instructions and development workflow.
```bash
make install-dev # Set up development environment
make test-fast # Run tests
make fix # Auto-fix formatting and linting
```
## Acknowledgements
This project relies on Yahoo Finance's publicly available data. We are grateful to Yahoo for providing this data.
Special thanks to [yfinance](https://github.com/ranaroussi/yfinance), the popular Python library that inspired this project. Many of the API patterns and data structures are adapted from yfinance's excellent work.
## License
MIT License - see [LICENSE](LICENSE) for details.