
finance-query
io.github.Verdenroz/finance-query
Stock quotes, charts, financials, options, SEC filings, crypto and macro data. Hosted, no API key.
Documentation
Finance Query
Rust library, CLI, and HTTP server for querying financial data.
Hosted API
Free hosted version at finance-query.com:
# 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 - 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:
[dependencies]
finance-query = "3"
# Or with additional features
finance-query = { version = "3", features = ["dataframe", "indicators", "fred", "crypto", "risk", "translation"] }
Single symbol:
use finance_query::Ticker;
use finance_query::format::Both;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let ticker = Ticker::builder("AAPL").logo().build().await?;
let quote = ticker.quote::<Both>().await?;
if let Some(price) = quote.regular_market_price.as_ref().and_then(|v| v.raw) {
println!("AAPL: ${:.2}", price);
}
Ok(())
}
Batch operations:
use finance_query::{Tickers, Interval, TimeRange};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// 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:
use finance_query::edgar;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
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")
&& let Some(revenue) = us_gaap.0.get("Revenues")
&& 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
fq (the command-line tool) lives in its own repository: Verdenroz/fq-cli.
# Linux/macOS
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Verdenroz/fq-cli/releases/latest/download/fq-cli-installer.sh | sh
# Windows
powershell -c "irm https://github.com/Verdenroz/fq-cli/releases/latest/download/fq-cli-installer.ps1 | iex"
Quick examples:
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 Verdenroz/fq-cli for full documentation.
Server
Run the server locally (requires Rust):
git clone https://github.com/Verdenroz/finance-query.git
cd finance-query
make serve # Compiles and runs v2 server
Or run the full stack with Docker Compose:
docker compose up -d # Starts v1 (port 8002), v2 (port 8001), Redis, Caddy, and the full monitoring stack
The v2 server provides REST endpoints at /v2/* and WebSocket streaming at /v2/stream.
Documentation
Package guides:
- CLI - Command-line tool with examples, installation, and features
- Server - REST API, WebSocket, and GraphQL server setup and endpoints
- MCP Server - AI agent integration (36 tools, hosted at
finance-query.com/mcp) - Derive Macros - Procedural macros for Polars DataFrame support
Full documentation at verdenroz.github.io/finance-query:
- Library Getting Started
- Ticker API - Single symbol operations
- Tickers API - Batch operations
- EDGAR API - SEC filings
- Finance Module - Market-wide data
- REST API Reference
- WebSocket API
- GraphQL API Reference
- MCP Tools Reference
- Contributing
API Documentation:
Legacy Python Version (v1)
The original Python implementation is available in the v1/ directory. It is no longer actively maintained but remains available for reference.
Contributing
We welcome contributions! See the Contributing Guide for setup instructions and development workflow.
make install-dev # Set up development environment
make test # Test what changed, skipping cached passes
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, 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 for details.
No installation packages available.