{"id":23622328,"url":"https://github.com/verdenroz/finance-query","last_synced_at":"2026-05-07T01:14:05.926Z","repository":{"id":233068662,"uuid":"783100934","full_name":"Verdenroz/finance-query","owner":"Verdenroz","description":"Open-source API for financial data. Get quotes, historical data, technical indicators, and more.","archived":false,"fork":false,"pushed_at":"2026-01-12T12:10:43.000Z","size":7272,"stargazers_count":16,"open_issues_count":2,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-12T19:36:21.840Z","etag":null,"topics":["aws-apigateway","aws-lambda","docker","fastapi","google-finance","python","redis","stocks","websockets","yahoo-finance"],"latest_commit_sha":null,"homepage":"https://verdenroz.github.io/finance-query/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Verdenroz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-04-07T00:08:39.000Z","updated_at":"2025-12-31T20:37:47.000Z","dependencies_parsed_at":"2024-05-21T13:13:14.284Z","dependency_job_id":"180608c5-448d-4dfd-80a0-fbb73778e85f","html_url":"https://github.com/Verdenroz/finance-query","commit_stats":null,"previous_names":["verdenroz/financeapi","verdenroz/financequery","verdenroz/finance-query"],"tags_count":63,"template":false,"template_full_name":null,"purl":"pkg:github/Verdenroz/finance-query","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Verdenroz%2Ffinance-query","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Verdenroz%2Ffinance-query/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Verdenroz%2Ffinance-query/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Verdenroz%2Ffinance-query/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Verdenroz","download_url":"https://codeload.github.com/Verdenroz/finance-query/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Verdenroz%2Ffinance-query/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477210,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T03:13:13.607Z","status":"ssl_error","status_checked_at":"2026-01-16T03:11:47.863Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-apigateway","aws-lambda","docker","fastapi","google-finance","python","redis","stocks","websockets","yahoo-finance"],"created_at":"2024-12-27T20:17:58.979Z","updated_at":"2026-05-02T22:02:52.091Z","avatar_url":"https://github.com/Verdenroz.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eFinance Query\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/logo.png\" alt=\"FinanceQuery\" width=\"187\" style=\"background:white; border-radius:8px; padding:8px;\"\u003e\n\u003c/p\u003e\n\n[![Crates.io](https://img.shields.io/crates/v/finance-query.svg)](https://crates.io/crates/finance-query)\n[![Documentation](https://docs.rs/finance-query/badge.svg)](https://docs.rs/finance-query)\n[![CI](https://github.com/Verdenroz/finance-query/actions/workflows/ci.yml/badge.svg)](https://github.com/Verdenroz/finance-query/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nRust library, CLI, and HTTP server for querying financial data.\n\n## Hosted API\n\nFree hosted version at **[finance-query.com](https://finance-query.com)**:\n\n```bash\n# Get a quote\ncurl \"https://finance-query.com/v2/quote/AAPL\"\n\n# Real-time streaming\nwscat -c \"wss://finance-query.com/v2/stream\"\n\n# GraphQL — interactive playground\nopen \"https://finance-query.com/graphql\"\n\n# MCP — for AI agents (Claude, Cursor, Windsurf, etc.)\n# Add to your MCP client config:\n# { \"url\": \"https://finance-query.com/mcp\" }\n```\n\n## What's in This Repository\n\n- **Library** (`finance-query`) - Core logic\n- **CLI** (`finance-query-cli`) - Command-line tool for market data, technical analysis, and backtesting\n- **Server** (`finance-query-server`) - HTTP REST API, WebSocket, and GraphQL server\n- **MCP Server** (`finance-query-mcp`) - 36 MCP tools for AI agents (Claude, Cursor, Windsurf, etc.)\n- **Derive Macros** (`finance-query-derive`) - Procedural macros for Polars DataFrame integration\n\n## Quick Start\n\n### Library\n\nAdd to your `Cargo.toml`:\n\n```toml\n[dependencies]\nfinance-query = \"2.3\"\n\n# Or with additional features\nfinance-query = { version = \"2.3\", features = [\"dataframe\", \"indicators\", \"fred\", \"crypto\", \"rss\", \"risk\"] }\n```\n\n**Single symbol:**\n\n```rust\nuse finance_query::Ticker;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let ticker = Ticker::builder(\"AAPL\").logo().build().await?;\n    let quote = ticker.quote().await?;\n\n    if let Some(price) = quote.regular_market_price.as_ref().and_then(|v| v.raw) {\n        println!(\"AAPL: ${:.2}\", price);\n    }\n    Ok(())\n}\n```\n\n**Batch operations:**\n\n```rust\nuse finance_query::{Tickers, Interval, TimeRange};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // Fetch quotes for multiple symbols in one request\n    let tickers = Tickers::builder(vec![\"AAPL\", \"MSFT\", \"GOOGL\"]).logo().build().await?;\n    let response = tickers.quotes().await?;\n\n    for (symbol, quote) in \u0026response.quotes {\n        if let Some(price) = quote.regular_market_price.as_ref().and_then(|v| v.raw) {\n            println!(\"{}: ${:.2}\", symbol, price);\n        }\n    }\n    Ok(())\n}\n```\n\n**SEC EDGAR filings:**\n\n```rust\nuse finance_query::edgar;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    edgar::init(\"your.email@example.com\")?;\n\n    // Resolve ticker to CIK\n    let cik = edgar::resolve_cik(\"AAPL\").await?;\n\n    // Get filing history\n    let submissions = edgar::submissions(cik).await?;\n    if let Some(name) = \u0026submissions.name {\n        println!(\"Company: {}\", name);\n    }\n\n    // Get XBRL financial data\n    let facts = edgar::company_facts(cik).await?;\n    if let Some(us_gaap) = facts.facts.get(\"us-gaap\") {\n        if let Some(revenue) = us_gaap.0.get(\"Revenues\") {\n            if let Some(usd) = revenue.units.get(\"USD\") {\n                for point in usd.iter().take(3) {\n                    if let (Some(fy), Some(val)) = (point.fy, point.val) {\n                        println!(\"FY {}: ${}\", fy, val);\n                    }\n                }\n            }\n        }\n    }\n    Ok(())\n}\n```\n\n### CLI\n\nInstall `fq` (the command-line tool):\n\n```bash\n# Linux/macOS\ncurl --proto '=https' --tlsv1.2 -LsSf https://github.com/Verdenroz/finance-query/releases/latest/download/finance-query-cli-installer.sh | sh\n\n# Windows\npowershell -c \"irm https://github.com/Verdenroz/finance-query/releases/latest/download/finance-query-cli-installer.ps1 | iex\"\n\n# From source\ngit clone https://github.com/Verdenroz/finance-query\ncargo install --path finance-query/finance-query-cli\n```\n\nQuick examples:\n\n```bash\nfq quote AAPL MSFT GOOGL          # Get quotes\nfq stream AAPL TSLA NVDA          # Live prices\nfq chart AAPL -r 6mo              # Interactive price chart\nfq indicator AAPL --indicator rsi:14  # Technical indicators\nfq backtest AAPL --preset swing   # Strategy backtesting\nfq dashboard                      # Market dashboard\nfq alerts add AAPL price-above:200  # Price alerts with notifications\n```\n\nSee [finance-query-cli/README.md](finance-query-cli/README.md) for full documentation.\n\n### Server\n\nRun the server locally (requires [Rust](https://rustup.rs/)):\n\n```bash\ngit clone https://github.com/Verdenroz/finance-query.git\ncd finance-query\nmake serve  # Compiles and runs v2 server\n```\n\nOr run both v1 and v2 with Docker Compose:\n\n```bash\nmake docker-compose  # Starts v1 (port 8002), v2 (port 8001), Redis, and Nginx\n```\n\nThe v2 server provides REST endpoints at `/v2/*` and WebSocket streaming at `/v2/stream`.\n\n## Documentation\n\n**Package guides:**\n\n- [CLI](finance-query-cli/README.md) - Command-line tool with examples, installation, and features\n- [Server](server/README.md) - REST API, WebSocket, and GraphQL server setup and endpoints\n- [MCP Server](finance-query-mcp/README.md) - AI agent integration (36 tools, hosted at `finance-query.com/mcp`)\n- [Derive Macros](finance-query-derive/README.md) - Procedural macros for Polars DataFrame support\n\n**Full documentation at [verdenroz.github.io/finance-query](https://verdenroz.github.io/finance-query):**\n\n- [Library Getting Started](https://verdenroz.github.io/finance-query/library/getting-started/)\n- [Ticker API](https://verdenroz.github.io/finance-query/library/ticker/) - Single symbol operations\n- [Tickers API](https://verdenroz.github.io/finance-query/library/tickers/) - Batch operations\n- [EDGAR API](https://verdenroz.github.io/finance-query/library/edgar/) - SEC filings\n- [Finance Module](https://verdenroz.github.io/finance-query/library/finance/) - Market-wide data\n- [REST API Reference](https://verdenroz.github.io/finance-query/server/api-reference/)\n- [WebSocket API](https://verdenroz.github.io/finance-query/server/websocket-api-reference/)\n- [GraphQL API Reference](https://finance-query.com/graphql)\n- [MCP Tools Reference](https://verdenroz.github.io/finance-query/server/mcp-reference/)\n- [Contributing](https://verdenroz.github.io/finance-query/development/contributing/)\n\n**API Documentation:**\n\n- [Rust Docs](https://docs.rs/finance-query) - Library API on docs.rs\n- [Crates.io](https://crates.io/crates/finance-query) - Published library\n\n## Legacy Python Version (v1)\n\nThe original Python implementation is available in the [`v1/`](./v1/) directory. It is no longer actively maintained but remains available for reference.\n\n## Contributing\n\nWe welcome contributions! See the [Contributing Guide](https://verdenroz.github.io/finance-query/development/contributing/) for setup instructions and development workflow.\n\n```bash\nmake install-dev  # Set up development environment\nmake test-fast    # Run tests\nmake fix          # Auto-fix formatting and linting\n```\n\n## Acknowledgements\n\nThis project relies on Yahoo Finance's publicly available data. We are grateful to Yahoo for providing this data.\n\nSpecial 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.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverdenroz%2Ffinance-query","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fverdenroz%2Ffinance-query","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverdenroz%2Ffinance-query/lists"}