Finance Toolkit
This server exposes the Finance Toolkit MCP API for querying financial data and calculating analytics across markets, companies, funds, options, macroeconomics, and portfolios.
Retrieve raw financial data: prices, statements, profiles, quotes, analyst estimates, dividends, ownership, insider trades, and transcripts.
Calculate pre-computed ratios: efficiency, liquidity, profitability, solvency, and valuation, with growth, trailing/TTM, quarterly/annual, and standardization options.
Run financial models: WACC, DuPont, DCF/intrinsic value, distress/manipulation scores, credit/default models, and quality/valuation screens.
Analyze technical indicators: momentum, moving averages/overlap, volatility, breadth, signals, and candlestick patterns.
Measure performance and risk: returns, Sharpe, beta, alpha, CAPM/Fama-French, VaR/CVaR, drawdowns, GARCH, tail risk, and copulas.
Perform econometrics: regressions, causality, time-series forecasts, cointegration, VAR/ARIMA, regime switching, and pairs trading.
Analyze ETFs and portfolios: holdings, overlap, tracking, optimization, risk contributions, stress tests, attribution, and portfolio tracking.
Price options and analyze option markets: Black-Scholes/binomial, Greeks, chains, implied volatility, max pain, and gamma exposure.
Query macroeconomic and fixed-income data: inflation, GDP, jobs, government finance, rates, yield curves, bonds, ESG/climate, and commodities.
Discover markets and metrics: screeners, calendars, index constituents, industry statistics, news, and search tools for finding the right metric/tool.
Allows GitHub Copilot to query financial statements, ratios, and market data using the FinanceToolkit MCP server.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
While browsing a variety of websites, I repeatedly observed significant fluctuations in the same financial metric among different sources. Similarly, the reported financial statements often didn't line up, and there was limited information on the methodology used to calculate each metric.
For example, Microsoft's Price-to-Earnings (PE) ratio on the 6th of May, 2023 is reported to be 28.93 (Stockopedia), 32.05 (Morningstar), 32.66 (Macrotrends), 33.09 (Finance Charts), 33.66 (Y Charts), 33.67 (Wall Street Journal), 33.80 (Yahoo Finance) and 34.4 (Companies Market Cap). All of these calculations are correct, however the method of calculation varies leading to different results. Therefore, collecting data from multiple sources can lead to wrong interpretation of the results given that one source could apply a different definition than another. And that is, if that definition is even available as often the underlying methods are hidden behind a paid subscription.
This is why I designed the FinanceToolkit, this is an open-source toolkit in which all relevant financial methods (500+) are written down in the most simplistic way allowing for complete transparency of the method of calculation (proof). This enables you to avoid dependence on metrics from other providers that do not provide their methods. With a large selection of financial statements in hand, it facilitates streamlined calculations, promoting the adoption of a consistent and universally understood methods and formulas.
Beyond Equities, it supports Options, Currencies, Cryptocurrencies, ETFs, Mutual Funds, Indices, Money Markets, Commodities, Key Economic Indicators and more, allowing you to obtain historical data as well as important performance and risk measurements such as the Sharpe Ratio and Value at Risk.
Complementing this is the Finance Database 🌎, a database featuring 300.000+ symbols containing Equities, ETFs, Funds, Indices, Currencies, Cryptocurrencies and Money Markets. By utilising both, it is possible to do a fully-fledged competitive analysis with the tickers found from the FinanceDatabase inputted into the FinanceToolkit.
🔌 The Finance Toolkit is also available as an MCP Server
Query 500+ methods from Claude, Copilot, Cursor, Windsurf or any MCP-compatible client without writing code.
Hosted: connect to
https://financetoolkit.jeroenbouma.com/mcp— OAuth handles the rest on first use.Local:
uvx --from "financetoolkit[mcp]" financetoolkit-mcp-setup— sets up your client config and API key automatically. See MCP Server Documentation for manual setup.
Also on Smithery, Glama, MCP Servers and more.
Table of Contents
Installation
Before installation, consider starring the project on GitHub which helps others find the project as well.
To install the Finance Toolkit it simply requires the following:
pip install financetoolkit -UThen within Python use:
from financetoolkit import Toolkit
companies = Toolkit(
tickers=['AAPL', 'MSFT'],
api_key="FINANCIAL_MODELING_PREP_KEY", # replace with your actual API key
)To be able to get started, you need to obtain an API Key from FinancialModelingPrep. This is used to gain access to 30+ years of financial statement both annually and quarterly. Note that the Free plan is limited to 250 requests each day, 5 years of data and only features companies listed on US exchanges.
Obtain an API Key from FinancialModelingPrep here.
Through the link you are able to subscribe for the free plan and also premium plans at a 15% discount. This is an affiliate link and thus supports the project at the same time. I have chosen FinancialModelingPrep as a source as I find it to be the most transparent, reliable and at an affordable price. I have yet to find a platform offering such low prices for the amount of data offered. When you notice that the data is inaccurate or have any other issue related to the data, note that I simply provide the means to access this data and I am not responsible for the accuracy of the data itself. For this, use their contact form or provide the data yourself.
By default, the Finance Toolkit prioritizes Financial Modeling Prep for data retrieval. If data acquisition from Financial Modeling Prep is unsuccessful (e.g., due to plan restrictions or API key issues), the toolkit automatically switches to Yahoo Finance as a secondary source. To disable this fallback behavior and exclusively use Financial Modeling Prep, set enforce_source="FinancialModelingPrep" during Toolkit initialization. This configuration ensures that an error is raised if Financial Modeling Prep data cannot be accessed. Alternatively, you can set enforce_source="YahooFinance" to exclusively use Yahoo Finance as the data source.
The same enforce_source argument is also accepted per call on get_historical_data, get_treasury_data and the four statement functions (get_balance_sheet_statement, get_income_statement, get_cash_flow_statement and get_statistics_statement), where it overrides whatever the Toolkit was initialised with.
Functionality
This section is an introduction to the Finance Toolkit. The documentation contains many more examples: every module page opens with a Getting Started section, from the basics to creating custom ratios and working with your own datasets.
Find the Documentation, including the Getting Started guides, here.
The sections below follow one analysis of the semiconductor sector from start to finish, where each step answers the question the previous one raises: which companies make up the sector, how their shares did, what drives their profits, how much risk came with the returns, what the option market expects next, how the economy shaped all of it, whether a fund is the better way in and how the sector fits into a diversified portfolio. Every module of the Finance Toolkit appears once, but each holds far more than shown here: 500+ methods in total, all described with examples in the documentation.
Discovering the Sector
An analysis starts with a set of companies. The Discovery module finds them without needing any tickers yet, through stock screeners, sector performance, news and lists of companies, ETFs, indices, currencies, cryptocurrencies and commodities.
The screener below looks for semiconductor companies on NASDAQ that are worth more than $100 billion:
from financetoolkit import Discovery
# Initialize the standalone Discovery module
discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")
# Find US semiconductor companies worth more than $100 billion
semiconductors = discovery.get_stock_screener(
industry="Semiconductors",
country="US",
exchange="NASDAQ",
market_cap_higher=100_000_000_000,
is_etf=False,
)
# Show the five largest
semiconductors[["Name", "Market Cap", "Beta", "Price", "Dividend"]].head()For example, the five largest companies the screener returns are shown below.
Symbol | Name | Market Cap | Beta | Price | Dividend |
NVDA | NVIDIA Corporation | 5084136000000 | 2.216 | 210.96 | 0.28 |
AVGO | Broadcom Inc. | 1535581254973 | 1.476 | 321.68 | 2.6 |
MU | Micron Technology, Inc. | 992877621000 | 2.226 | 877.55 | 0.565 |
AMD | Advanced Micro Devices, Inc. | 843646776955 | 2.454 | 516.79 | 0 |
INTC | Intel Corp. | 459679713584 | 2.23 | 86.96 | 0 |
And below all of them are ranked by market cap.
Related MCP server: crypto-quant-signal-mcp
Following the Market
The rest of this walkthrough follows three of them: Nvidia, AMD and Intel. They are loaded into the Toolkit in one line, and the S&P 500 comes along as the benchmark:
from financetoolkit import Toolkit
# Initialize the Toolkit for Nvidia, AMD and Intel from 2018 to 2025
companies = Toolkit(
["NVDA", "AMD", "INTC"],
api_key="FINANCIAL_MODELING_PREP_KEY",
start_date="2017-12-31",
end_date="2025-12-31",
)Historical data comes on a daily, weekly, monthly, quarterly or yearly basis, with the return and cumulative return of each period, and so do the income statement, balance sheet and cash flow statement on an annual or quarterly basis. How far a share has travelled is one thing; whether the rally was stretched is another. The technicals module answers that with 50+ indicators, such as the Relative Strength Index (RSI), which moves between 0 and 100 and is commonly read as overbought above 70:
# Obtain weekly market data for all tickers and the benchmark
historical_data = companies.get_historical_data(period="weekly")
# The 14-week Relative Strength Index
relative_strength_index = companies.technicals.get_relative_strength_index(period="weekly", window=14)
# Show the highest RSI of each year
relative_strength_index.groupby(relative_strength_index.index.start_time.year).max()For example, the highest weekly RSI of each year is shown below.
Date | NVDA | AMD | INTC | Benchmark |
2018 | 66.1087 | 90.9719 | 66.7363 | 66.0498 |
2019 | 73.8156 | 81.2446 | 69.8225 | 75.9305 |
2020 | 85.2337 | 82.1215 | 78.4827 | 80.2378 |
2021 | 85.1593 | 82.0983 | 71.5862 | 74.4751 |
2022 | 58.4343 | 58.9426 | 61.2806 | 59.9225 |
2023 | 87.5129 | 77.506 | 76.2332 | 71.4291 |
2024 | 91.0702 | 82.1403 | 67.6949 | 80.0566 |
2025 | 73.3514 | 82.5281 | 79.7429 | 71.6939 |
And below the cumulative returns of all three are plotted against the S&P 500, with the RSI underneath.
Zooming in on Competitors
Nvidia's shares outran the other two by far, which raises the question whether its business did as well. From the financial statements the Toolkit calculates 80+ ratios in five categories: efficiency, liquidity, profitability, solvency and valuation. Each ratio has its own function, and a collect_ function returns a whole category at once:
# Collect all Profitability Ratios for all tickers
profitability_ratios = companies.ratios.collect_profitability_ratios()
# Show the first ratios for Nvidia
profitability_ratios.loc["NVDA"].head()For example, some of Nvidia's profitability ratios are shown below.
2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | 2025 | |
Gross Margin | 0.5993 | 0.6121 | 0.6199 | 0.6234 | 0.6493 | 0.5693 | 0.7272 | 0.7499 | 0.7107 |
Operating Margin | 0.3305 | 0.3247 | 0.2607 | 0.2718 | 0.3731 | 0.1566 | 0.5412 | 0.6242 | 0.6038 |
Net Profit Margin | 0.3137 | 0.3534 | 0.2561 | 0.2598 | 0.3623 | 0.1619 | 0.4885 | 0.5585 | 0.556 |
EBITDA Margin | 0.3509 | 0.347 | 0.2956 | 0.3376 | 0.4167 | 0.2138 | 0.566 | 0.6385 | 0.617 |
Free Cash Flow Margin | 0.2995 | 0.2683 | 0.3913 | 0.2815 | 0.3021 | 0.1412 | 0.4435 | 0.4663 | 0.4477 |
And below a few of them are shown with their latest value and their course over the years.
A high return on equity can come from margins, from turnover or from debt. Models combine the ratios to tell these apart: the Extended DuPont Analysis splits the return on equity into five components that multiply into it: interest burden, tax burden, operating margin, asset turnover and equity multiplier.
# Get the Extended DuPont Analysis for all tickers
extended_dupont_analysis = companies.models.get_extended_dupont_analysis()
# Show the results for Nvidia
extended_dupont_analysis.loc["NVDA"]For example, the components for Nvidia are shown below.
2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | 2025 | |
Interest Burden Ratio | 0.9956 | 1.0242 | 1.0436 | 0.9729 | 0.99 | 0.9898 | 1.0257 | 1.0316 | 1.0848 |
Tax Burden Ratio | 0.9534 | 1.0629 | 0.9414 | 0.9825 | 0.981 | 1.0447 | 0.88 | 0.8674 | 0.8488 |
Operating Profit Margin | 0.3305 | 0.3247 | 0.2607 | 0.2718 | 0.3731 | 0.1566 | 0.5412 | 0.6242 | 0.6038 |
Asset Turnover | 0.9215 | 0.9551 | 0.7134 | 0.7233 | 0.7376 | 0.6319 | 1.1397 | 1.4718 | 1.3564 |
Equity Multiplier | 1.5931 | 1.4592 | 1.4205 | 1.5846 | 1.6775 | 1.7525 | 1.6428 | 1.4499 | 1.3456 |
Return on Equity | 0.4605 | 0.4926 | 0.2595 | 0.2978 | 0.4483 | 0.1793 | 0.9146 | 1.1918 | 1.0149 |
And below each component is shown for every fiscal year, with the latest value on top, multiplying into the return on equity.
Other models include the Weighted Average Cost of Capital, Altman Z-Score, Piotroski F-Score and Intrinsic Valuation. Almost every function also accepts growth=True for the growth from one period to the next, trailing=4 for trailing twelve-month figures and standardize=True for Z-Scores.
Weighing Risk and Return
Strong businesses do not make for smooth shares. The market data feeds the performance and risk modules, which calculate their metrics for any period, from intraday to yearly:
# The annualized Sharpe Ratio for each year
sharpe_ratio = companies.performance.get_sharpe_ratio(period="yearly", annualize=True)
# The deepest fall within each year
maximum_drawdown = companies.risk.get_maximum_drawdown(period="yearly", within_period=True)
# Show the Sharpe Ratios
sharpe_ratioFor example, the yearly Sharpe Ratios are shown below.
Date | NVDA | AMD | INTC |
2018 | -0.613 | 1.1009 | 0.161 |
2019 | 1.5458 | 1.9143 | 1.048 |
2020 | 1.656 | 1.419 | -0.0445 |
2021 | 2.0003 | 1.2366 | 0.2976 |
2022 | -0.8393 | -1.0532 | -1.5306 |
2023 | 2.6986 | 1.9195 | 1.8358 |
2024 | 2.0851 | -0.2615 | -1.5749 |
2025 | 0.8325 | 1.1753 | 1.2061 |
And below both are plotted for each year, the maximum drawdown together with the S&P 500.
Together the two modules cover 70+ metrics, such as Value at Risk, GARCH, Jensen's Alpha, the Capital Asset Pricing Model and the Fama-French factors. Most of them also accept rolling=<n> for a value that moves through time.
What the Option Market Expects
The past shows how much risk came with the returns; the option market puts a price on the risk ahead. The options module prices options with Black-Scholes, the Binomial Model and others, calculates the Greeks up to the third order and reads the live option chains: the put-call ratio, max pain, dealer gamma exposure, the volatility skew and term structure and the implied move. As the chains are those of today, the Toolkit below runs up to today, and the numbers are those of the day this README was last updated:
# Initialize the Toolkit up to today, as the option chains are live
companies_today = Toolkit(["NVDA", "AMD", "INTC"], api_key="FINANCIAL_MODELING_PREP_KEY")
# The volatility the options imply for the next 30 days against that of the past 30 days
companies_today.options.get_volatility_risk_premium(days=30)The implied volatility is model-free, read with the method behind the VIX from all out-of-the-money options around the horizon, and the realized volatility is that of the daily returns over the same number of days. For example, both are shown below for each company.
Implied Volatility | Realized Volatility | Volatility Risk Premium | Variance Risk Premium | Implied to Realized Ratio | |
NVDA | 0.4845 | 0.2795 | 0.2049 | 0.1566 | 1.7331 |
AMD | 0.657 | 0.498 | 0.159 | 0.1836 | 1.3192 |
INTC | 0.6991 | 0.5196 | 0.1795 | 0.2188 | 1.3456 |
Options usually price more risk than follows, as their sellers want to be paid for taking it on, and here they priced far more turbulence for the coming month than the past month delivered: Nvidia's options implied 1.7 times the volatility its shares showed. And below the implied and realized volatility of each company are plotted next to each other.
The Economic Environment
All three are listed in the United States and valued on earnings that lie years ahead, which makes US inflation and interest rates the backdrop to their share prices. In 2022, the year the maximum drawdown above shows each of them falling by more than half, inflation reached 9% and the Federal Reserve raised its policy rate from 0.12% to 4.38%.
The economics module covers 60+ countries with 50+ indicators, from GDP and unemployment to money supply and interest rates, and the fixed income module adds bond yields, yield curves, central bank rates and calculations on individual bonds. Both are reached through the same Toolkit instance, or on their own with from financetoolkit import Economics, FixedIncome:
# Inflation on the same month a year earlier and the Federal Reserve's policy rate
inflation_rate = companies.economics.get_inflation_rate("United States", period="monthly")
policy_rate = companies.economics.get_central_bank_policy_rate("United States", period="monthly")
# The daily U.S. Treasury par yield curve
treasury_rates = companies.fixedincome.get_treasury_rates()
# Show the curve on the last trading day of each year
treasury_rates.groupby(treasury_rates.index.year).last()For example, the yield curve at the end of each year is shown below.
Date | 1 Month | 2 Month | 3 Month | 6 Month | 1 Year | 2 Year | 3 Year | 5 Year | 7 Year | 10 Year | 20 Year | 30 Year |
2018 | 0.0244 | 0.0245 | 0.0245 | 0.0256 | 0.0263 | 0.0248 | 0.0246 | 0.0251 | 0.0259 | 0.0269 | 0.0287 | 0.0302 |
2019 | 0.0148 | 0.0151 | 0.0155 | 0.016 | 0.0159 | 0.0158 | 0.0162 | 0.0169 | 0.0183 | 0.0192 | 0.0225 | 0.0239 |
2020 | 0.0008 | 0.0008 | 0.0009 | 0.0009 | 0.001 | 0.0013 | 0.0017 | 0.0036 | 0.0065 | 0.0093 | 0.0145 | 0.0165 |
2021 | 0.0006 | 0.0005 | 0.0006 | 0.0019 | 0.0039 | 0.0073 | 0.0097 | 0.0126 | 0.0144 | 0.0152 | 0.0194 | 0.019 |
2022 | 0.0412 | 0.0441 | 0.0442 | 0.0476 | 0.0473 | 0.0441 | 0.0422 | 0.0399 | 0.0396 | 0.0388 | 0.0414 | 0.0397 |
2023 | 0.056 | 0.0559 | 0.054 | 0.0526 | 0.0479 | 0.0423 | 0.0401 | 0.0384 | 0.0388 | 0.0388 | 0.042 | 0.0403 |
2024 | 0.044 | 0.0439 | 0.0437 | 0.0424 | 0.0416 | 0.0425 | 0.0427 | 0.0438 | 0.0448 | 0.0458 | 0.0486 | 0.0478 |
2025 | 0.0374 | 0.0367 | 0.0367 | 0.0359 | 0.0348 | 0.0347 | 0.0355 | 0.0373 | 0.0394 | 0.0418 | 0.0479 | 0.0484 |
And below the yield curve at the end of each year is plotted. It went from almost zero at the short end in 2021 to above 4% across all maturities a year later, and when short-term yields lie above long-term ones, as at the end of 2022 and 2023, the curve is inverted.
Economic Relations
Rates rose and the shares fell, but a 10-year Treasury yield is made of two parts: the real yield, the return investors demand on top of inflation, and the inflation they expect over those ten years. The econometrics module tells such drivers apart with regressions, tests and forecasts built on statsmodels and linearmodels (pip install financetoolkit[econometrics]). Through the Toolkit it analyzes the returns of its tickers, and on its own, through Econometrics(data=...), any data at all, here the monthly returns of the three next to the monthly change in the US 10-year real yield and in 10-year inflation expectations:
import pandas as pd
from financetoolkit import Econometrics
# The US 10-year real yield and inflation expectations at the end of each month
real_yield = companies.economics.get_real_yield_curve("United States", period="monthly")
inflation_expectations = companies.economics.get_breakeven_inflation_expectations(
"United States", period="monthly"
)
# The monthly change in both next to the monthly returns
monthly_returns = companies.get_historical_data(period="monthly")["Return"][["NVDA", "AMD", "INTC"]]
monthly_returns["Real Yield"] = real_yield[("United States", "10Y")].diff()
monthly_returns["Inflation Expectations"] = inflation_expectations[("United States", "10Y")].diff()
# The data are changes already
econometrics = Econometrics(data=monthly_returns, changes=None)
# Regress the return of each company on the change in the real yield and inflation expectations
regressions = pd.concat(
{
ticker: econometrics.get_ols(
dependent_ticker=ticker, independent_tickers=["Real Yield", "Inflation Expectations"]
)
for ticker in ["NVDA", "AMD", "INTC"]
}
)
# Show the results for Nvidia
regressions.loc["NVDA"]For example, the coefficients for Nvidia are shown below.
Coefficient | Std. Error | t-Statistic | P-Value | |
Intercept | 0.049 | 0.0129 | 3.8028 | 0.0003 |
Real Yield | -22.8132 | 5.6358 | -4.0479 | 0.0001 |
Inflation Expectations | 18.1329 | 9.1029 | 1.992 | 0.0493 |
And below each coefficient is shown with its 95% confidence interval. A rise of 0.1 percentage point in the real yield went with a monthly return about 2.3% lower for Nvidia, 3.4% for AMD and 1.9% for Intel, as a higher real yield discounts their distant earnings more heavily. Inflation expectations matter far less: only for Nvidia does their coefficient come close to significance.
The module also covers unit root and cointegration tests, Granger causality, panel data, causal inference, ARIMA, VAR and VECM forecasts, regime switching, a time-varying beta and pairs trading.
Comparing the Sector's ETFs
Rather than picking three companies, a fund holds the whole industry. The ETF module analyzes the holdings, sector and country weightings, tracking, concentration, overlap, valuation and liquidity of any fund. Below it compares six semiconductor funds: three focused on the United States (SOXX, XSD and PSI), one global fund (SMH) and two that hold a single country, China (SMHC) and South Korea (KCHP):
# Initialize the Toolkit for six semiconductor funds
funds = Toolkit(
["SOXX", "XSD", "PSI", "SMH", "SMHC", "KCHP"],
api_key="FINANCIAL_MODELING_PREP_KEY",
start_date="2017-12-31",
end_date="2025-12-31",
)
# Where each fund invests, how concentrated it is and how much the funds hold of the same
country_weightings = funds.etf.get_country_weightings()
concentration = funds.etf.get_concentration()
overlap = funds.etf.get_overlap()
# Show the overlap between every pair of funds
overlap.round(2)For example, the overlap between every pair of funds is shown below: the share of the two portfolios that is the same. Holdings are those of today, as funds publish their current holdings only.
SOXX | XSD | PSI | SMH | SMHC | KCHP | |
SOXX | 1 | 0.38 | 0.46 | 0.7 | 0 | 0 |
XSD | 0.38 | 1 | 0.34 | 0.28 | 0 | 0 |
PSI | 0.46 | 0.34 | 1 | 0.38 | 0 | 0 |
SMH | 0.7 | 0.28 | 0.38 | 1 | 0 | 0 |
SMHC | 0 | 0 | 0 | 0 | 1.08 | 0 |
KCHP | 0 | 0 | 0 | 0 | 0 | 1 |
The three US funds and SMH largely hold the same companies, with SOXX and SMH sharing 70% of their portfolios. SMH holds the most outside the United States, 9% in Taiwan and 6% in the Netherlands. The China and Korea funds share nothing with any other fund, which is what diversification within one sector looks like. Below, the country weights of each fund are plotted next to the overlap.
Building a Diversified Portfolio
A fund spreads the risk over the sector, but the sector still moves as one. The portfolio module builds portfolios from the tickers of any Toolkit: minimum variance, maximum Sharpe ratio, mean-variance, risk parity, Hierarchical Risk Parity, Hierarchical Equal Risk Contribution, Nested Clustered Optimization, minimum CVaR, minimum drawdown, maximum Omega and CVaR ratio, Black-Litterman, maximum diversification, minimum tracking error and growth optimal (Kelly) weights, the efficient frontier, risk contributions, stress tests and attribution. Below the semiconductor fund is combined with health care (XLV), energy (XLE), long-term Treasuries (TLT) and gold (GLD):
# Initialize the Toolkit for funds across sectors and asset classes from 2021 to 2025
assets = Toolkit(
["SMH", "XLV", "XLE", "TLT", "GLD"],
api_key="FINANCIAL_MODELING_PREP_KEY",
start_date="2021-01-01",
end_date="2025-12-31",
)
# The efficient frontier and the maximum Sharpe ratio portfolio, with at most 40% per asset
efficient_frontier = assets.portfolio.get_efficient_frontier(points=25, maximum_weight=0.4)
maximum_sharpe = assets.portfolio.get_maximum_sharpe_weights(maximum_weight=0.4)
# The portfolio in which every asset contributes the same share of the risk
risk_parity = assets.portfolio.get_risk_parity_weights()
# Show the risk parity portfolio
risk_parityFor example, the risk parity portfolio is shown below. Returns and volatilities are annualized and the risk contribution is each asset's share of the portfolio's volatility.
Weight | Expected Return | Volatility | Sharpe Ratio | Risk Contribution | |
SMH | 0.1008 | 0.3067 | 0.3508 | 0.7782 | 0.2 |
XLV | 0.2358 | 0.0901 | 0.1449 | 0.3889 | 0.2 |
XLE | 0.1481 | 0.2463 | 0.2672 | 0.7954 | 0.2 |
TLT | 0.275 | -0.0748 | 0.1606 | -0.6756 | 0.2 |
GLD | 0.2403 | 0.1681 | 0.1562 | 0.8603 | 0.2 |
Portfolio | 1 | 0.1084 | 0.1085 | 0.6888 | 1 |
And below the efficient frontier is plotted with both portfolios and each asset on its own, next to the weights of both portfolios.
Following the Portfolio
Optimal weights on paper still have to be held. The Portfolio class follows a portfolio over time, given as weights, as the shares held, as your own transactions or as one of thirteen classic portfolios such as the 60/40 and the All Weather portfolio. Below the risk parity weights are invested at the start of 2021, brought back to their weights every year and followed up to today:
from financetoolkit import Portfolio
# Invest the risk parity weights and rebalance every year
portfolio = Portfolio(
weights=risk_parity,
start_date="2021-01-01",
rebalancing="yearly",
api_key="FINANCIAL_MODELING_PREP_KEY",
)
# Get an overview of the positions against the benchmark
overview = portfolio.get_portfolio_overview()
# Show the main figures
overview[["Weight", "Return", "Benchmark Return", "Volatility", "Alpha", "Beta"]]For example, the main figures of each position are shown below.
Identifier | Weight | Return | Benchmark Return | Volatility | Alpha | Beta |
GLD | 0.1969 | 0.9399 | 0.849 | 0.2845 | 0.0909 | 0.8392 |
SMH | 0.1307 | 2.0669 | 0.5236 | 0.4001 | 1.5433 | 2.4046 |
TLT | 0.2273 | -0.2038 | 0.7457 | 0.096 | -0.9494 | 0.2198 |
XLE | 0.2034 | 1.5458 | 0.2236 | 0.2212 | 1.3222 | -0.4119 |
XLV | 0.2418 | 0.5502 | 0.7995 | 0.1632 | -0.2493 | 0.256 |
Portfolio | 1 | 0.9703 | 1.1143 | 0.1047 | -0.144 | 0.5075 |
And below the return of each position is plotted against the return of the benchmark over the same period.
With portfolio.toolkit the portfolio, the time-weighted sum of all positions, is loaded into the Toolkit, so every metric above can be calculated for it as well.
MCP Server
The Finance Toolkit MCP Server exposes 500+ financial methods directly to any AI assistant that supports the Model Context Protocol (MCP). Ask questions in plain English — the AI fetches live financial data on your behalf, backed by the transparent, open-source calculation methods of the Finance Toolkit.
See an example of the Finance Toolkit MCP server in action in Claude Desktop below:
https://github.com/user-attachments/assets/96ad5288-d83d-4497-a345-1841c48c29d5
Remote server
Connect directly to the hosted server at https://financetoolkit.jeroenbouma.com/mcp. Nothing needs to be installed locally. On first connection your client opens an OAuth consent page asking for your FMP API key (and, optionally, a FRED API key for the corporate bond series); enter it once and the server handles authentication from there.
Client | Steps |
Claude Desktop | Customize → Connectors → Add custom connector → paste the URL |
Claude.ai | Customize → Connectors → Add custom connector → paste the URL |
Claude Code |
|
VS Code | Command Palette → MCP: Add Server → HTTP → paste the URL |
Cursor | Cursor Settings → Tools & MCP → New MCP Server → add |
Windsurf | Cascade panel → MCPs → Configure → add |
Local installation
Run the setup wizard — it locates your client's config file and writes the MCP entry automatically, including the API key:
uvx --from "financetoolkit[mcp]" financetoolkit-mcp-setupFor manual config, add the following to your client's MCP config file (e.g. claude_desktop_config.json, .cursor/mcp.json, .vscode/mcp.json):
{
"mcpServers": {
"finance-toolkit": {
"command": "uvx",
"args": ["--from", "financetoolkit[mcp]", "financetoolkit-mcp"],
"env": { "FINANCIAL_MODELING_PREP_API_KEY": "YOUR_API_KEY_HERE" }
}
}
}Alternatively, download the Finance Toolkit MCPB bundle and open it with Claude Desktop. An installation dialog will prompt for your FMP API key.
Questions & Answers
This section includes frequently asked questions and is meant to clear up confusion about certain results and/or deviations from other sources. If you have any questions that are not answered here, feel free to reach out to me via the contact details below.
How do you deal with companies that have different fiscal years?
For any financial statement, I make sure to line it up with the corresponding calendar period. For example, Apple's Q4 2023 relates to July to September of 2023. This corresponds to the calendar period Q3 which is why I normalize Apple's numbers to Q3 2023 instead. This is done to allow for comparison between companies that have different fiscal years.
Why do the numbers in the financial statements sometimes deviate from the data from FinancialModelingPrep?
When looking at a company such as Hyundai Motor Company (ticker: 005380.KS), you will notice that the financial statements are reported in KRW (South Korean won). As this specific ticker is listed on the Korean Exchange, the historical market data will also be reported in KRW. However, if you use the ticker HYMTF, which is listed on the American OTC market, the historical market data will be reported in USD. To deal with this discrepancy, the end of year or end of quarter exchange rate is retrieved which is used to convert the financial statements to USD. This is done to prevent ratio calculations such as the Free Cash Flow Yield (which is based on the market capitalization) or Price Earnings Ratio (which is based on the stock price) from being incorrect. This can be disabled by setting convert_currency=False in the Toolkit initialization. It is recommended to always use the ticker that is listed on the exchange where the company is based.
How can I get TTM (Trailing Twelve Months) and Growth metrics?
Most functions will have the option to define the trailing parameter. This lets you define the number of periods that you want to use to calculate the trailing metrics. For example, if you want to calculate the trailing 12-month (TTM) Price-to-Earnings Ratio, you can set trailing=4 when you have set quarterly=True in the Toolkit initialization. The same goes for growth metrics which can be calculated by setting growth=True. This will calculate the growth for each period based on the previous period. This also includes a lag parameter in which you can define lagged growth. Furthermore, you can also combine the trailing and growth parameters to get trailing growth. For example, set trailing=4 and growth=True for the Price-to-Earnings Ratio which will then calculate the TTM growth.
Does the Finance Toolkit retrieve the same data every time I run it?
No. Any data that comes from an external source (financial statements, historical prices, economic indicators, yield curves, news and so on) is cached automatically in a local SQLite database and reused on the next run, in the Toolkit as well as in the Economics, Fixed Income, Discovery and Portfolio modules. Anything the Finance Toolkit calculates itself, such as ratios, models and risk metrics, is never cached: it is always derived from that data on demand, so it reflects the latest version of the Finance Toolkit.
Cached data does not go stale. Each dataset is retrieved again once it may have changed: prices and financial statements after a day (prices only for the last week, since older bars no longer change), quotes after a minute, company profiles after a month and economic releases according to how often they are published. An answer that a source has no data, such as the ETF holdings of a company, is cached as well, while a failed request, such as a rate limit, is not.
The cache keeps track of what it already holds per ticker and per date range, which means changing a parameter does not throw the rest away:
Repeating the same request retrieves nothing at all.
Widening the period only retrieves the years that were missing.
Adding a ticker only retrieves that one ticker.
The database lives in your user configuration directory, which is the same one the MCP server uses, so both share a single cache. You can choose where it is stored, or switch caching off:
from financetoolkit import Economics, Toolkit
# Store the cache in a specific folder
toolkit = Toolkit(["AAPL", "MSFT"], use_cached_data="datasets")
# Retrieve everything every time
toolkit = Toolkit(["AAPL", "MSFT"], use_cached_data=False)
economics = Economics(use_cached_data=False)Setting the FINANCE_TOOLKIT_CACHE_ENABLED environment variable to 0 switches caching off by default everywhere, which suits environments where nothing should be written to disk, such as a continuous integration job. FINANCE_TOOLKIT_CACHE_DB moves the shared database to another file.
To see what is currently stored, use toolkit.get_cache_contents(). It reports the entries grouped by source and dataset:
source | dataset | entities | entries | oldest_write | newest_write |
FinancialModelingPrep | historical | 2 | 2 | 2025-01-14 09:12:03 | 2025-01-14 09:12:05 |
FinancialModelingPrep | statements | 2 | 2 | 2025-01-14 09:12:01 | 2025-01-14 09:12:02 |
The Finance Toolkit never clears the cache on its own, not even when its own internal structure changes. Removing data is always something you ask for explicitly with toolkit.clear_cache(), and it can be narrowed instead of wholesale:
# Remove only the price history of a single ticker
toolkit.clear_cache(source="FinancialModelingPrep", ticker="AAPL")
# Remove everything retrieved from the OECD
toolkit.clear_cache(source="OECD")
# Remove the entire cache, which has to be confirmed
toolkit.clear_cache(confirm=True)The source names match the ones used by the enforce_source parameter, so "FinancialModelingPrep" and "YahooFinance" mean the same thing in both places.
What is the "Benchmark" that is automatically obtained when acquiring historical data?
This is related to the benchmark_ticker parameter which is set to "SPY" (S&P 500) by default. This is important when calculating performance metrics such as the Sharpe Ratio or Treynor Ratio that require a market return. This can be disabled by setting benchmark_ticker=None in the Toolkit initialization.
Data collection seems to be slow, what could be the issue?
Generally, it should take less than 15 seconds to retrieve the historical data of 100 tickers. If it takes much longer, this could be due to reaching the API limit (the Starter plan has 250 requests per minute), due to a slow internet connection or due to unoptimized code. The Finance Toolkit collects data with a bounded pool of worker threads (10 by default, configurable through the FINANCETOOLKIT_MAX_WORKERS environment variable) over a shared connection, so it is recommended to initialize the Toolkit with all tickers you want to analyze at once rather than one at a time. If it is taking 10+ minutes consider having a look at this issue that managed to resolve the problem.
I work behind a corporate proxy and get "certificate verify failed" errors, how do I solve this?
Many corporate networks inspect encrypted traffic. The proxy opens every HTTPS connection on your behalf and presents a certificate signed by your company's own root certificate instead of the website's real one. Your browser trusts that root certificate because IT installed it on your computer, but Python does not: it checks certificates against its own list of public certificate authorities (the certifi package), which does not include your company's. The result is an error such as SSLError: certificate verify failed: self-signed certificate in certificate chain.
When a certificate cannot be verified, the Finance Toolkit first retries with your operating system's certificate file, where Python can find one (usually on Linux, not on Windows). If that fails as well, what happens next depends on whether the request carries an API key:
Requests without an API key, such as those to the ECB, Eurostat or the BIS, are retried without verifying the certificate. A warning is logged when this happens.
Requests with an API key, such as those to FinancialModelingPrep and FRED, are not retried without verification. The key is part of the web address, so anyone who can intercept an unverified connection could read it and use your subscription. The request fails with an error that explains the options below.
The recommended solution is to tell Python to trust your company's root certificate, so every connection stays verified:
Obtain the root certificate as a
.pem(or.crt) file. Your IT department can usually provide it. You can also export it from your browser by opening the certificate details of any HTTPS website and exporting the top certificate in the chain ("Base-64 encoded" on Windows).Combine it with Python's public certificates. The next step replaces Python's list rather than adding to it, so without the public certificates every connection that does not go through the proxy would fail:
# Prints the location of Python's public certificates python -c "import certifi; print(certifi.where())" # macOS and Linux: combine both into one file cat /path/printed/above/cacert.pem /path/to/company-root.pem > ~/combined-certificates.pemOn Windows you can open both files in a text editor and paste the company certificate at the end of a copy of
cacert.pem.Point
REQUESTS_CA_BUNDLEto the combined file before using the Finance Toolkit:# macOS and Linux, e.g. in ~/.bashrc or ~/.zshrc export REQUESTS_CA_BUNDLE=~/combined-certificates.pem # Windows (PowerShell), for every window opened afterwards setx REQUESTS_CA_BUNDLE "C:\Users\you\combined-certificates.pem"setxdoes not change the window it runs in, so open a new terminal (or restart your editor) afterwards.Or set it within Python, before the first request:
import os os.environ["REQUESTS_CA_BUNDLE"] = "/path/to/combined-certificates.pem" from financetoolkit import ToolkitWhen you use the MCP server, add the variable to the
envsection of the server in your AI assistant's configuration instead.
Alternatively, if your company's root certificate is already installed in your operating system (which is usually the case on managed Windows and macOS computers), the truststore package lets Python use the operating system's certificates directly. Install it with pip install truststore and run import truststore; truststore.inject_into_ssl() at the start of your script.
If none of this is possible, you can accept the risk and allow requests with an API key to be sent without verification by setting FINANCETOOLKIT_ALLOW_UNVERIFIED_SSL=1 in the same way as above. Only do so on a network you trust: the connection is then encrypted to whoever answers it, which may not be the website you think you are talking to, and your API key is readable to them.
To go the other way and never send a request without verification, not even one without an API key, set FINANCETOOLKIT_ALLOW_UNVERIFIED_SSL=0. A hosted MCP server (the sse or streamable-http transport) does this by default, since the data it retrieves reaches every user through its cache.
Are you part of FinancialModelingPrep?
No, I am not. I've merely picked them as the primary data provider given that they have a generous free tier and fair pricing compared to other providers. Therefore, any questions related to the data should go through their contact form. When it comes to any type of ratios, performance metrics, risk metrics, technical indicators or economic indicators, feel free to reach out to me as this is my own work.
Contributing
First off all, thank you for taking the time to contribute (or at least read the Contributing Guidelines)! 🚀
Find the Contributing Guidelines here.
The goal of the Finance Toolkit is to make any type of financial calculation as transparent and efficient as possible. I want to make these type of calculations as accessible to anyone as possible and seeing how many websites exists that do the same thing (but instead you have to pay) gave me plenty of reasons to work on this.
Mentions
The Finance Toolkit has been mentioned in various blogposts, research papers, newsletters and social media. Below is a list of some of the mentions that I am aware of. If you have any other mentions, feel free to reach out to me so I can add them to this list.
Blogposts
Discovering the Best Integrated Platforms for Big Tech Quantitative Finance: 1. Finance Toolkit
Unlocking Financial Clarity: Introducing the Open-Source Finance Toolkit Powered by FMP
Research
Newsletters & Social Media
Contact
If you have any questions about the Finance Toolkit or would like to share with me what you have been working on, feel free to reach out to me via:
Website: https://jeroenbouma.com/
LinkedIn: https://www.linkedin.com/in/boumajeroen/
Email: jer.bouma@gmail.com
If you'd like to support my efforts, either help me out by contributing to the package or Sponsor Me.
Available Tools
28 toolsbreadthARead-onlyIdempotentInspect
Market breadth technical indicators (McClellan Oscillator, OBV, Advance/Decline Line, Chaikin, TRIN, new highs and lows). Applied to price data automatically — no need to fetch prices first. TRIN treats the given tickers as one market, so every column holds the same value; pass the market's constituents for a meaningful figure. Each indicator needs its window of history before it produces values, so the first periods after start_date can be empty and quarterly or yearly periods with long windows can be empty on short histories; start earlier to warm up. Requires tickers='AAPL' — use comma-separated values for multiple tickers. get_market_breadth measures the breadth of all tickers together (advancers and decliners, the advance-decline line, the McClellan oscillator and summation index, the share above the 50 and 200-period averages and new highs and lows), meant for many tickers such as an index's constituents (discovery get_index_constituents). For the predictive power of these indicators across tickers (factor analysis), use the momentum tool with indicator='get_factor_analysis' and metrics='breadth'.
Inputs: indicator (required), lag, rank, limit, +18 more. Returns: result
discoveryARead-onlyIdempotentInspect
Market discovery (lists of stocks, ETFs, indices, currencies, commodities and cryptocurrencies, stock screener, biggest gainers and losers, most active stocks, sector and industry performance and P/E, earnings, IPO and stock split calendars, latest 8-K filings, insider trades and mergers, market news and press releases). No tickers or countries needed. The news and press release feeds (get_stock_news, get_press_releases, get_general_news, get_crypto_news, get_forex_news) are the latest articles across the whole market, not news about one company: each article names its ticker, but the feed cannot be narrowed to a ticker. The calendars and filings take start_date/end_date; the market-wide earnings calendar (get_earnings_calendar) covers the coming week unless a range is given and lists the largest companies first, one row per company (its primary, most traded listing; share classes with names of their own count as separate companies) with 'Market Cap (USD)'; min_market_cap= (in US dollars), country= (the company's country) and exchange= (e.g. 'XETRA') narrow it, sort_by='date' sorts by date and primary_only=false shows every listing. Its EPS and revenue are in the currency the source reports for each listing. Sector and industry performance and P/E take date= for one day's snapshot or sector=/industry= for a history (the last year unless start_date/end_date say otherwise); they average the companies of one exchange, exchange='NASDAQ' (default), 'NYSE' or 'AMEX', and performance is a decimal change (0.0125 is +1.25%). The stock screener ranks by market cap in US dollars ('Market Cap (USD)'; 'Market Cap' is in the listing's own currency) and returns every listing of a company unless primary_only=true; to screen by classification, use the Finance Database server. get_index_constituents lists the members of index='S&P 500', 'NASDAQ 100' or 'Dow Jones', today's or, with date=, those on a past date (with the date each left the index), free of survivorship bias; get_index_constituent_changes lists the dated additions and removals with their reasons (start_date/end_date). get_industry_statistics returns Aswath Damodaran's industry averages (about 95 industries plus the Total Market, computed every January from all listed companies): dataset='cost_of_capital' (default; beta, cost of equity and debt, debt weights, WACC), 'betas' (levered and unlevered betas, the unlevered beta corrected for cash, D/E ratio), 'total_betas', 'margins', 'price_to_earnings', 'price_to_book', 'price_to_sales' or 'enterprise_value_multiples', for region='United States' (default), 'Europe', 'Japan', 'Australia, New Zealand and Canada', 'Emerging Markets', 'China', 'India' or 'Global'; rates and margins are decimals, betas and multiples plain numbers. Use show_columns to keep a few columns.
Inputs: indicator (required), date, page, rank, +26 more. Returns: result
econometricsBRead-onlyIdempotentInspect
Statistical and econometric analysis of price or return series: unit root tests (ADF, KPSS, Phillips-Perron, Zivot-Andrews), cointegration (Engle-Granger, Johansen, VECM), Granger causality, VAR forecasts, impulse responses and variance decomposition, ARIMA forecasts, regressions (OLS, WLS, GLS, quantile, logistic, probit, IV/2SLS, Fama-MacBeth, fixed and random effects panels; get_wls estimates its weights from the regression's residuals with weights='feasible' and get_gls an AR(1) error covariance with omega='ar1', the defaults; get_wald_test takes restriction_matrix as rows of numbers, e.g. [[0, 1, 0], [0, 0, 1]], with one column per coefficient, the Intercept first), causal designs (difference-in-differences, event study, regression discontinuity, synthetic control, propensity score matching), diagnostics (ARCH-LM, Jarque-Bera, Ljung-Box, Durbin-Watson, Breusch-Pagan, White, Ramsey RESET, VIF, Chow, CUSUM, variance ratio), forecast comparison (Diebold-Mariano, RMSE, MAE), regimes and dynamics (get_markov_regime_switching: calm and turbulent regimes with their mean, volatility and expected duration, probabilities=true per date; get_structural_breaks: Bai-Perron dates at which the mean shifts; get_time_varying_beta: Kalman filter alpha and beta per date against the benchmark; get_dcc_garch: DCC-GARCH correlation of every pair per date, parameters=true for the estimates) get_pairs_trading (hedge ratio, half-life, cointegration p-value, z-score and signal per pair, window= for a rolling z-score, time_series=true per date) and get_move_significance (how unusual each change of a series is: the change in units of its trailing volatility and VaR, its percentile among earlier moves and 'Largest Since', the last date a move in the same direction was as large; e.g. series='rates:get_treasury_rates:2 Year' with changes='difference' and limit=-1 for the latest daily move of the 2-year yield in points and 'the largest one-day rise since'; start_date a year or more back, as the volatility needs a year of moves). get_level_significance (how unusual the latest value of each series is: its percentile and Rank (1 for the highest, e.g. Rank 3 is 'the 3rd highest since' the Start Date) in the series' own history and the last dates it was at least as high ('Highest Since') and as low ('Lowest Since'), e.g. series='rates:get_long_term_interest_rate:United States' with period='monthly' and start_date='2000-01-01'; the answer depends on start_date, which the Start Date column shows; it also gives the Start Value and the Change Since Start (latest / first - 1, a decimal), the change of any series between start_date and its latest value, e.g. series='macroeconomics:get_housing_starts:United States' with period='monthly' and start_date='2021-01-01'; and the Highest and Lowest of the range (the latest value included) with the first date each was reached (Highest Date, Lowest Date) and the Change From Highest and Change From Lowest (latest / highest - 1 and latest / lowest - 1, decimals), so start_date anchors an event window: tickers='BZ=F' with start_date='2026-02-27' gives Brent's close that day, its peak since, the date of the peak and the fall from it; also the Multiple Since Start and Annualised Change (the compound annual rate between start_date and the latest value, e.g. CPI 1970 to now) and the Largest Drawdown with its Drawdown Peak Date, Drawdown Trough Date and Recovery Date (peak to trough and when the peak was regained, of any series)) and get_streaks (the streak each series is on: the Sign of its latest value, the Run Start and Run Length of the current run, the Previous Sign, Previous Run Start, Previous Run End and Previous Run Length, and the longest earlier run of the same sign, lengths in observations, e.g. months with period='monthly'; column='Return' counts rises and falls instead; level=0.02 counts the runs above and below 2% instead of zero, e.g. years of inflation below 2%) and get_window_change_by_year (the change over the same months of every year, from_month= and to_month= as numbers, e.g. 2 and 10 for February to October, per year with the Start Value, End Value, Change (a decimal), Rank (1 for the largest) and Largest Since (the last earlier year with a change at least as large), e.g. series='macroeconomics:get_consumer_price_index:United States' with start_date='2000-01-01'; for a rate pass changes='difference'). All three take spread_over= (with ratio=true the other series divided by it instead, e.g. exports over GDP) with the name of one of the series to measure every other series minus it instead, e.g. series='macroeconomics:get_economic_calendar:China:Producer Price Index YoY; macroeconomics:get_economic_calendar:China:Inflation Rate YoY' with spread_over='China Inflation Rate YoY' and period='monthly' for the spread of producer over consumer price inflation (named 'China Producer Price Index YoY - China Inflation Rate YoY'). Two indicators with the same country are named after their indicator too, e.g. series='rates:get_mortgage_rate_30_year:United States; rates:get_long_term_interest_rate:United States' with spread_over='United States Long Term Interest Rate' for the mortgage spread over the 10-year Treasury. A spread exists on the dates both series have: without period= a weekly series minus a daily one is measured on the weekly dates; period='weekly' or 'monthly' takes the last value of each period of both. No need to fetch price data first. Requires tickers='AAPL' — use comma-separated values for multiple tickers. With series= of indicators by ticker, basket=true adds the tickers up into one company, 'Total', a series of its own (e.g. series='solvency:get_capex_coverage_ratio:MSFT,AMZN,GOOGL,META' with basket=true and quarterly=true for the level significance of their combined capex coverage). To analyze any other indicator instead of prices, pass series= with references separated by ';', each tool:indicator:tickers-or-countries with an optional :column, e.g. series='valuation:get_price_to_earnings_ratio:AAPL,MSFT' (quarterly=true for quarterly ratios), series='macroeconomics:get_inflation_rate:United States,Germany' or series='rates:get_government_bond_yield_curve:United States:2Y; rates:get_government_bond_yield_curve:United States:10Y'; each ticker or country becomes a series named after it (with the column, e.g. 'United States 10Y'), which dependent_ticker and independent_tickers name. The series themselves are the 'Adj Close' column (unit root, cointegration, breaks) and their changes the 'Return' column (regressions, diagnostics); changes='difference' suits rates and ratios, and also gives the changes of get_level_significance (Change Since Start, Change From Highest and Lowest, Largest Drawdown) and get_window_change_by_year in points instead of relative changes, e.g. series='rates:get_long_term_interest_rate:United States' with start_date='2026-09-30', end_date='2026-10-30' and changes='difference' for the change of the 10-year yield over October (-0.0035 is -0.35 percentage points). With series=, period= is also passed to every indicator that is published at that period (period='monthly' reads a monthly series as its source publishes it); an indicator that is not is read at its own frequency. Use start_date for a long enough history.
Inputs: indicator (required), d, p, q, +101 more. Returns: result
efficiencyARead-onlyIdempotentInspect
Pre-computed efficiency ratios (asset turnover, inventory turnover, days sales outstanding, days payable outstanding, cash conversion cycle, capex intensity (capex/revenue), capex to depreciation, net capital expenditure (capex minus depreciation and amortization, the investment beyond what wears off), and the investment anomalies: asset growth (Cooper-Gulen-Schill, year over year on quarterly data) and net operating assets (Hirshleifer et al. NOA: operating assets minus operating liabilities over the total assets of the period before)). Requires tickers='AAPL' — use comma-separated values for multiple tickers. Use instead of raw financial statements. Supports quarterly=true and start_date/end_date. basket=true also adds up the tickers into one company, 'Total', whose ratios are calculated on the summed statements (e.g. the capex coverage of a group of companies together, not an average of their ratios); per-share ratios stay empty for it. For the predictive power of these ratios across tickers (factor analysis), use the valuation tool with indicator='get_factor_analysis' and metrics='efficiency'.
Inputs: indicator (required), lag, days, rank, +12 more. Returns: result
environmentARead-onlyIdempotentInspect
Environmental and ESG data. For ESG scores (E, S, G ratings) use tickers='AAPL'. For carbon footprint and renewable energy data use countries='United States' (also supports rolling=N and trailing=N smoothing/summation). This is the only tool that accepts BOTH tickers= and countries= depending on the indicator. get_carbon_price returns the EU ETS carbon price (EEX primary auctions of EU emission allowances, euro per tonne of CO2, daily from 2020, no countries needed), period='daily', 'weekly' or 'monthly'. get_climate_scenario returns NGFS climate scenario paths (Phase 5, yearly 2022-2050, around fifty countries and regions): variable='gdp'|'inflation'|'long_term_interest_rate'|'long_term_real_interest_rate'|'policy_rate'|'unemployment_rate'|'equity_prices'|'effective_exchange_rate'|'oil_price'|'gas_price'|'coal_price'|'carbon_price' (carbon price per model region to 2100), scenario='Net Zero 2050'|'Below 2°C'|'Low demand'|'Delayed transition'|'Nationally Determined Contributions (NDCs)'|'Current Policies'|'Fragmented World'|'Baseline', model='REMIND-MAgPIE'|'GCAM'|'MESSAGEix-GLOBIOM', risk='combined'|'transition'|'physical', deviation=true for the deviation from the baseline; countries= optional.
Inputs: indicator (required), lag, rank, risk, +17 more. Returns: result
etfARead-onlyIdempotentInspect
Analysis of ETFs and other funds. Requires tickers='VOO' — use comma-separated values for several funds; tickers that are not an ETF or fund return no data. get_holdings: the 25 largest holdings of each fund by weight (shares, weight and market value) unless limit= asks for more, limit=-10 for the smallest; the holdings carry no sector or country, so use get_sector_weightings and get_country_weightings for those breakdowns, or the Finance Database server to classify the holdings. get_information: everything published about each fund, including its identifiers, description and website. get_profile: name, issuer, asset class, domicile, inception date, expense ratio, assets under management, NAV, latest price, premium/discount to NAV (the close of the NAV's own date against the NAV; empty for a NAV that is not current unless stale_nav=true), holdings count and average (dollar) volume. get_tracking: tracking difference (annualized return gap, about minus the expense ratio for an index fund), tracking error, correlation, beta and R Squared against benchmark_ticker (set it to the fund's index or another fund of the same index, e.g. benchmark_ticker='SPY' for VOO); yearly=true gives the gap per calendar year. get_concentration: number of holdings, largest holding, top 10 weight, Herfindahl-Hirschman index and effective number of holdings. get_overlap: the overlap of every pair of funds (sum of the smaller weight over shared holdings). get_active_share: the active share of every pair of funds (half the sum of the absolute weight differences, 0 for identical and 1 for unrelated holdings; e.g. tickers='MGK,VOO' for a fund against its index). get_look_through_valuation: weighted (harmonic) P/E, P/B, P/S and P/FCF, dividend yield and net margin of the largest holdings (holdings=25) with the coverage. get_liquidity: average volume and dollar volume, dollar volume to assets and the price impact per $100 million traded (Amihud). get_contribution: how much every holding (group_by='sector' for every sector) added to or took off the fund's price return from the close before start_date to end_date, as Start Weight, Return, Contribution and Points (of the fund's price, or of an index with index='^GSPC' for SPY), largest first, then the Remainder (cash, unpriced holdings) and the Total; the weights are the current holdings rolled back to the start, so short recent periods are the most precise. get_return_excluding: the fund's return without its largest holding, or without the holdings or sectors of exclude= (e.g. exclude='NVDA,Technology'), next to the return of all priced holdings. Both price the holdings one request each (holdings= limits that to the largest).
Inputs: indicator (required), rank, index, limit, +12 more. Returns: result
fixed_incomeARead-onlyIdempotentInspect
Bond calculations on real bonds and market curves; nothing needs to be typed in. The bond calculations (collect_bond_statistics for all measures at once, get_present_value, get_duration, get_yield_to_maturity, get_z_spread, get_key_rate_duration, get_taylor_price_change) return one row per bond with its issuer, coupon, maturity and market price. Without arguments they use the benchmark US Treasuries (the note or bond maturing closest to 2, 3, 5, 7, 10, 20 and 30 years out) from the Treasury's FedInvest prices. Select bonds with bonds= (CUSIPs or ISINs; Treasury CUSIPs start with 912), issuer= (text in the issuer name, e.g. 'APPLE INC', read from bond ETF holdings, which needs a FinancialModelingPrep API key and has only the latest prices), maturity_start=/maturity_end= (YYYY-MM-DD; alone they select every Treasury bill, note and bond maturing in between), etfs= and date= (the day of the Treasury prices). The present value, Z-spread and key rate durations use the US Treasury zero-coupon curve of the price date; yields are semi-annual bond-equivalent decimals and prices clean per 100 of par. TIPS yields are real yields and have no present value or Z-spread on the nominal curve; floating rate notes are left out. get_bond_equivalent_yield lists every Treasury bill with its discount yield and bond-equivalent yield. The rate calculations read the government bond curves of a country (country=, default United States) on a day (date=): get_forward_rate (near_maturity=, far_maturity=, on the zero-coupon curve, annually compounded), get_par_yield (years_to_maturity=, any maturity from the zero-coupon curve), get_yield_curve_spread (long_maturity=, short_maturity=, on the par curve, e.g. 10Y-2Y) and get_breakeven_inflation_rate (US nominal minus TIPS par yields). get_taylor_price_change with from_date= (YYYY-MM-DD) instead of yield_change= measures each Treasury from that day to date=: its own Yield Change, the Taylor estimate of the price change for it (Price Change) and the Realised Price Change of its clean FedInvest price, side by side; the Treasuries are selected on from_date and a weekend or holiday uses the business day before it. get_implied_default_probability turns the latest ICE BofA spread per rating (ratings='BBB,B') into hazard rates and default probabilities (recovery_rate=0.4, horizons='1,5,10'); it needs a FRED API key. get_treasury_securities lists every marketable US Treasury (about 460 bills, notes, bonds, TIPS and FRNs, by CUSIP) with price, yield and duration (date=, security_type='Bill'|'Note'|'Bond'|'TIPS'|'FRN', bonds=). get_bond_universe lists about 9,000 US corporate bonds (investment grade and high yield, by ISIN) from the daily holdings of bond ETFs, with the G-Spread over the Treasury par curve; narrow it with issuer=, bonds=, maturity_start=/maturity_end= and show_columns; etfs= picks other iShares bond funds (default 'LQD,IGSB,USHY', e.g. 'HYG' or 'MUB'). Yields are to maturity, so a callable bond above its call price yields less to its call date. get_issuer_spreads compares issuers at the same maturities: per issuer the G-Spread interpolated between its own bonds at maturity_years= (default '2,3,5,7,10,20,30', e.g. '5' for five years), with the number of Bonds and the Shortest and Longest maturities they cover; no spread outside that range (e.g. issuer='APPLE INC,BOEING,FORD MOTOR CREDIT,INTEL' with maturity_years='4.5'). Mortgage calculations at the weekly US 30-year fixed mortgage rate (Freddie Mac; a nominal annual rate compounded monthly), one row per survey date between start_date and end_date: get_loan_payment (the Payment, Total Interest and First Payment Interest of a new loan at each rate; principal= default 400000, years= default 30, payments_per_year= default 12), get_affordable_loan (the Affordable Loan a fixed payment repays at each rate and its Change since the first date; payment= defaults to the payment of principal= at the first rate in the range, so start_date='2021-01-01' compares today's loan with the same monthly budget in January 2021) and get_amortization_schedule (one row per payment with the Interest, Principal and Balance of a new loan at the rate of date=, default the latest).
Inputs: indicator (required), date, etfs, rank, +29 more. Returns: result
governmentARead-onlyIdempotentInspect
Government fiscal metrics by country (debt, deficit, expenditure, revenue, tax revenue, interest expenditure, expenditure by function, trust in government). Requires countries='United States' — use comma-separated values for multiple countries. Do NOT use tickers= for this tool. Supports start_date/end_date. Debt, deficit, expenditure, revenue and tax revenue are yearly (Global Macro Database, millions of national currency); level='consolidated' (default, longest history), 'general' (general government) or 'central' (central government) selects their level of government. Interest expenditure (IMF, general government interest payable, accrual basis, before interest received; around 40 economies incl. the United States, the euro area countries, the United Kingdom, Canada, Australia and Brazil, not Japan or China) comes quarterly unless period='yearly': get_government_interest_expenditure in millions of national currency, get_government_interest_expenditure_to_gdp_ratio and get_government_interest_expenditure_to_revenue_ratio as decimals, quarterly ratios over the last four quarters. Expenditure by function (IMF COFOG, general government, yearly, around 180 countries, latest year usually one or two years back): get_government_expenditure_by_function (millions of national currency) and get_government_expenditure_by_function_to_gdp_ratio (decimals), columns per country and function; functions= picks 'General Public Services', 'Defence', 'Public Order and Safety', 'Economic Affairs', 'Environmental Protection', 'Housing and Community Amenities', 'Health', 'Recreation, Culture and Religion', 'Education', 'Social Protection' (the ten divisions, the default), 'Public Debt Transactions' (COFOG 01.7, mostly interest, also for countries without interest expenditure) or 'Total', comma-separated. Interest against defence, both shares of the same GDP: get_government_interest_expenditure_to_gdp_ratio with period='yearly' next to get_government_expenditure_by_function_to_gdp_ratio with functions='Defence'. Ratios are decimal fractions (0.04 is 4% of GDP). Supports rolling=N (moving-average smoothing) and trailing=N (trailing N-period sum, e.g. a trailing-4-quarter sum) on the raw series.
Inputs: indicator (required), lag, rank, level, +13 more. Returns: result
jobsARead-onlyIdempotentInspect
Labour and social metrics by country (unemployment rate, labour productivity, population statistics, poverty rate, income inequality). Requires countries='United States' — use comma-separated values for multiple countries. Do NOT use tickers= for this tool. Supports start_date/end_date. Indicators with a period come at the highest frequency they are published at unless period= says otherwise; the others are yearly. quarterly=true returns quarterly data only where a source has it (a note says when it does not). get_life_table returns Eurostat life tables by age 0-95 for European countries, yearly from 1960 (measure='death_probability'|'survival_probability'|'death_rate'|'survivors'|'deaths'|'person_years'|'total_person_years'|'life_expectancy', sex='total'|'male'|'female'); keep countries to one or two, since each country has 96 ages. get_unemployment_rate defaults to monthly figures (Eurostat, the ONS for the United Kingdom, the IBGE for Brazil, the BLS for the latest US months, the OECD for every other country). Supports rolling=N (moving-average smoothing) and trailing=N (trailing N-period sum) on the raw series. Also includes two US-only labor indicators that only return a 'United States' column regardless of the countries= argument: get_initial_jobless_claims (Department of Labor, weekly from 1967) and get_nonfarm_payrolls (BLS, the last three years; a FRED API key gives the history from 1939).
Inputs: indicator (required), lag, sex, rank, +14 more. Returns: result
liquidityARead-onlyIdempotentInspect
Pre-computed liquidity ratios (current ratio, quick ratio, cash ratio, working capital). Requires tickers='AAPL' — use comma-separated values for multiple tickers. Use instead of raw financial statements. Supports quarterly=true and start_date/end_date. basket=true also adds up the tickers into one company, 'Total', whose ratios are calculated on the summed statements (e.g. the capex coverage of a group of companies together, not an average of their ratios); per-share ratios stay empty for it. For the predictive power of these ratios across tickers (factor analysis), use the valuation tool with indicator='get_factor_analysis' and metrics='liquidity'.
Inputs: indicator (required), lag, days, rank, +12 more. Returns: result
macroeconomicsARead-onlyIdempotentInspect
Macroeconomic indicators by country (GDP, real GDP, CPI, PPI, export and import price indices, inflation rate, trade balance, imports, exports, investment, consumption, business/consumer confidence, house prices, rent prices, exchange rates, real effective exchange rate, money supply, household savings rate, household debt-to-income ratio, output gap, real interest rate, misery index, banking/currency/sovereign debt crisis indicators, commercial real estate prices, credit-to-GDP gap, debt service ratios, credit to GDP by sector, commodity forward curves). Requires countries='United States' — use comma-separated values for multiple countries. Do NOT use tickers= for this tool. Supports start_date/end_date. Indicators with a period come at the highest frequency they are published at unless period= says otherwise (daily, else weekly, monthly, quarterly, yearly); house prices, rent prices, the household savings rate and the household debt-to-income ratio come quarterly from the OECD (quarterly=false for yearly); get_real_interest_rate is monthly (period='yearly' for annual), the nominal rate minus inflation with rate_type='long_term' (default), 'short_term' or 'policy' (the central bank rate, incl. 'Euro Area'); the others are yearly. quarterly=true returns quarterly data only where a source has it (a note says when it does not). Supports rolling=N (moving-average smoothing) and trailing=N (trailing N-period sum, e.g. a trailing-4-quarter sum) on the raw series. get_gross_domestic_product_growth returns the latest quarterly real GDP growth (quarter on quarter, or year_over_year=true). get_shiller_stock_market_data returns Robert Shiller's monthly US stock market data from 1871 (price, dividend, earnings, CPI, long rate, CAPE; no countries needed). get_supply_chain_pressure_index returns the New York Fed's Global Supply Chain Pressure Index, monthly from 1998, in standard deviations from its average (not a decimal; a 'World' column, no countries needed). get_exchange_rates returns each country's currency per US dollar (e.g. countries='Japan' for yen per dollar, not a currency pair; for a pair such as EURUSD use the market_data tool with tickers='EURUSD'), defaults to daily rates and accepts end_of_period=true for month-, quarter- or year-end rates (BIS, about a week behind). For the change of currencies against the dollar up to the latest close, use the market_data tool with tickers quoted in dollars ('EURUSD,GBPUSD,JPYUSD,CNYUSD,CHFUSD') and their Cumulative Return. get_commercial_real_estate_prices covers around twenty economies (BIS). get_credit_to_gdp_gap (the Basel III credit gap), get_debt_service_ratio and get_credit_to_gdp_ratio come quarterly from the BIS, for around 45, 30 and 45 economies; borrowers='private' (default), 'households' or 'corporations' selects the sector (get_credit_to_gdp_ratio also 'government' and 'non_financial'). get_inflation_rate and get_consumer_price_index default to monthly data (period='yearly' for annual) (sources: Eurostat incl. the euro area flash estimate, the ONS for the United Kingdom, the Statistics Bureau of Japan, and the BIS for around sixty other countries incl. the United States, China, India and Brazil; the US months the BLS has released since the latest BIS update are added, so a CPI release appears the same day). measure='core' (all items less food and energy) or a component, 'energy', 'food', 'goods', 'services' or 'shelter' (US only), returns those monthly for the United States (BLS CPI-U, not seasonally adjusted; about the last three years without a FRED key) and the euro area and European countries (Eurostat HICP). get_consumer_price_index also accepts oecd_source=true for monthly/quarterly OECD data only. get_consumer_price_index with cumulative=true returns the growth of 1 in prices since the first period of the date range (1.346 for prices 34.6% higher). get_purchasing_power returns what 100 at start_date buys in every later month, in start_date prices (100 × CPI(start) / CPI(t), e.g. 74.29 when prices rose 34.6%; period='yearly' for annual averages); overnight_rate=true deposits the 100 at the currency's overnight rate compounded daily (€STR for the Euro Area and its members, SONIA, TONA, SOFR; monthly only), the real value of cash, with countries without an overnight rate left out with a note; each month's cash value is paired with that same month's CPI, so months whose CPI is not yet published are left out. get_producer_price_index, get_export_price_index and get_import_price_index return monthly indices (period='quarterly' or 'yearly' for averages) from the official publishers: Eurostat for the euro area, the EU and around 35 European countries, the BLS for the United States (about the last three years without a FRED key) and the Bank of Japan; growth=true with lag=12 gives the year-on-year change. China has no producer price index there: get_economic_calendar with countries='China' and events='Producer Price' has its monthly year-on-year release. get_commodity_prices returns the World Bank's monthly average prices in US dollars from 1960 (the Pink Sheet, no countries needed): commodity= e.g. 'Gold', 'Crude oil Brent', 'Crude oil WTI', 'Copper', 'Natural gas Europe' (the World Bank's names without commas, about seventy; all when left out), in $/troy oz for precious metals, $/bbl for oil, $/mmbtu for gas and $/mt for base metals and grains; deflate_with='United States' gives real prices in the money of the latest month of that country's CPI up to end_date (e.g. gold in 1980 against today's), and econometrics takes the same with series='macroeconomics:get_commodity_prices:Gold' and deflate_with='United States' (e.g. get_level_significance with level= for the first month above the 1980 peak). get_chokepoint_transits returns IMF PortWatch's daily ship transits through 28 maritime chokepoints from 2019 (no countries needed): chokepoints= e.g. 'Strait of Hormuz,Suez Canal,Bab el-Mandeb Strait,Cape of Good Hope,Panama Canal' (a part such as 'Hormuz' works; all when left out), a column per ship category (Container, Dry Bulk, General Cargo, Ro-Ro, Tanker, Cargo = all but tankers, Total) and per chokepoint when there are several; show_columns='Tanker' keeps one category. measure='transits' (number of ships, default) or 'trade_volume' (estimated cargo in metric tons); period='weekly', 'monthly', 'quarterly' or 'yearly' sums the days (complete periods only). Updated weekly; days are UTC. get_commodity_forward_curve and get_commodity_term_structure take commodity= instead of countries= ('Crude Oil', 'Natural Gas', 'Gold', 'Silver', 'Copper', 'Corn', 'Wheat' or 'Soybeans', comma-separated for several; all eight when left out). get_commodity_forward_curve returns the daily settlement of each dated futures contract listed today (columns are delivery months, e.g. '2026-12'); generic=true returns the generic (nearby) curve as it stood each day instead (Front, +1, ... +11: positions ranked per day, rolling at each contract's last trading day, not interpolated to fixed maturities), and growth=true with lag=N the change of each column over N trading days. get_commodity_term_structure returns per day the front and the far contract (the last of the 12-month strip starting with the front, e.g. Dec26 against Nov27), their prices, the Spread (front minus far, positive in backwardation), the Slope (far / front - 1, a decimal), the annualised Roll Yield (ln(front / far) x 12 / months, a decimal) and Structure ('Backwardation', 'Contango' or 'Flat'); its time series gives the widest spread directly. Yahoo Finance drops a contract once it expires, so on a past date the positions (and the term structure) whose contract has expired since are empty; generic=false on get_commodity_term_structure compares today's front and far contract over their full history instead. Also includes five US-only indicators that only return a 'United States' column regardless of the countries= argument: get_industrial_production_index (Federal Reserve G.17), get_recession_indicator (NBER business cycle dates), get_retail_sales (Census Bureau, monthly from 1992), get_housing_starts (Census Bureau, monthly from 1959) and get_real_personal_income (BEA, monthly from 1959). get_economic_calendar returns scheduled economic data releases (event, previous, estimate, actual, impact) rather than a country series. By default it returns only High impact releases from the past 23 days to the coming 7 days; narrow it with countries= (e.g. 'United States') and currencies= (e.g. 'USD,EUR'), filter on event names with events= (e.g. events='PMI' for the purchasing managers' indices with consensus, or 'CPI,Unemployment'), pass impact='Medium' or 'High,Medium' for more, impact='All' for every release, and start_date/end_date for another window (keep it to a few weeks: one month of every country is over 2,000 releases). Its Unit column gives each release's unit; releases quoted in percent and its Change % column are decimals like the rest. as_series=true returns the Actual of every event by the period it covers instead of the releases by date (read from the event name: the month, quarter or year; a December figure released in January belongs to the previous year), a column per event and its consensus as ' Estimate', keeping the latest release of a period (the final figure after a flash); the default impact is High, so pass impact='All' to include Medium and Low releases. In the econometrics tool, series='macroeconomics:get_economic_calendar:China:Producer Price Index YoY' reads one such event as a series (the event name without its period as the column), every impact included; a figure published for two months at once, such as China's January and February trade, is kept once under the later month. The calendar starts in 2013 for most countries. Its Currency column is the currency of the market a release concerns, not of its value (China's balance of trade is in US dollars). Every rate and ratio this tool returns is a decimal fraction, not a percentage: an inflation rate of 4.1% comes back as 0.0412 and a debt-to-GDP ratio of 131.7% as 1.3173. Multiply by 100 before presenting them as percentages. Global Macro Database options: usd=true returns GDP, GDP per capita, consumption, investment, fixed investment, exports, imports, trade balance and current account in millions of US dollars (comparable across countries); get_total_consumption and get_total_consumption_to_gdp_ratio accept component='total', 'household' or 'government'; get_gross_domestic_product with inflation_adjusted=true returns real GDP (with usd=true in millions of US dollars at constant 2015 prices) and get_house_prices with inflation_adjusted=true real house prices. Yearly GMDB series end at the last observation; pass gmdb_forecasts=true to include the IMF projections up to five years ahead. get_implied_volatility returns volatility indices by market and maturity as decimals, no countries needed (markets='US Equity' VIX 9D-1Y from 1990, 'Euro Area Equity' VSTOXX 1M-24M from 1999, 'Emerging Markets Equity', 'US Equity Volatility' VVIX, 'US Treasury Bonds' VXTLT, 'Crude Oil', 'Gold'; with an FMP key also 'US Treasury Rates' MOVE and 'Japan Government Bonds'), period='daily', 'weekly' or 'monthly'. get_stress_test_scenario returns regulators' stress test scenarios (authority='federal_reserve' quarterly US and international variables incl. Treasury and BBB yields, equity, house prices and VIX; authority='esrb' the EBA bank stress test, yearly, every EU country plus iTraxx spreads), scenario='baseline', 'adverse' or 'historic' (Fed history from 1976), countries= optional; the scenario path is not cut to start_date/end_date. Long-horizon data: get_long_run_asset_returns returns yearly total returns 1870-2020 for 18 advanced economies (Jordà -Schularick-Taylor; asset_class='equity'|'housing'|'bonds'|'bills'|'risky'|'safe'|'wealth', real=true for real returns; licensed for non-commercial use only, so it requires accept_licence=true; countries= optional). get_millennium_of_macroeconomic_data returns the Bank of England's annual UK series from as early as 1086 to 2016 (series= e.g. 'Bank Rate,Consols,Share prices'; set start_date far back, e.g. 1700-01-01). deflate_with='United States' puts a money series in today's dollars (the latest year of that country's CPI), e.g. series='$ Oil prices'; growth=true with lag= gives the change over lag years. get_scenario_set returns De Nederlandsche Bank's pension scenario set (20,000 scenarios over 100 years, measure='real_world' or 'market_consistent'): quantiles per horizon year of nominal zero rates 1Y-30Y, the euro area 10Y real rate, equity returns and EU/NL inflation; the first call takes one to two minutes. get_asset_class_proxies returns daily total returns of listed funds tracking private equity, infrastructure, hedge funds, merger arbitrage, private credit, real estate and investment grade and high yield credit (asset_classes=, period='daily'|'weekly'|'monthly').
Inputs: indicator (required), lag, usd, rank, +45 more. Returns: result
market_dataARead-onlyIdempotentInspect
Raw financial data (historical prices, income statement, balance sheet, cash flow statement, company profile, quotes, analyst estimates (get_analyst_estimates: consensus revenue, EBITDA, EBIT, net income, SGA and EPS per period with the number of analysts behind the revenue and the EPS consensus, 'Number of Analysts Revenue' and 'Number of Analysts EPS'; far-out years often rest on a few), dividend/earnings calendars (with the scheduled dates after today, e.g. the next earnings release), statistics, market risk premium by country, CFTC Commitment of Traders report, executives and their compensation, company notes, employee count, share float, mergers and acquisitions, stock splits, insider trade statistics, institutional (13F) ownership per quarter, FINRA daily short sale volume, analyst stock grades, analyst price targets (get_price_targets: today's consensus, high, low and median with the upside to the share price, the dispersion, the revision momentum and the date of the most recent target with the days since; get_price_target_history: every published target with the upside it implied and the analyst company's previous target (published in the year before), its date and the Target Change; a target without a previous one is new coverage), monthly buy/hold/sell recommendation counts with the mean recommendation (get_analyst_recommendations), earnings call transcripts). Use this ONLY for raw data needs — for pre-computed ratios, performance, risk, or model metrics use the dedicated tools instead. Requires tickers='AAPL' — use comma-separated values for multiple tickers. basket=true adds a 'Total' to the financial statements, each line item the sum of the tickers (e.g. the combined capital expenditure of a group of companies with trailing=4 and quarterly=true; EPS and share counts stay empty). get_market_risk_premium (by country) and get_treasury_data (US Treasury rates) are market-wide and need no tickers. get_commitment_of_traders takes CFTC futures symbols, e.g. tickers='NG' (natural gas) or 'GC' (gold), not stocks. get_earnings_surprise gives per announcement the EPS and revenue against the analyst consensus (surprise as a decimal), the SUE and the share's reaction over days -1 to +1 against the benchmark. get_earnings_call_transcripts returns the full, never shortened text (often 40,000 to 60,000 characters) of one call of one ticker: the most recent, or the one of fiscal_period (e.g. '2025Q4', the company's own fiscal quarter); call it once per ticker and period. A period without a transcript is answered with the most recent periods that have one. Currency and crypto pairs may be written either way: EURUSD or EURUSD=X, BTCUSD or BTC-USD. get_short_volume is the daily short SALE volume FINRA reports for US-listed stocks (short volume, total FINRA-reported volume, short volume ratio and its z-score), not short interest; it covers the history_days (92 by default, one download per trading day) before end_date. To find which instruments exist, use the Finance Database server. The holdings, information and sector and country weightings of ETFs and funds are in the etf tool.
Inputs: indicator (required), lag, rank, limit, +25 more. Returns: result
modelsARead-onlyIdempotentInspect
Pre-computed financial models (WACC, DuPont analysis, Extended DuPont analysis, Enterprise value breakdown, intrinsic value/DCF, Gordon Growth Model, Altman Z-Score, Piotroski F-Score, Beneish M-Score, Economic Value Added (EVA), Present Value of Growth Opportunities, Sustainable Growth Rate, Internal Growth Rate, Graham Number). get_altman_z_score takes model='original' (listed manufacturers, default), 'private' (Z', book equity), 'non-manufacturing' (Z'', no sales term) or 'emerging' (Z''-EM = Z'' + 3.25), each with its own zones. get_taffler_z_score is the UK Taffler z-score (below zero is at risk). get_return_decomposition splits the share price return into EPS growth and P/E change (the multiple), plus dividends for the total return, year over year by default (lag= periods; logarithmic=true for parts that add up; NaN split when earnings are not positive). Valuation: get_reverse_discounted_cash_flow (the growth rate the share price implies, next to the historical growth), get_earnings_power_value (Greenwald's no-growth value), get_h_model (Fuller-Hsia dividend discount model with growth declining from high_growth_rate to stable_growth_rate), get_two_stage_dividend_discount_model (transition_periods= makes it three-stage), get_justified_multiples (justified trailing/leading P/E and P/B, next to the actual multiples), get_intrinsic_valuation with historical=true (the DCF value for every period), get_monte_carlo_intrinsic_valuation (percentiles of the DCF value and the probability it exceeds the price) and get_peer_comparison (valuation, margins, returns, growth and leverage against the company's peers, or peers={'AAPL': ['MSFT', 'GOOGL']}). The valuation models need no inputs: the required return defaults to each company's cost of equity (CAPM with its country's equity risk premium) and the discount rate of the DCFs to its WACC; the dividend models grow at the dividend per share growth (CAGR), the DCFs at the reinvestment rate times the return on capital, and the stable (perpetual) growth is that growth kept within 0 and 2.5%. Values per period use the rates and growth known at each period end. A company (or period) whose rate does not exceed its stable growth is left out. rate_of_return=, growth_rate= and the like override them, as one number or one per ticker ({'AAPL': 0.08}). Credit: get_merton_distance_to_default (Merton/KMV asset value, distance to default and probability of default per year), get_campbell_hilscher_szilagyi_score (Campbell-Hilscher-Szilagyi failure probability from accounting and market data: the monthly probability of failing 12 months ahead, with its eight variables, measured on each fiscal period end) and get_synthetic_credit_rating (Damodaran's rating, default spread and cost of debt from interest coverage). Quality and manipulation scores: get_magic_formula (Greenblatt ranking across the tickers given), get_mohanram_g_score (relative to the tickers given, so pass peers), get_quality_score (Quality Minus Junk: z-scores of profitability, growth, safety and payout ranked across the tickers given, at least three; growth_years= sets the growth window, so use an earlier start_date), get_dechow_f_score, get_montier_c_score and get_accruals_ratio (Sloan). weighted_average_cost_of_capital= defaults to each company's latest WACC. Requires tickers='AAPL' — use comma-separated values for multiple tickers. Supports quarterly=true and start_date/end_date. basket=true also adds up the tickers into one company, 'Total', whose models are calculated on the summed statements (e.g. the Piotroski F-Score or Altman Z-Score of a group of companies together); the models that value a share stay empty for it and the scores that rank the tickers against each other (Magic Formula, Mohanram G-Score, Quality Score) leave it out. On quarterly data the distress scores (Altman, Taffler, Ohlson, Zmijewski, Springate, Grover, Fulmer, Piotroski, Beneish) use a trailing year by default and compare with the same quarter a year earlier; trailing=1 scores single quarters. get_altman_z_score (with the cut-offs of the model asked for: original 1.81/2.99, private 1.23/2.90, non-manufacturing 1.10/2.60, emerging 4.35/5.85), get_zmijewski_score (0), get_springate_score (0.862) and get_taffler_z_score (0) add a Zone row per ticker, 'Distress', 'Grey' or 'Safe'; zone=false leaves it out. get_factor_analysis: factor analysis (predictive power) of the models across tickers: do the tickers that score high on one go on to return more than those that score low? Needs tickers= with at least ten, preferably twenty or more tickers. metrics= a model name, a comma-separated list, or a collection: 'scores' (default: Piotroski, Altman Z, Beneish M, Ohlson O, Zmijewski, Springate, Grover, Fulmer H, Taffler z, Campbell-Hilscher-Szilagyi, Dechow F, Montier C and Mohanram G) or 'all' (adds accruals ratio, Tobin's Q, growth rates, magic formula, Merton distance to default); column= picks a component instead of the score. Returns a row per metric and horizon: the mean information coefficient (IC, the Spearman rank correlation between the metric and the later returns), its standard deviation, IC information ratio, t-statistic, p-value, share of positive periods, number of periods, the Top Minus Bottom quantile spread, quantile turnover and rank autocorrelation. detail='information_coefficient', 'quantile_returns', 'quantile_turnover' or 'rank_autocorrelation' returns that part per period (or per quantile) for a single metric. period= sets how often it is evaluated (monthly by default), horizons= the periods ahead (e.g. 12 or [1, 12]), quantiles= the number of quantiles (5). Other parameters (e.g. trailing=) pass to the models. The IC is reported as measured: a negative IC means low scores go on to outperform. Scores apply from the fiscal period end, so there is no look-ahead.
Inputs: indicator (required), lag, rank, seed, +48 more. Returns: result
momentumARead-onlyIdempotentInspect
Momentum technical indicators (RSI, MACD, Stochastic Oscillator, Williams %R, Aroon, ADX, CCI, MFI, rate of change, Ichimoku Cloud, awesome, ultimate and Chande momentum oscillators, vortex, Know Sure Thing and more). Applied to price data automatically — no need to fetch prices first. Each indicator needs its window of history before it produces values, so the first periods after start_date can be empty and quarterly or yearly periods with long windows can be empty on short histories; start earlier to warm up. Requires tickers='AAPL' — use comma-separated values for multiple tickers. get_relative_strength gives the price relative to the benchmark, the Mansfield relative strength and a 1-99 relative strength rating across the tickers; get_seasonality the average return, hit rate and t-statistic per calendar month (frequency='month') or weekday (frequency='weekday'); get_signals the events per period: moving average crossovers (golden and death cross with the default 50 and 200), MACD crossovers, the RSI entering and leaving its overbought and oversold zones, Bollinger Band breakouts and new 52-week highs and lows, each 1 for a cross upwards, -1 for a cross downwards and 0 otherwise; signals_only=true returns only the periods with a signal (with limit=-5 the last five). get_indicator_summary summarises an indicator's history in one row per ticker instead of the daily series (use it rather than the full series for questions such as 'how low is the RSI compared with the last five years'): metric= the indicator (get_relative_strength_index by default, or any technical indicator, column= for one with several outputs), the latest value with its percentile and rank in its own history up to that date, the mean, minimum and maximum with their dates; below=30 (or above=70) adds the periods beyond the line, the number and last date of the crossings into that zone, and forward_periods=[5, 21, 63] the average return after those crossings next to the average return over every period; show_crossings=true lists every crossing with its value, percentile at the time and forward returns. Other parameters (e.g. window=) pass to the indicator. get_factor_analysis: factor analysis (predictive power) of the technical indicators across tickers: do the tickers that score high on one go on to return more than those that score low? Needs tickers= with at least ten, preferably twenty or more tickers. metrics= an indicator name, a comma-separated list, or a collection: 'momentum' (default), 'overlap', 'volatility', 'breadth' or 'all'; column= picks the output of a multi-output indicator (e.g. 'Signal Line'). Returns a row per metric and horizon: the mean information coefficient (IC, the Spearman rank correlation between the metric and the later returns), its standard deviation, IC information ratio, t-statistic, p-value, share of positive periods, number of periods, the Top Minus Bottom quantile spread, quantile turnover and rank autocorrelation. detail='information_coefficient', 'quantile_returns', 'quantile_turnover' or 'rank_autocorrelation' returns that part per period (or per quantile) for a single metric. period= sets how often it is evaluated (monthly by default), horizons= the periods ahead (e.g. 12 or [1, 12]), quantiles= the number of quantiles (5). Other parameters (e.g. window=) pass to the indicators; indicators in price units are used relative to the close. The IC is reported as measured: a negative IC means low values go on to outperform.
Inputs: indicator (required), lag, rank, above, +47 more. Returns: result
optionsARead-onlyIdempotentInspect
Option pricing and Greeks (Black-Scholes model, binomial tree, delta, gamma, theta, vega, rho, implied volatility). Requires tickers='AAPL' — use comma-separated values for multiple tickers. get_stock_price_simulation returns the unique price levels per time step; pass show_unique_combinations=false for every simulated path. get_binomial_model covers the strikes within 5% of the price unless strike_price_range= asks for more; strike_price_range also narrows the Greeks and get_option_chains. get_option_chains shows the nearest expiry (its Expiration Date column says which); show_expiration_dates=true lists the expiries and expiration_date= picks one. get_strategy_payoff is the P&L at expiration of an at-the-money straddle (a call and a put at the stock price, 30 days, Black-Scholes premiums) unless legs= gives a list of objects, e.g. [{'strike_price': 340, 'position': 'long'}, {'strike_price': 360, 'position': 'short'}]. Option market metrics from the live chains, per expiry (number_of_expirations= or expiration_dates=): get_put_call_ratio (volume and open interest), get_max_pain, get_implied_volatility_term_structure (at-the-money volatility), get_volatility_skew (25-delta risk reversal and butterfly) and get_implied_move (straddle-implied move and range; around_earnings=true uses the first expiry after the next earnings date). Per ticker: get_gamma_exposure (dealer GEX in dollars per 1% move and the gamma flip point; by_strike=true per strike), get_model_free_implied_volatility (the Cboe VIX method for any ticker, days=30; '^SPX' approximates the VIX) and get_volatility_risk_premium (implied minus realized volatility, and in variance units). The market metrics take the underlying price quoted with the live chain (else the last traded close) and the rates and realized volatility from the price history, so leave end_date at today; days= cannot exceed the longest listed expiry.
Inputs: indicator (required), days, legs, rank, +40 more. Returns: result
overlapARead-onlyIdempotentInspect
Overlap technical indicators drawn over the price (moving averages: get_moving_average with method='simple' (default), 'exponential', 'double_exponential', 'triangular', 'weighted' or 'hull', and the Kaufman adaptive moving average; TRIX, VWAP, Parabolic SAR, pivot points, Fibonacci retracement levels, support and resistance levels). Applied to price data automatically — no need to fetch prices first. Each indicator needs its window of history before it produces values, so the first periods after start_date can be empty and quarterly or yearly periods with long windows can be empty on short histories; start earlier to warm up. Bollinger Bands and Keltner Channels are in the volatility tool. get_candlestick_patterns recognises 15 candlestick patterns with TA-Lib's definitions (doji, hammer, hanging man, inverted hammer, shooting star, engulfing, harami, piercing line, dark cloud cover, morning and evening star, three white soldiers, three black crows, marubozu, spinning top), 1 for a bullish and -1 for a bearish pattern per period (0.8 for the weaker engulfing and harami); patterns='Hammer,Engulfing' returns only those, and signals_only=true only the periods with a pattern (with limit=-5 the last five). Requires tickers='AAPL' — use comma-separated values for multiple tickers. For the predictive power of these indicators across tickers (factor analysis), use the momentum tool with indicator='get_factor_analysis' and metrics='overlap'.
Inputs: indicator (required), lag, rank, limit, +22 more. Returns: result
performanceARead-onlyIdempotentInspect
Pre-computed risk-adjusted performance metrics (Sharpe ratio incl. standard/lo/adjusted/probabilistic/deflated methods, Sortino ratio, Alpha, Jensen's Alpha, Beta, CAPM, Treynor ratio, M2 ratio, Tracking Error, Information Ratio, Fama-French factors, period Returns, Excess Returns — get_beta takes method='blume' (Bloomberg adjusted), 'vasicek', 'dimson' (lags=), 'scholes_williams', 'upside' or 'downside' besides the default 'ols'; Returns/Excess Returns support cumulative=true for the compounded growth of 1 from the start of the date range, so the first value includes the first period's return; returns start from the first close on or after start_date, so for a year-to-date return set start_date to the last trading day of the previous year). Beta, CAPM, Alpha, Jensen's Alpha, Treynor, Sortino, M2, Tracking Error and Information Ratio support rolling=N for a rolling N-period value spanning the full history instead of one value per period (e.g. period='monthly', rolling=6 for a rolling 6-month figure). Sharpe ratios are per observation (e.g. per day within the period) unless annualize=true; method='lo' is Lo's (2002) annualized Sharpe ratio corrected for autocorrelated returns (lags= autocorrelation lags); it needs 30 or more returns per period, so use quarterly or yearly periods or rolling= of 30 or more. get_sharpe_ratio_standard_error (method='iid', 'non_normal' for skewed and fat-tailed returns, or 'gmm' for autocorrelated returns too) is on the per-observation scale. get_minimum_track_record_length is the number of return observations (trading days per period, or periods with rolling=) needed before the Sharpe ratio is significantly above benchmark_sharpe_ratio (0 by default, per observation) at confidence_level (0.95); empty when the Sharpe ratio is not above it. get_coskewness and get_cokurtosis measure how each ticker moves with the squared and cubed moves of the benchmark (method='standardized' or 'residual', Harvey-Siddique). Requires tickers='AAPL' — use comma-separated values for multiple tickers. Supports period='daily' only together with rolling=N (e.g. period='daily', rolling=60 for a rolling 60-day figure); per-period results use weekly, monthly, quarterly, or yearly. get_style_analysis and get_return_statistics also take period='daily' without rolling. get_beta_implied_return splits each period's return into Beta × Benchmark Return (the Implied Return) and the Residual, the asset's own part, with the Beta estimated from the beta_window (252 by default) daily returns before the period; it is daily by default (limit=-1 for the latest day's move) and also takes weekly, monthly, quarterly or yearly. Residual Value is the Residual in money (times the market cap at the previous close, in the ticker's trading currency; empty for ETFs and indices), Residual Percentile the share of earlier residuals that were smaller in size and Residual Largest Since the date of the last residual as large in the same direction ('the largest stock-specific fall since'), so limit=-1 judges the latest move against the whole history from start_date (two or more years back: a year for the Beta and a year of residuals for the Percentile). The factor models (get_fama_and_french_model, get_carhart_four_factor_model, get_factor_asset_correlations, get_factor_correlations) take region='United States' (default), 'Developed', 'Developed ex US', 'Europe', 'Japan', 'Asia Pacific ex Japan' or 'North America' for Ken French's regional factors. get_style_analysis is Sharpe's returns-based style analysis: every ticker gets its weights in the style indices, by default IWD, IWF, IWN, IWO (US large and small cap value and growth), AGG (bonds) and BIL (cash), or those of style_tickers= (e.g. style_tickers='IWF,IWD,AGG'; tickers outside the call are retrieved), with its in-sample R Squared, selection return and tracking error; window= for rolling weights, which adds Sharpe's out-of-sample selection return per period. get_factor_analysis: factor analysis (predictive power) of the performance metrics across tickers: do the tickers that score high on one go on to return more than those that score low? Needs tickers= with at least ten, preferably twenty or more tickers. metrics= a performance metric name, a comma-separated list, or 'all' (the default: returns, excess return, beta, Sharpe, Sortino, Treynor, information ratio, tracking error, Jensen's alpha, Calmar, Omega, win rate); each is measured within every period. Returns a row per metric and horizon: the mean information coefficient (IC, the Spearman rank correlation between the metric and the later returns), its standard deviation, IC information ratio, t-statistic, p-value, share of positive periods, number of periods, the Top Minus Bottom quantile spread, quantile turnover and rank autocorrelation. detail='information_coefficient', 'quantile_returns', 'quantile_turnover' or 'rank_autocorrelation' returns that part per period (or per quantile) for a single metric. period= sets how often it is evaluated (monthly by default), horizons= the periods ahead (e.g. 12 or [1, 12]), quantiles= the number of quantiles (5). Other parameters pass to the metrics. The IC is reported as measured: a negative IC for get_returns is short-term reversal. get_kelly_criterion is the share of capital to risk that maximizes log growth: method='discrete' (default; win rate - loss rate / payoff ratio) or 'continuous' (average excess return / variance), fraction=0.5 for half Kelly; per period, within_period=false over the whole history, or rolling=N. get_return_statistics (daily returns over the whole range by default; within_period=true per year) gives the absolute win rate, average win and loss, payoff ratio, profit factor, expectancy, longest winning and losing streaks, recovery factor and common sense ratio. get_morningstar_risk_adjusted_return (MRAR, the certainty-equivalent return Morningstar ranks funds on, gamma=2) and get_morningstar_risk (Morningstar Return minus MRAR) use monthly total returns in excess of the risk-free rate (risk_free_rate='13w' for the Treasury bill rate Morningstar uses), per calendar year (period='yearly' or 'quarterly'), over the whole range with within_period=false, or rolling=36, 60 or 120 for Morningstar's three, five and ten year figures at every month end.
Inputs: indicator (required), lag, lags, rank, +40 more. Returns: result
portfolioARead-onlyIdempotentInspect
Portfolio construction and analysis for the given tickers (at least two). Optimal weights: get_minimum_variance_weights, get_maximum_sharpe_weights, get_mean_variance_weights (target_return=, target_volatility= for the highest return at that annualized volatility, or risk_aversion=), get_risk_parity_weights (risk_budget={'AAPL': 0.5, ...} optional), get_hierarchical_risk_parity_weights (codependence='pearson'|'spearman'|'kendall' sets the correlation that is clustered, also on HERC and NCO), get_hierarchical_equal_risk_contribution_weights (HERC; clusters= or chosen automatically, linkage_method='ward'; adds the Cluster of each ticker), get_nested_clustered_optimization_weights (NCO: objective='minimum_variance'|'maximum_sharpe'|'risk_parity' within and across clusters, denoised covariance by default; adds the Cluster), get_inverse_volatility_weights, get_minimum_cvar_weights (confidence_level=), get_minimum_drawdown_weights (measure='cdar'|'maximum'|'average', confidence_level= for the CDaR; drawdowns of uncompounded returns, added as a column), get_maximum_omega_weights (minimum_acceptable_return= per period, 0 by default; adds the Omega Ratio), get_maximum_cvar_ratio_weights (confidence_level=; the excess return per period over the CVaR, adds CVaR and CVaR Ratio), get_black_litterman_weights (views={'AAPL': 0.10, 'AAPL-MSFT': 0.02}, optional view_confidences= and market_weights=; market capitalizations by default; risk_aversion=2.5 by default or 'market' for the benchmark's excess return over its variance; adds the Posterior Volatility), get_maximum_diversification_weights (adds the Diversification Ratio), get_minimum_tracking_error_weights (against the benchmark; objective='information_ratio' for the highest information ratio; adds Active Return, Tracking Error and Information Ratio) and get_growth_optimal_weights (Kelly: method='exact'|'approximate', fraction=0.5 for half Kelly with the rest in cash; adds Log Growth) and get_resampled_efficient_weights (Michaud: the average of the optimal weights over resamples=500 return histories drawn with resampling='parametric'|'bootstrap' and seed=0; objective='maximum_sharpe'|'minimum_variance'|'mean_variance'; adds the Weight Standard Deviation over the histories). Each returns per ticker and for the Portfolio the Weight, annualized Expected Return, Volatility, Sharpe Ratio and Risk Contribution. minimum_weight=/maximum_weight= bound the weights, as one number or per ticker ({'AAPL': 0.3}, the others keep 0 and 1; a negative minimum allows shorting). sector_bounds={'Technology': [0, 0.4]} and country_bounds={'United States': [0, 0.6]} bound the total weight per sector or country of the company profiles. net_exposure= sets the sum of the weights (1 by default, 0 for market neutral) and gross_exposure= caps the sum of absolute weights for long-short portfolios (1.6 for 130/30). Every optimizer and the frontier take these; risk parity and HERC take the weight, sector and country bounds, HRP only minimum_weight=/maximum_weight= (all three long only), NCO none (long only within and across clusters) and get_inverse_volatility_weights none of them. Constraints no portfolio can meet return an error that says why. current_weights={'AAPL': 0.5, 'MSFT': 0.5} (the weights held now) adds a Turnover column and, with maximum_turnover=0.2, caps the sum of absolute weight changes; get_maximum_sharpe_weights and get_mean_variance_weights also take transaction_cost=0.001 (cost per unit traded, taken from the expected return). Optimizers that use expected returns take expected_returns='mean' (default) | 'exponential' (expected_returns_span=) | 'capm' (beta to the benchmark) | 'james_stein' (Bayes-Stein shrinkage). get_efficient_frontier (points=) returns portfolios from the lowest risk to the highest return. get_optimization_backtest: a walk-forward out-of-sample backtest of the optimizers (methods='minimum_variance,maximum_sharpe,...', from minimum_variance, maximum_sharpe, mean_variance, risk_parity, hierarchical_risk_parity, hierarchical_equal_risk_contribution, nested_clustered_optimization, inverse_volatility, maximum_diversification, minimum_cvar, minimum_drawdown, maximum_omega and maximum_cvar_ratio; rebalancing='monthly'|'quarterly'|'yearly', lookback= daily returns per estimate, 252 by default, transaction_cost=, maximum_turnover=) against equal weights (1/N) and the benchmark: annualized return, volatility, Sharpe ratio, maximum drawdown, average turnover and costs (output='returns' or 'weights' for the details). For given weights (weights={'AAPL': 0.6, 'MSFT': 0.4}, equal weights when omitted): get_risk_contributions (risk_measure='volatility'|'cvar' (expected shortfall)|'semideviation' (below a zero return)|'mad' (mean absolute deviation)|'cdar' (Conditional Drawdown at Risk of uncompounded returns); contributions add up to the portfolio's measure, per period except volatility), get_portfolio_risk_metrics (annualized return and volatility, Sharpe and Sortino ratios, maximum drawdown, historical VaR and CVaR at confidence_level= of the weighted returns next to the benchmark), get_discrete_allocation (whole shares per ticker at the latest close for portfolio_value=10000, method='integer' (closest to the target amounts) | 'greedy'; Shares, Amount, Target Weight, Weight held and the Leftover Cash; short weights become short shares), get_diversification_metrics (Herfindahl-Hirschman index, effective number of assets, diversification ratio, effective number of bets), get_stress_test (returns in the Dot-com Crash, Global Financial Crisis, Euro Area Debt Crisis, 2015-2016 and 2018 Q4 sell-offs, COVID-19 Crash and 2022 Rate Shock next to the benchmark, or scenarios={'name': ['start', 'end']}), get_look_through_exposure (by='sector'|'country'|'holdings', looks through ETFs to their holdings, with the benchmark's exposure next to it) and get_brinson_attribution (allocation, selection and interaction effects by sector against the benchmark over start_date/end_date). Expected returns are historical averages unless expected_returns= says otherwise; period= sets the return frequency (daily by default). covariance= sets the covariance estimator of the weights and risk contributions: 'sample' (default), 'ledoit_wolf', 'ledoit_wolf_constant_correlation', 'ledoit_wolf_single_factor' (benchmark as the factor) or 'oas' (shrinkage, steadier weights for many tickers), 'semicovariance' (downside only), 'exponential' (recent periods weigh most; covariance_span= in periods, 180 by default) or 'denoised' (Marcenko-Pastur random matrix noise removed, steadier weights for many tickers). Weights, returns and volatilities are decimals. To follow a portfolio you hold (its trades, holdings or weights over time), use portfolio_performance.
Inputs: indicator (required), by, tau, rank, +51 more. Returns: result
portfolio_performanceARead-onlyIdempotentInspect
The value and returns of a portfolio over time, built from one of: transactions (a list of trades, e.g. [{'date': '2023-01-03', 'ticker': 'AAPL', 'volume': 10, 'price': 125.1}]; volume negative for a sale, price optional (the closing price of the day), costs and currency optional), holdings ({'AAPL': 10, 'MSFT': 5}, bought at the close of start_date), weights ({'VTI': 0.6, 'BND': 0.4}, investing initial_value on start_date and rebalancing as rebalancing= says) or preset (a classic portfolio such as '60/40', 'All Weather' or 'Permanent'; get_presets lists them). get_portfolio_overview: per position and for the Portfolio the volume, average purchase price, invested amount, latest value, return, dividends, weight, volatility, beta and alpha against the benchmark. get_portfolio_performance (period=): the return per period of each position and the Portfolio. get_positions_overview: per day the volume, invested amount, value, cumulative return and weights of each position (use limit=-5 for the latest days). get_transactions_overview (pnl_method='FIFO'|'LIFO'|'AVERAGE'): each trade with its value, return and profit and loss. get_transactions_performance (period=): how the units bought in each period did against the same purchases of the benchmark. get_money_weighted_return: the annual money-weighted return (XIRR) per position and for the Portfolio. Prices are valued in one currency (currency=, by default the currency most of the portfolio trades in). Returns, weights and rates are decimals.
Inputs: indicator (required), rank, limit, period, +13 more. Returns: result
profitabilityARead-onlyIdempotentInspect
Pre-computed profitability ratios (gross margin, operating margin, net margin, ROE, ROA, ROIC, ROCE, cash ROIC (CROIC), FCF conversion (FCF/net income, FCF/EBITDA), and the profitability factors: gross profitability (Novy-Marx GP/A), operating profitability (Fama-French RMW) and cash-based operating profitability (Ball et al.), and percent accruals (Hafzalla-Lundholm-Van Winkle: (net income - cash flow from operations) / |net income|)). Gross, operating and cash-based operating profitability and percent accruals use the trailing twelve months on quarterly data. Requires tickers='AAPL' — use comma-separated values for multiple tickers. Use instead of raw financial statements. Supports quarterly=true and start_date/end_date. basket=true also adds up the tickers into one company, 'Total', whose ratios are calculated on the summed statements (e.g. the capex coverage of a group of companies together, not an average of their ratios); per-share ratios stay empty for it. For the predictive power of these ratios across tickers (factor analysis), use the valuation tool with indicator='get_factor_analysis' and metrics='profitability'.
Inputs: indicator (required), lag, rank, limit, +11 more. Returns: result
ratesARead-onlyIdempotentInspect
Interest rate data (central bank policy rates, short/long-term rates, government bond yields, ICE BofA corporate bond series, EURIBOR, ECB rates, Federal Reserve rates, official U.S. Treasury par yield curve, yield curve slope). Requires countries='United States' — use comma-separated values for multiple countries. Do NOT use tickers= for this tool. Supports start_date/end_date. Indicators with a period come at the highest frequency they are published at unless period= says otherwise (daily, else weekly, monthly, quarterly, yearly); keep the date range short for daily series. quarterly=true returns quarterly data only where a source has it (a note says when it does not). get_central_bank_policy_rate defaults to daily rates (BIS, around fifty central banks incl. 'Euro Area'; the days since the weekly BIS update come from the Bank of England and the ECB); get_long_term_interest_rate defaults to daily 10-year yields for the United States, United Kingdom, Japan and Euro Area and to monthly otherwise; get_government_bond_yield returns monthly OECD 10-year yields (short_term=true for 3-month rates) for every OECD country; get_overnight_rate returns €STR, SONIA, TONA and SOFR (Euro Area, United Kingdom, Japan, United States) with period='daily', 'weekly' or 'monthly'. cumulative=true compounds it day by day into the growth of 1 deposited on the first day of the date range (ACT/360 for €STR and SOFR, ACT/365 for SONIA and TONA, as the ECB's compounded €STR index and the New York Fed's SOFR Index; weekly and monthly take the last day of each period). get_government_bond_yield_curve returns full government yield curves (columns per country and maturity, e.g. 3M to 30Y) for the United States, Euro Area, Germany, United Kingdom, Japan, Canada, Sweden, Norway and Australia, daily, weekly or monthly, plus the monthly 10-year yield of every other EU member (e.g. France, Italy, Spain) with period='monthly'; keep the date range short (a few weeks) or use period='monthly', since one country is up to 15 maturities per day. get_treasury_rates returns the US par yield curve; maturities= keeps some of its maturities (e.g. '2Y,10Y,30Y', from 1M to 30Y). Curve analytics on the curves of get_government_bond_yield_curve (the full history from start_date, so use period='monthly' for long ranges): get_zero_coupon_curve (zero-coupon rates bootstrapped from the par yields; United States, Euro Area, Germany, Japan, Canada, Sweden; countries= optional, United States by default), get_nelson_siegel_svensson (Svensson parameters Beta 0-3, Tau 1-2 and the fit error per date, svensson=false for the three-factor Nelson-Siegel level/slope/curvature; maturities='0.5,1,10,50' returns the fitted zero-coupon yields instead), get_yield_curve_principal_components (one country: level/slope/curvature loadings with the explained variance as the last row, scores=true for the scores per date, changes=false to analyze levels), get_short_rate_model (one country: Vasicek and CIR calibrated to the history of the short_rate='3M' yield, with the model's zero-coupon curve next to the market's; CIR needs a rate above zero throughout, so use short_rate='6M' or a later start_date for the US) and get_short_rate_simulation (one country: model='hull_white' (fits today's curve), 'vasicek' or 'cir'; short_rate=, years=, steps_per_year=, paths=; returns the mean and 5-95% percentiles per step). get_treasury_auctions returns US Treasury auction results (no countries needed; security_type='Bill'|'Cash Management Bill'|'Note'|'Bond'|'TIPS'|'FRN', security_term= e.g. '10-Year'; yield, bid-to-cover ratio, amounts and primary dealer/direct/indirect bidder shares, from 1979; keep the date range short). The central bank policy rate, short/long-term rate, overnight rate and yield curve slope indicators additionally support rolling=N (moving-average smoothing) and trailing=N (trailing N-period sum). Also includes get_mortgage_rate_30_year (Freddie Mac, US only). Inflation-linked curves, columns per country and maturity, countries= optional: get_real_yield_curve (real yields of inflation-linked government bonds: United States TIPS, United Kingdom index-linked gilts, Germany inflation-linked federal bonds at constant maturities) and get_yield_decomposition splits the nominal yield of a maturity (maturities='10Y' by default, e.g. '5Y' or '2Y,10Y') into the real yield and breakeven inflation, with the change of each part since the previous trading day, for the United States, United Kingdom and Germany (limit=-1 for the latest day: did the yield rise on real rates or on inflation compensation?). get_breakeven_inflation_expectations (market-implied inflation, nominal minus real: United States incl. 5Y5Y forward, United Kingdom RPI implied inflation, Germany as the euro area proxy), both with period='daily', 'weekly' or 'monthly'; get_inflation_expectations (survey-based longer-term inflation expectations: Germany 5Y and 10Y monthly from 1989 via Consensus Economics, Euro Area 5Y from the ECB Survey of Professional Forecasters from 1999), period='monthly' or 'quarterly'. Long-history US credit series: get_hqm_corporate_bond_yield_curve (Treasury HQM corporate curve, rate='spot' for 6 months to 100 years or 'par', monthly from 1984), get_hqm_corporate_bond_spread (HQM par minus Treasury yields at 2, 5, 10 and 30 years, from 1990, or from 1984 with a FRED API key), get_moodys_corporate_bond_yields (Aaa and Baa, daily from 1986 or period='monthly' from 1919; spread=true for the spreads over the 10-year Treasury and Baa - Aaa) and get_excess_bond_premium (Gilchrist-Zakrajšek credit spread, excess bond premium and implied recession probability, monthly from 1973). get_term_premium splits US Treasury zero-coupon yields into the expected short rate and the term premium (Adrian-Crump-Moench model of the New York Fed, columns per component and maturity 1Y to 10Y, continuously compounded decimals, daily from 1961, period='daily'|'weekly'|'monthly', maturity_years= e.g. '2,5,10'; no countries needed). Also includes get_eiopa_risk_free_rate (EIOPA Solvency II risk-free curves for the euro and 40 other currencies, 1 to 150 years, monthly from 2023; countries= e.g. 'Euro Area,United Kingdom', curve='spot_no_va'|'spot_with_va'|'shock_up'|'shock_down'; returns the 1, 2, 5, 10, 20 and 30 year maturities unless maturity_years= lists others, e.g. '1,3,7,50'), get_bank_of_england_yield_curve (UK zero-coupon spot curve, curve='nominal'|'ois', 0.5 to 40 years, daily from 1985), get_corporate_borrowing_cost (ECB cost of bank borrowing for euro area companies, monthly from 2003), get_corporate_bond_yields (monthly corporate bond yields by country: Germany all ratings from 1957 (Bundesbank), Australia A and BBB at 3, 5, 7 and 10 years from 2005 (RBA), United States Moody's Aaa/Baa with a FRED key; spread=true for the spread over government bonds), get_rating_transition_matrix (ESMA CEREP rating migration matrix of a rating agency, agency='S&P'|'Moody's'|'Fitch'|'DBRS'|'Scope'|..., rating_type='corporate'|'sovereign'|'structured_finance'|'covered_bonds', year=, horizon= years, region= e.g. 'Europe'; probabilities, withdrawal-adjusted), get_default_rates (one-year default rates per rating per year from the agency's first reported year, ESMA CEREP; slow the first time, about 30 seconds per year), get_eiopa_symmetric_adjustment (Solvency II equity dampener and type 1/type 2 equity charges, daily from 1991) and get_financial_stress_index (ECB CISS for the euro area, its members, the UK, US and China, daily from 1980). The HQM series come from the Treasury; the Moody's and ICE BofA series require a free FRED API key (get one at https://fred.stlouisfed.org/docs/api/api_key.html). The ICE BofA option-adjusted spreads are decimals like the other rates (0.0077 is 77 basis points).
Inputs: indicator (required), lag, rank, rate, +41 more. Returns: result
riskBRead-onlyIdempotentInspect
Pre-computed risk metrics (VaR incl. historic/gaussian/cornish-fisher/studentt/evt distributions, CVaR, EVaR, GARCH volatility, max drawdown, drawdown duration, drawdown recovery time, drawdown series (underwater curve, the current distance from the running high; recovery=true gives the gain needed to get back to the high instead, e.g. +25% after a 20% fall; deepest_since=true adds the last date the drawdown was as deep), drawdown table (the top= deepest drawdowns with peak, trough and recovery dates, the gain needed from the trough back to the peak and lengths in periods and in calendar days and years), Conditional Drawdown at Risk (CDaR), Tail Ratio, skewness, kurtosis, downside deviation, Variance, Volatility incl. close_to_close/parkinson/garman_klass/rogers_satchell/yang_zhang estimators, Excess Volatility). VaR, CVaR, skewness, kurtosis, CDaR, Tail Ratio, downside deviation, Variance, Volatility and Excess Volatility support rolling=N for a rolling N-period value spanning the full history instead of one value per period (e.g. period='monthly', rolling=6 for a rolling 6-month figure). Requires tickers='AAPL' — use comma-separated values for multiple tickers. Supports period='daily' for whole-series calculations; rolling and per-period outputs use weekly, monthly, quarterly, or yearly. get_copula_simulation returns 100 simulated joint draws unless n_simulations= asks for more. get_tail_dependence_coefficient pairs ticker_a= (every ticker by default) with ticker_b= (the benchmark by default). get_covar measures the tail risk of ticker= (the system, the benchmark by default) given the distress of conditioning_ticker= (every other ticker by default), so by default how much each ticker's distress adds to the benchmark's tail risk (Delta-CoVaR). get_amihud_illiquidity is the price impact per billion dollars traded (scale=1e9). get_factor_analysis: factor analysis (predictive power) of the risk metrics across tickers: do the tickers that score high on one go on to return more than those that score low? Needs tickers= with at least ten, preferably twenty or more tickers. metrics= a risk metric name, a comma-separated list, or a collection: 'anomalies' (default: volatility, maximum drawdown, skewness, Amihud illiquidity) or 'all' (adds downside deviation, kurtosis, VaR, CVaR, tail ratio, Roll spread); each is measured within every period. Returns a row per metric and horizon: the mean information coefficient (IC, the Spearman rank correlation between the metric and the later returns), its standard deviation, IC information ratio, t-statistic, p-value, share of positive periods, number of periods, the Top Minus Bottom quantile spread, quantile turnover and rank autocorrelation. detail='information_coefficient', 'quantile_returns', 'quantile_turnover' or 'rank_autocorrelation' returns that part per period (or per quantile) for a single metric. period= sets how often it is evaluated (monthly by default), horizons= the periods ahead (e.g. 12 or [1, 12]), quantiles= the number of quantiles (5). Other parameters (e.g. alpha=) pass to the metrics. The IC is reported as measured: a negative IC for the volatility is the low-volatility anomaly. get_move_significance says how unusual each move is: the return in units of the volatility of the window= returns before it, the VaR Multiple (the return divided by the size of the historic VaR at alpha=, 0.05 by default, of those returns; below -1 is a VaR exceedance), its percentile among all earlier moves and the date of the last move as large in the same direction ('the biggest fall since'); use limit=-1 for the latest day and a start_date years back for a long history.
Inputs: indicator (required), k, q, dof, +55 more. Returns: result
search_by_categoryARead-onlyIdempotentInspect
Finance Toolkit: list every metric/tool within a category of prices, financial statements, ratios and other calculations.
Args:
category: One of the category names returned by ``search_metric_categories``,
e.g. ``ratios``, ``technicals``, ``economics``, ``discovery``.
Returns:
str: Markdown table of tool names and their descriptions for the
requested category, or an error message if the category is unknown.
Inputs: category (required). Returns: result
search_metric_categoriesARead-onlyIdempotentInspect
Finance Toolkit: list the categories of what this server calculates (prices, financial statements, ratios, models, risk, economics) and how many tools each has.
Use this first to understand what is available, then call
``search_by_category`` with a specific category name.
Returns:
str: Markdown table of categories, tool counts, and descriptions.
Inputs: no named parameters. Returns: result
search_metricsARead-onlyIdempotentInspect
Finance Toolkit: search the metrics this server calculates (prices, financial statements, ratios and more) by keyword, with typo tolerance.
Supports minor typos and common financial abbreviations. Tokens
shorter than four characters bypass fuzzy matching and require an
exact substring hit.
Args:
query: Free-text search string, e.g. ``'debt'``,
``'moving average'``, ``'sharpe'``, or ``'retun on equty'``.
Returns:
str: Markdown table of matching tools sorted by relevance score,
or a guidance message when no strong matches are found.
Inputs: query (required). Returns: result
solvencyARead-onlyIdempotentInspect
Pre-computed solvency ratios (debt-to-equity, interest coverage, debt-to-assets, net debt to EBITDA), the credit ratios of the rating agencies (EBITDA interest coverage, (EBITDA - CapEx) interest coverage, cash interest coverage, funds from operations (FFO) to debt and discretionary cash flow (DCF) to debt as defined by S&P Global Ratings) and the degrees of operating, financial and total leverage (DOL, DFL, DTL: the percentage change in operating income or net income per percentage change in revenue or operating income, year over year on quarterly data). FFO and DCF to debt use the trailing twelve months on quarterly data. Requires tickers='AAPL' — use comma-separated values for multiple tickers. Use instead of raw financial statements. Supports quarterly=true and start_date/end_date. basket=true also adds up the tickers into one company, 'Total', whose ratios are calculated on the summed statements (e.g. the capex coverage of a group of companies together, not an average of their ratios); per-share ratios stay empty for it. For the predictive power of these ratios across tickers (factor analysis), use the valuation tool with indicator='get_factor_analysis' and metrics='solvency'.
Inputs: indicator (required), lag, rank, limit, +13 more. Returns: result
valuationARead-onlyIdempotentInspect
Pre-computed valuation ratios (P/E, EPS, EV/EBITDA, EV/EBIT, P/B, P/S, PEG, dividend yield, FCF yield, market cap, forward P/E, forward PEG, price to tangible book, EV to invested capital, FCF payout ratio, shareholder yield (the net payout yield: dividends plus buybacks minus issuance), and the issuance anomalies: net share issuance (Pontiff-Woodgate: log change in split-adjusted basic shares over a year), composite equity issuance (Daniel-Titman: log market cap growth minus log total return over five years) and net external financing (Bradshaw-Richardson-Sloan: equity and debt raised minus repurchases, repayments and dividends over average total assets, trailing twelve months on quarterly data)). Requires tickers='AAPL' — use comma-separated values for multiple tickers. Use instead of raw financial statements. Supports quarterly=true and start_date/end_date. basket=true adds up the tickers into one company, 'Total', whose ratios are calculated on the summed statements and the summed market cap (EV/EBITDA, FCF yield; per-share ratios such as P/E stay empty), so get_market_cap with basket=true adds a 'Total' of the tickers' market caps (share=true gives each ticker's share of it instead); show_daily=true gives the close of each day, e.g. limit=-1 for the latest. get_market_cap_to_gdp: the Buffett indicator of the tickers as one basket, their total market cap divided by the nominal GDP in US dollars of country= ('United States' by default, one country per call, e.g. country='China'), each date against the GDP of the last complete year; the tickers must be listed in US dollars. get_forward_price_earnings_ratio and get_forward_price_earnings_growth_ratio additionally require a Premium FMP subscription and are fetched on first use only; min_analysts= leaves out the periods whose EPS consensus has fewer analysts (market_data get_analyst_estimates shows the number per period). get_factor_analysis: factor analysis (predictive power) of the ratios across tickers: do the tickers that score high on one go on to return more than those that score low? Needs tickers= with at least ten, preferably twenty or more tickers. metrics= a ratio name, a comma-separated list, or a collection: 'valuation' (default: multiples, yields and market cap), 'profitability', 'solvency', 'liquidity', 'efficiency' or 'all'. Returns a row per metric and horizon: the mean information coefficient (IC, the Spearman rank correlation between the metric and the later returns), its standard deviation, IC information ratio, t-statistic, p-value, share of positive periods, number of periods, the Top Minus Bottom quantile spread, quantile turnover and rank autocorrelation. detail='information_coefficient', 'quantile_returns', 'quantile_turnover' or 'rank_autocorrelation' returns that part per period (or per quantile) for a single metric. period= sets how often it is evaluated (monthly by default), horizons= the periods ahead (e.g. 12 or [1, 12]), quantiles= the number of quantiles (5). Other parameters (e.g. trailing=) pass to the ratios. The IC is reported as measured: a negative IC means low values go on to outperform, as for a low P/E. Statement figures apply from the fiscal period end, so there is no look-ahead.
Inputs: indicator (required), lag, rank, limit, +25 more. Returns: result
volatilityARead-onlyIdempotentInspect
Volatility technical indicators (Bollinger Bands, Keltner Channels, Donchian Channels, True Range, Average True Range, Supertrend, volatility cone). Applied to price data automatically — no need to fetch prices first. Each indicator needs its window of history before it produces values, so the first periods after start_date can be empty and quarterly or yearly periods with long windows can be empty on short histories; start earlier to warm up. Requires tickers='AAPL' — use comma-separated values for multiple tickers. For the predictive power of these indicators across tickers (factor analysis), use the momentum tool with indicator='get_factor_analysis' and metrics='volatility'.
Inputs: indicator (required), lag, rank, limit, +16 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
The 28 tools are organized around clearly labeled finance domains (volatility, valuation, options, macroeconomics, etc.), and descriptions repeatedly explain boundaries such as when to use market_data rather than pre-computed ratios. Some boundaries remain blurry—risk vs. volatility vs. performance, models vs. valuation, and portfolio vs. portfolio_performance—but an agent can usually route correctly from the category labels.
Most tools are consistently named as snake_case domain or category nouns (market_data, fixed_income, portfolio_performance), which is predictable for a broad toolkit. The three search_* tools use a different verb style, but they are clearly meta/search utilities rather than part of the analytical surface.
Twenty-eight tools is heavy for a single MCP server and exceeds the comfortable 3–15 range. However, the scope is exceptionally broad—financial statements, technicals, risk, portfolio construction, fixed income, macro, rates, options, discovery—so most tools correspond to a real domain rather than redundant wrappers.
The surface covers raw market data, pre-computed ratios/models, technical and risk analytics, portfolio construction/backtesting, options, fixed income, macro/rates/government/jobs/environment data, discovery, and search/meta-navigation. No obvious lifecycle gap appears for a general finance research toolkit.
Maintenance
Related MCP Connectors
SEC filings and financial data for AI agents: 59 tools for statements, valuation and supply chains.
Market data, filings, fundamentals, macro, news and research runs for AI assistants.
SEC-filed company financials with filing citations, plus market data, for AI agents
443 finance tools, 60 prompts: quant, SEC and EU filings, fact checks, rates, odds, DeFi, macro.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI assistants with access to comprehensive financial data including real-time stock quotes, company fundamentals, financial statements, market analysis, SEC filings, and economic indicators through 253+ tools across 24 categories.558 npmApache 2.0
- AlicenseAqualityBmaintenanceAI-native quantitative trading signal engine for crypto and TradFi perpetuals. Multi-factor composite BUY/SELL/HOLD signals, cross-venue funding rate arbitrage scanning, and market regime detection powered by Hyperliquid data.11586 npm10MIT
- AlicenseAqualityCmaintenanceSEC EDGAR filing MCP for equity research agents: search 10-K/10-Q/8-K with CompanyFacts metrics, preview a free sample, and purchase full structured JSON via x402 USDC on Polygon. Public endpoint on xpay.tools.32MIT
- AlicenseAqualityBmaintenanceMCP server for the SEC-registered Savvly Longevity Benefit Fund: product info, Savvly-vs-alternative comparisons, eligibility checks, an audience-tagged Q\&A library, and retirement / lump-sum / monthly projections that render inline MCP Apps chart widgets. Hosted remote plus npm/PyPI/NuGet/OCI/MCPB.83Apache 2.0