financialmodelingprep

Retrieve, verify, and cite accurate company financial data from Financial Modeling Prep, including quotes, profiles, statements, ratios, valuation, history,...

Simon-Pierrre Boucher@simonpierreboucher02

Install

openclaw skills install @simonpierreboucher02/financialmodelingprep-al

Financial Modeling Prep (FMP) Skill

Instructional knowledge that teaches an AI agent how to use the Financial Modeling Prep (FMP) financial-data API correctly, safely, and with rigor. This is guidance, not executable code.

1. Skill name

financialmodelingprep — "Use FMP for company financial data: quotes, profiles, statements, ratios, key metrics, valuation, price history, and calendars."

2. Purpose

Teach the agent to retrieve, ground, and cite financial data from FMP. The agent must:

Resolve a company name to the correct ticker before pulling data.
Pull quotes, company profiles, financial statements, ratios, key metrics, valuation (DCF), price history, and earnings/analyst data.
Report only numbers actually returned by the API — never fabricate, estimate silently, or "remember" figures.
Always cite the symbol, period, filingDate, currency, and as-of date.
Handle errors and rate limits gracefully, control cost, protect the API key, and include a not-investment-advice disclaimer.

The agent's value is accuracy and traceability, not opinion. Treat every figure as something a user could audit against the API response.

3. When to use FMP

Use FMP when the user asks for:

A stock quote or current price for a covered ticker.
A company profile/overview (sector, industry, description, market cap, CEO, exchange, currency).
Financial statements — income statement, balance sheet, cash flow (annual or quarterly).
Financial ratios or key metrics (P/E, margins, ROE, debt ratios, per-share figures).
A valuation reference such as discounted cash flow (DCF).
Historical end-of-day prices over a date range.
Earnings calendar dates or analyst estimates.
Resolving a company name to a ticker (symbol/name search).

Prefer FMP when the task is fundamental analysis, screening inputs, or grounded company snapshots.

4. When NOT to use FMP

Do not use FMP (or stop and explain the limitation) when:

The user needs real-time tick-level / sub-second trading data or order execution. FMP returns delayed/EOD-grade data, not a trading feed.
The asset is not covered by FMP or by the user's plan (many international tickers, exotic instruments, private companies).
The task requires licensed redistribution of data to third parties, bulk resale, or building a competing data product — that is a licensing matter outside this skill; do not assume it is permitted.
The user wants personalized investment advice or recommendations — provide data with a disclaimer instead (see §16).
A non-financial question is asked — use another tool/source.

When out of scope, say so plainly and suggest the correct alternative rather than forcing FMP.

5. Required environment variables

FMP_API_KEY — required. The API key for FMP. Read it from the environment at call time.
Authentication: pass as the apikey query parameter (or header where supported) on every request.
Base URL: https://financialmodelingprep.com/stable/
Method: GET only. Responses are JSON (usually a JSON array).

Never hardcode, print, log, or echo the key. Never include it in citations, examples, error messages, or output shown to the user. See §15.

6. Available operations

The financialmodelingprep-mcp server is complete and live-tested: it exposes 12 tools — eleven focused tools for common workflows plus one generic passthrough (fmp_request) that reaches all 263 FMP /stable endpoints. Prefer the MCP tools when present; the HTTP column shows the underlying endpoint for direct-GET fallback.

#	Operation	MCP tool	HTTP endpoint (`/stable/...`)
1	Symbol/name search (auto symbol→name fallback)	`fmp_search`	`/search-symbol?query=`, `/search-name?query=`
2	Quote	`fmp_quote`	`/quote?symbol=`
3	Company profile	`fmp_company_profile`	`/profile?symbol=`
4	Income statement	`fmp_income_statement`	`/income-statement?symbol=&period=&limit=`
5	Balance sheet	`fmp_balance_sheet`	`/balance-sheet-statement?symbol=&period=&limit=`
6	Cash flow	`fmp_cash_flow`	`/cash-flow-statement?symbol=&period=&limit=`
7	Ratios	`fmp_ratios`	`/ratios?symbol=&period=&limit=`
8	Key metrics	`fmp_key_metrics`	`/key-metrics?symbol=&period=&limit=`
9	Valuation (DCF)	`fmp_dcf`	`/discounted-cash-flow?symbol=`
10	Historical prices (EOD)	`fmp_historical_prices`	`/historical-price-eod/full?symbol=&from=&to=`
11	Company screener	`fmp_screener`	`/company-screener?...`
12	Anything else (263 endpoints)	`fmp_request`	any `/stable/<endpoint>` (e.g. `treasury-rates`, `dividends`, `senate-trading`, `news/stock-latest`)

Common parameters: period ∈ annual | quarter; limit controls how many periods/rows return; from/to are YYYY-MM-DD. The server validates inputs, preserves as-of dates, redacts the key, and surfaces typed errors (auth, validation, rate_limit, plan_restricted, timeout, server).

6a. The generic `fmp_request` tool (full 263-endpoint surface)

Tools 1–11 cover the common equity-research path. fmp_request is the escape hatch for the entire rest of FMP — treasury rates, dividends, stock splits, insider trading, senate/house trading, ETF holdings, economic indicators, news, earnings-call transcripts, and the long tail of the 263 /stable endpoints.

Inputs: endpoint (the path after /stable/, validated to a safe path shape) and an optional params object of query parameters.

json

{ "endpoint": "treasury-rates", "params": { "from": "2025-01-01", "to": "2025-03-31" } }
{ "endpoint": "dividends", "params": { "symbol": "AAPL" } }
{ "endpoint": "senate-trading", "params": { "symbol": "AAPL" } }
{ "endpoint": "news/stock-latest", "params": { "limit": 20 } }

When to prefer a dedicated tool. If a dedicated tool exists for what you need — quote, profile, income statement, balance sheet, cash flow, ratios, key metrics, DCF, historical prices, screener, or search — use it instead of fmp_request. Dedicated tools add input validation, output normalization (e.g. as-of fields), and clearer errors. Reach for fmp_request only when no dedicated tool fits.

Catalog. The complete endpoint list with parameters and response shapes lives in the API docs at api-docs/09-all-endpoints/ (search & directory, company & profile, quotes, prices & history, metrics/valuation/analyst, ownership/SEC/government, ETFs & funds, screeners & movers). Consult it to pick the right endpoint and params rather than guessing.

All numeric-integrity, citation, freshness, security, and compliance rules below apply equally to data returned by fmp_request.

7. Symbol resolution workflow

Never pull data for a guessed ticker. Tickers are ambiguous (e.g. "Apple" vs "Applied"; same name on multiple exchanges; ADRs).

Resolve symbols with fmp_search first. Before any quote/statement/metric call, run fmp_search to turn a name or fuzzy ticker into a canonical symbol. fmp_search already tries /search-symbol and automatically falls back to /search-name, so a single call handles both a partial ticker and a company name. Use the resolved symbol for every downstream tool.

If the user gave an exact, obviously valid ticker (e.g. AAPL) and you are confident, you may proceed — but still verify against the profile.
Otherwise call fmp_search (which queries /search-name / /search-symbol).
Inspect results: symbol, name, exchange/exchangeShortName, currency.
Confirm the right match — prefer the primary listing on the expected exchange and currency. If multiple plausible matches exist (different exchanges, ADR vs local), ask the user to confirm or state which one you chose and why.
Only then pull quotes/statements/etc. using the confirmed symbol.
Cross-check with /profile?symbol= — confirm companyName, exchange, and currency match the user's intent before reporting numbers.

Document the resolved symbol explicitly in the answer ("Resolved 'Apple' → AAPL on NASDAQ, USD").

8. Quote workflow

Confirm/resolve the symbol (§7).
Call /quote?symbol=<TICKER> (or fmp_quote).
Read fields: price, change, changePercentage, dayLow, dayHigh, marketCap, volume, previousClose, timestamp/exchange.
Report the price with currency and an as-of indication (use the response timestamp/exchange). Quotes are delayed, not real-time — say so if precision matters.
If the array is empty, the symbol is wrong or not covered by the plan (§13).
For multiple symbols, prefer a single batched quote call if supported instead of many calls (§14).

Example phrasing: "AAPL last price 192.34 USD (delayed quote, as of ). Source: FMP /quote."

9. Financial statements workflow

Resolve the symbol (§7).
Choose the statement endpoint: income, balance sheet, or cash flow.
Choose the period explicitly (this applies to fmp_income_statement, fmp_balance_sheet, fmp_cash_flow, fmp_ratios, and fmp_key_metrics):
- period=annual for fiscal-year data — use for year-over-year trends, long histories, and "last N years" requests.
- period=quarter for quarterly data — use for recent momentum, seasonality, the latest reported quarter, or to build a TTM from the last four quarters.
- Default to annual when the user does not specify; switch to quarter only when the question is about recent/quarterly performance.
- Do not mix annual and quarterly figures in one comparison without labeling each.
Choose limit to control how many periods come back (e.g. limit=5 for 5 years/quarters). Larger limits cost more and may exceed plan history.
Identify each row's identity fields: date, period (e.g. FY, Q1), calendarYear/fiscalYear, filingDate, acceptedDate, reportedCurrency.
TTM (trailing twelve months): if the user wants TTM, use a dedicated TTM endpoint/metric if available, or sum the last four quarters — and label it "TTM" and state the four periods used. Never present a single annual figure as TTM.
Currency: always report reportedCurrency. Do not convert currencies unless asked, and if you do, cite the rate and source separately.
Cite every number with symbol + period + filingDate (§12).

Verification needed: confirm whether a separate TTM endpoint exists or whether TTM is a field within /key-metrics / /ratios.

10. Valuation workflow (DCF)

Resolve the symbol (§7).
Call /discounted-cash-flow?symbol=<TICKER>.
Read dcf (estimated intrinsic value per share) and the comparison price (Stock Price / price field).
Always add caveats. FMP's DCF is a model estimate built on assumptions (growth, discount rate, terminal value) that may not match the user's view. It is not a price target or a recommendation.
Compare DCF to the current price descriptively ("model DCF X vs market price Y") — do not conclude "buy/sell" or "undervalued, you should..." Frame as: "Per FMP's DCF model, estimated value is X versus market price Y; this is a single model's estimate, not advice."
Combine with statements/ratios for context, but keep each number cited and dated.
Include the not-investment-advice disclaimer (§16).

11. Numeric integrity rules

These are non-negotiable.

Report only numbers returned by the API. If a figure is not in the response, do not state it.
Never silently compute or estimate. If a derived value is needed (e.g. a growth rate, a margin), compute it explicitly from cited API fields, show the inputs, and label it "derived" — or prefer the API's own ratio/metric field.
Never recall numbers from memory/training. Financial data changes; only the live response is authoritative.
Show units and currency for every figure (e.g. "1.23B USD", "P/E 28.4x", "margin 24.3%"). State whether large numbers are raw, thousands, or millions per the response.
Preserve precision sensibly — do not invent decimal places the response did not provide; round transparently and say so.
If a field is null/missing, say "not reported" rather than guessing.
If two endpoints disagree, report both with their sources rather than picking silently.

12. Citation & freshness rules

Every reported number must be traceable. For each figure or block, cite:

Symbol (the resolved ticker).
Endpoint (e.g. /income-statement, /quote).
Period (FY2024, Q1 2025, or "annual/quarterly") for statements/metrics.
filingDate / acceptedDate for statement data (when the filing was made).
reportedCurrency for monetary figures.
As-of: financial data goes stale. State that data is "as of" the response timestamp or the latest period/filing, and that newer filings may exist.

Example citation: "Revenue 391.0B USD — FY2024 income statement, filingDate 2024-11-01, reportedCurrency USD (FMP). Data as of latest available filing; a newer period may exist."

Prefer giving the user enough to re-query: symbol, endpoint, period.

13. Error handling rules

Condition	Meaning / typed error	Correct agent reaction
`{"Error Message":"..."}` / `validation`	Request rejected / bad arguments	Read the message; fix the request (param/symbol/date/endpoint). Do not present partial/garbage data.
HTTP 401 / "invalid api key" / account suspended (`auth`)	Auth problem	Do not retry. Stop, tell the user the key is invalid/suspended and must be fixed. Never expose the key.
HTTP 402 (`plan_restricted`)	Endpoint not included in the current plan (e.g. `fmp_screener` or some `fmp_request` endpoints on lower tiers)	Do not retry — retrying never helps. Tell the user plainly that this endpoint requires a higher FMP plan, name the endpoint, and offer an alternative the current plan can answer if one exists.
HTTP 429 (`rate_limit`)	Rate/quota limit hit	Back off (wait/retry with delay) and cache; reduce call volume. Inform the user if limited. Do not hammer.
Empty array `[]`	No data	Likely wrong symbol or not covered by the plan (e.g. non-US on free tier). Re-resolve the symbol or explain coverage limits.
Timeout / 5xx (`timeout` / `server`)	Transient	Retry a small number of times with backoff; if persistent, report the outage. (For wide price ranges, narrow `from`/`to`.)

Rule of thumb: fix-don't-retry for 401/suspended and 402/plan_restricted (a higher plan is needed); back-off-and-cache for 429; re-resolve for empty results.

14. Cost / limit-control rules

The free tier is limited (~250 calls/day, US-only coverage). Treat calls as scarce.

Verification needed: confirm current free-tier call limits and coverage at https://site.financialmodelingprep.com/developer/docs

Cache results within a session; reuse a profile/quote you already fetched instead of re-pulling.
Batch where possible (e.g. one multi-symbol quote call rather than N single calls).
Right-size limit — request only the periods you need.
Avoid redundant pulls — resolve the symbol once, store it, reuse it.
Plan the minimal set of endpoints to answer the question before calling.
If a request would blow the budget, tell the user and propose a narrower query.

15. Security rules

Never expose FMP_API_KEY — not in answers, logs, citations, examples, code blocks, or error text.
Read the key only from the environment; do not request it from the user in plain chat or store it in files.
When showing example URLs, replace the key with apikey=YOUR_FMP_API_KEY — never the real value.
If a tool/log would echo the URL with the key, redact it.
Do not transmit the key to any non-FMP endpoint.

16. Compliance rules

This is not financial advice. Always include a disclaimer when giving valuations, comparisons, or anything a user could read as a recommendation: "This is informational data from FMP, not investment advice. Verify independently before making decisions."
No recommendations — present data and let the user decide. Do not say "buy", "sell", "you should invest".
Respect data licensing — do not facilitate bulk redistribution, resale, or building a competing dataset. Provide data for the user's own analysis.
Attribute data to FMP as the source.
Distinguish facts returned by the API from any interpretation you add (label interpretation clearly).

17. Agent behavior checklist

Before answering any FMP request, confirm:

18. Example agent workflows

A. "What's Apple trading at?"

Confident AAPL; confirm via /profile?symbol=AAPL (NASDAQ, USD).
/quote?symbol=AAPL.
Report: "AAPL 192.34 USD, +0.8% (delayed quote, as of ). Source: FMP /quote."

B. "Show me Microsoft's revenue and net income for the last 3 years."

Resolve "Microsoft" → search → MSFT (NASDAQ, USD); confirm via profile.
/income-statement?symbol=MSFT&period=annual&limit=3.
Report each year with date/period, revenue, netIncome, reportedCurrency, filingDate. Label as annual. Note data as-of latest filing.

C. "Is Tesla undervalued?"

Resolve → TSLA; confirm profile.
/discounted-cash-flow?symbol=TSLA → dcf vs market price.
Report: "FMP DCF model estimate X USD vs market price Y USD (as of ). This is one model's estimate, not advice." Add disclaimer (§16). Do not declare it under/overvalued as a conclusion.

19. Common mistakes

Guessing a ticker instead of resolving it (wrong company entirely).
Reporting a number from memory or "rounding from intuition" instead of the response.
Mixing annual and quarterly figures without labels.
Calling an annual figure "TTM".
Omitting currency or treating non-USD as USD.
Concluding "buy/undervalued" from a DCF model.
Retrying on 401/suspended (wastes calls, never fixes auth).
Retrying on 402/plan_restricted instead of telling the user a higher plan is required.
Using fmp_request when a dedicated tool exists (loses validation/normalization).
Hammering on 429 instead of backing off.
Treating an empty [] as "value is zero" instead of "no data / wrong symbol / not covered".
Exposing the API key in a URL or example.
Forgetting the not-investment-advice disclaimer.

20. Maintenance notes

FMP migrated to the /stable/ base; older /api/v3/ paths may differ. Re-verify endpoints against the docs periodically.
Free-tier limits, coverage (US-only), and pricing change — re-check before relying on them.
The financialmodelingprep-mcp server currently exposes 12 tools (11 dedicated + fmp_request). Tool names and the endpoint surface may evolve; confirm against the server's tool list and the full catalog in api-docs/09-all-endpoints/.
Keep all "Verification needed" items in sync with the live docs: https://site.financialmodelingprep.com/developer/docs
When in doubt about a field's meaning, prefer the API's own labeled field over a derived calculation.