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
• 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:

[dependencies]
finance-query = "2.3"

# Or with additional features
finance-query = { version = "2.3", features = ["dataframe", "indicators", "fred", "crypto", "rss", "risk"] }

Single symbol:

use finance_query::Ticker;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    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:

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") {
        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):

# 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:

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 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 both v1 and v2 with Docker Compose:

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

• Rust Docs - Library API on docs.rs
• Crates.io - Published library

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-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, 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.