Multi-Provider Architecture#

Finance Query v3 introduces a provider abstraction layer that lets you route each data capability (quotes, charts, fundamentals, etc.) to a different provider through a single builder API. The system automatically falls back to the next provider in the list on failure.

Why Multiple Providers?#

• Redundancy — if one provider fails or rate-limits you, the next one takes over
• Capability coverage — route each data type to the provider with the best coverage for it
• Flexibility — pick providers based on rate limits, data quality, and budget

Available Providers#

Yahoo Finance is always available with no configuration. All others are opt-in via feature flags:

[dependencies]
finance-query = { version = "3", features = ["polygon", "fmp"] }

Provider Initialization#

API keys are read from environment variables automatically during build(). No manual init calls are needed:

export POLYGON_API_KEY="your-polygon-key"
export FMP_API_KEY="your-fmp-key"
export ALPHAVANTAGE_API_KEY="your-av-key"
export FRED_API_KEY="your-fred-key"

Capability Routing#

Use .route(Capability, &[Provider]) on Providers::builder() to assign providers to specific data capabilities, then create handles via providers.ticker(). Providers are tried in order — the first success wins.

use finance_query::{Capability, Fetch, Provider, Providers};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let providers = Providers::builder()
        // Route quotes to Polygon first, Yahoo as fallback
        .route(Capability::QUOTE, [Provider::Polygon, Provider::Yahoo])
        // Route fundamentals to FMP first, Yahoo as fallback
        .route(Capability::FUNDAMENTALS, [Provider::Fmp, Provider::Yahoo])
        // Route corporate (news, recommendations) to Polygon only
        .route(Capability::CORPORATE, [Provider::Polygon])
        .fetch(Fetch::Sequential)
        .build()
        .await?;
    let ticker = providers.ticker("AAPL").build().await?;
    Ok(())
}

If no .route() is set for a capability, Yahoo Finance is used by default. EDGAR is auto-injected for FILINGS when no other provider is configured.

Available Capabilities#

Capabilities are bitflags — compose them with | and test membership with contains. This example runs as a real test, no network needed:

use finance_query::Capability;

let market_data = Capability::QUOTE | Capability::CHART;
assert!(market_data.contains(Capability::QUOTE));
assert!(market_data.contains(Capability::CHART));
assert!(!market_data.contains(Capability::OPTIONS));
assert_eq!(Capability::QUOTE.name(), "quote");
println!("market_data = {market_data:?}");
println!("QUOTE.name() = {:?}", Capability::QUOTE.name());

market_data = Capability(3)
QUOTE.name() = "quote"

Fetch Strategies#

Fetch controls how the provider list is queried:

Fetch and Provider are plain enums — constructing them never touches the network:

use finance_query::{Fetch, Provider};

let strategy = Fetch::Sequential;
assert_eq!(strategy, Fetch::Sequential);
assert_ne!(Fetch::Parallel, Fetch::Sequential);

// Yahoo is the default provider; EDGAR is likewise always compiled in.
assert_eq!(Provider::default(), Provider::Yahoo);
assert_eq!(Provider::Edgar.as_str(), "edgar");
println!("default provider = {:?}", Provider::default());
println!("Edgar.as_str()   = {:?}", Provider::Edgar.as_str());

default provider = Yahoo
Edgar.as_str()   = "edgar"

use finance_query::{Capability, Fetch, Provider, Providers};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Sequential: try Polygon, then Yahoo if Polygon fails
    let providers = Providers::builder()
        .route(Capability::QUOTE, [Provider::Polygon, Provider::Yahoo])
        .fetch(Fetch::Sequential)
        .build()
        .await?;
    let ticker = providers.ticker("AAPL").build().await?;

    // Parallel: race Polygon against Yahoo, use whichever responds first
    let providers = Providers::builder()
        .route(Capability::QUOTE, [Provider::Polygon, Provider::Yahoo])
        .fetch(Fetch::Parallel)
        .build()
        .await?;
    let ticker = providers.ticker("AAPL").build().await?;
    Ok(())
}

Provider Capabilities Matrix#

Capabilities supported by each provider. Providers that don't support a given capability are automatically skipped during dispatch.

• Capability dispatch over a full provider registry is branch-few bitflag filtering: selecting the providers for a request makes zero allocations and completes in single-digit nanoseconds — routing adds no measurable overhead to any call.

This table is printed by the program below rather than maintained by hand, so it cannot fall behind Provider::capabilities().

use finance_query::{Capability, Provider};

println!("| Provider | Capabilities |");
println!("|----------|--------------|");
for provider in Provider::all() {
    let declared: Vec<&str> = Capability::all()
        .filter(|c| provider.capabilities().contains(*c))
        .map(Capability::name)
        .collect();
    let declared = match declared.is_empty() {
        true => "none".to_string(),
        false => declared.join(", "),
    };
    println!("| `{}` | {declared} |", provider.as_str());
}

| Provider | Capabilities |
|----------|--------------|
| `yahoo` | quote, chart, fundamentals, corporate, options, discovery, calendar, market, indices, futures, commodities |
| `polygon` | quote, chart, fundamentals, corporate, options, discovery, crypto, economic, calendar, forex, indices, futures, filings |
| `fmp` | quote, chart, fundamentals, corporate, discovery, crypto, calendar, market, forex, indices, commodities, filings |
| `alphavantage` | quote, chart, fundamentals, corporate, options, discovery, crypto, economic, calendar, market, forex, commodities, filings |
| `coingecko` | chart, discovery, crypto |
| `fred` | economic, calendar |
| `worldbank` | economic |
| `fiscaldata` | economic |
| `bls` | economic |
| `frankfurter` | forex |
| `binance` | chart, crypto |
| `kraken` | chart, crypto |
| `finra` | fundamentals |
| `defillama` | crypto |
| `gdelt` | corporate, crypto, forex |
| `cftc` | futures |
| `nasdaq` | calendar |
| `wikipedia` | indices |
| `congresstrades` | filings |
| `edgar` | corporate, discovery, filings |
| `local_market_calendar` | calendar |
| `local_exchange` | discovery |

Providers Factory (Shared Connections)#

For non-equity asset classes, use the Providers factory to create domain handles that share the same provider connections and configuration:

use finance_query::{Capability, Fetch, Provider, Providers};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let providers = Providers::builder()
        .route(Capability::FOREX, [Provider::AlphaVantage])
        .route(Capability::ECONOMIC, [Provider::Fred])
        .route(Capability::CRYPTO, [Provider::CoinGecko])
        .fetch(Fetch::Sequential)
        .build()
        .await?;

    // All handles share the same provider connections
    let aapl  = providers.ticker("AAPL").logo().build().await?;   // → Ticker
    let pair  = providers.forex("USD", "EUR");                    // → ForexPair
    let btc   = providers.crypto("bitcoin");                      // → CryptoCoin
    let gdp   = providers.economic("REAL_GDP");                   // → EconomicIndicator
    let spy   = providers.index("SPY");                           // → Index
    let cl    = providers.futures("CL=F");                        // → FuturesContract
    let wheat = providers.commodity("WHEAT");                     // → Commodity
    let sec   = providers.filings("AAPL");                        // → Filings
    Ok(())
}

Four handles are market-wide rather than symbol-scoped, so their factories take no argument. market() and snapshot() are always available (movers are served keylessly from Yahoo's screeners); discovery() and calendar() require at least one of the fmp, polygon, or alphavantage features:

let disco = providers.discovery();   // → Discovery: symbol search, reference data, screeners
let cal   = providers.calendar();    // → MarketCalendar: earnings/IPO/dividend/split/economic calendars
let mkt   = providers.market();      // → Market: sector performance, movers
let snap  = providers.snapshot();    // → Snapshot: cross-market watchlist snapshots
let cat   = providers.economic_catalog(); // → EconomicCatalog: find macro series (needs fred/alphavantage/polygon)

Domain Handle Methods#

Snapshot::get takes provider-spelled symbols from any market in one list ("AAPL", "X:BTCUSD", "I:SPX", "C:EURUSD", "O:NCLH221014C00005000") and answers them in a single request — one rate-limit unit instead of one per asset class. Symbols the provider cannot resolve come back as rows with error set, so the result stays aligned with the request. Polygon (max 250 symbols) is currently the only provider whose snapshot endpoint spans markets.

All chart-capable handles route through Capability::CHART (Yahoo by default) and cache per (symbol, interval, range) when .cache(ttl) is set. history(range) is sugar for chart(range.default_interval(), range). The handle's identifier is passed to the chart route as-is, so it must be a chart-route symbol (e.g. ^GSPC, NQ=F, GC=F); CryptoCoin builds "{ID}-{VS}" (e.g. "BTC-USD"), which resolves on Yahoo only for ticker-style ids.

Technical Indicators & Risk on Domain Handles#

With the indicators / risk features, every chart-capable handle also exposes the same analytics as Ticker, computed over its cached chart:

CryptoCoin takes a leading vs_currency argument on all three (e.g. coin.indicator(Indicator::Rsi(14), "USD", interval, range)), matching its chart().

risk() annualizes with the handle's asset-class trading calendar — 252 days for exchange-traded (index/futures/commodity), ~260 for forex, 365 for crypto (24/7) — and intraday intervals scale by session length, so Sharpe/Sortino/Calmar are correct across asset classes and intervals. beta is always None on domain handles (no benchmark is fetched).

Tickers and Providers#

Tickers supports the same multi-provider configuration as Ticker. Routing is configured through Providers::builder() and passed to Tickers via providers.tickers():

use finance_query::{Capability, Fetch, Provider, Providers};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let providers = Providers::builder()
        .route(Capability::QUOTE, [Provider::Polygon, Provider::Yahoo])
        .fetch(Fetch::Sequential)
        .build()
        .await?;
    let tickers = providers.tickers(["AAPL", "NVDA"]).build().await?;
    Ok(())
}

Provider Pages#