# FinancialMD

> AI-native financial terminal for agents and the people who direct them. Financial statement data where every number carries proof back to the filing it came from. Every read is point-in-time. No account is needed.

FinancialMD serves standardized and as-reported financial statements from primary sources (SEC EDGAR first). The API is JSON over HTTPS on two hosts with identical routes:

- https://api.financial.md: no key needed; daily limits per IP address. API keys (Authorization: Bearer fmd_live_<prefix>_<secret>) are not issued publicly yet; https://financial.md/keys says when they open.
- https://agent.financial.md: reserved for per-call payment (x402), which is not switched on yet. Metered routes there answer 402 and the body points back to https://api.financial.md. Use https://api.financial.md today.
- OAuth 2.1 for MCP clients and connectors: authorization server metadata at https://api.financial.md/.well-known/oauth-authorization-server (dynamic registration, PKCE S256, no account). Its tokens carry the keyless limits in an allowance of their own.

## How to call it

Identify a company as `company=ticker:AAPL` (optionally `ticker:AAPL.XNAS`), `company=cik:320193` or `company=fmd_<id>`; a bare `AAPL` is a ticker and bare digits are a CIK. The response tells you what matched in `meta.company.matched_by`.

Every successful response is an envelope: `{ "data": ..., "meta": { request_id, as_of, company, coverage, pipeline_version, licence, terms, proof_base } }`.

Every number is a value object, never a bare number:
`{ value, unit, currency, decimals, period: {start, end, type, fiscal_year, fiscal_period}, known: {from, to}, restated, method, calc_type, proof: {id, accession, form, filed, taxonomy, tag, dims, source_url, page, anchor} }`.
Resolve any `proof.id` at GET /proof/{id} to see the filing and the raw as-reported facts behind the value.

## Point in time

- `as_of=YYYY-MM-DD` (or a timestamp) on any read route returns what was known at that instant: facts whose `known` interval contains it.
- `original=true` returns the first-reported version of each period.
- `history=true` returns every knowledge version of each period, oldest first, so restatements are visible (`restated`, `restatement_kind`).
- GET /v1/changes?since=<timestamp> lists facts whose knowledge interval opened since then.

## Routes

- GET /healthz: Liveness and database reachability
- GET /openapi.json: OpenAPI 3.1 document
- GET /llms.txt: llms.txt discovery file
- GET /skill.md: Agent skill file
- GET /llms-full.txt: The whole reference in one text file: every route, parameter, ratio formula and recipe
- GET /docs: Interactive API reference (Swagger UI over openapi.json)
- GET /changelog: Dated changelog of the API and the MCP server (Markdown)
- GET /changelog.json: The changelog as JSON
- GET /robots.txt: Crawler rules: documents open, data routes closed to crawlers
- GET /pricing.json: Prices per route, free limits and per-call payment status as JSON
- GET /v1/companies: Company directory with filters and cursor paging
- GET /v1/company/profile: Company profile, listings and available datasets
- GET /v1/company/financials/{statement}/standardized: Standardized statement with point-in-time, original and history views
- GET /v1/company/financials/{statement}/as_reported: The filer's own line items with tags and dimensions
- GET /v1/company/ratios: Ratios computed from standardized facts, each with the proofs of its inputs
- GET /v1/company/ratios/daily/{ratio_id}: One ratio as a series over periods
- GET /v1/company/metrics: Concept rows of the company's reporting template
- GET /v1/company/filings: Filing index for a company
- GET /v1/filing/{accession}: One filing by accession number
- GET /v1/filing/{accession}/document: Links to a filing's documents on EDGAR, or with format=html the primary document itself
- GET /v1/filing/{accession}/facts: Every mapped fact a filing tagged, grouped by statement, in one call
- GET /v1/company/ownership/insiders: Insider transactions of a company from Forms 3, 4 and 5, newest first
- GET /v1/company/ownership/institutional: Institutional holders of a company from Form 13F, by quarter, with the change against the prior quarter
- GET /v1/ownership/institutional/holders: Form 13F managers with their newest filing; name search and cursor paging
- GET /v1/ownership/institutional/holdings: One Form 13F manager's portfolio for a quarter
- GET /v1/company/stock_prices: Daily bars of a company's listing built from trades at IEX only: not the consolidated tape, not adjusted
- GET /v1/company/splits: Stock splits as filed in XBRL, with whether IEX prices confirm them
- GET /v1/company/dividends: Dividends per share declared or paid in each period, as filed
- GET /v1/events_calendar: Earnings releases (8-K Item 2.02 filed) and model-expected dates, for one company or all
- GET /v1/company/events: 8-K items a company filed: a filing-based event feed
- GET /v1/news: News from 8-K filings across all companies, newest first, with event type and importance per item (not wire news)
- GET /v1/search/filings: Keyword search across EDGAR documents since 2001, through SEC EDGAR full-text search
- GET /v1/coverage: Every dataset FinancialMD serves, and those it does not (licensed, not built, or waiting on a decision) with alternatives
- GET /v1/company/segments: As-reported segment facts (business, geography, product) from the SEC Financial Statement Data Sets
- GET /v1/company/ownership/insider_holders: What each insider owned after their latest Form 4 or 5 transaction
- GET /v1/company/ownership/funds: Funds holding the company in their latest Form N-PORT
- GET /v1/funds: Form N-PORT funds (series) with their latest report; name search
- GET /v1/fund/holdings: One fund's Form N-PORT holdings for a report period
- GET /v1/company/kpis: Company-reported metrics (adjusted non-GAAP measures and operating KPIs) read from earnings releases and reports, each with its exact citation
- GET /v1/company/dividend_events: Cash dividends with declaration, record, ex and pay dates as the company's filings state them, each with how it was captured and the citation
- GET /v1/company/ownership/insider_holdings: Holding lines of Forms 3, 4 and 5 as filed (a Form 3 initial statement is only these)
- GET /v1/fund/profile: A fund's type and ETF flag from Form N-CEN, and each share class's prospectus fees and expense ratio
- GET /v1/company/identifiers: LEI and FIGI identifiers of a company with their evidence
- GET /v1/screen: Screen every covered company on latest-period metrics with range filters, sorting and paging
- GET /v1/company/estimates: Not covered: consensus estimates are licensed; answers 404 not_covered with alternatives
- GET /v1/company/analyst_ratings: Not covered: analyst ratings and price targets are licensed; answers 404 not_covered
- GET /v1/company/transcripts: Not covered: call transcripts and audio are licensed; answers 404 not_covered with alternatives
- GET /v1/company/stock_prices/intraday: Not covered: real-time and intraday prices are licensed; answers 404 not_covered
- GET /v1/company/logo: Not covered: logos wait on a trademark review; answers 404 not_covered
- GET /v1/politician_trades: Not covered: politician trades wait on a legal review; answers 404 not_covered
- GET /v1/fund_letters: Not covered: fund letters are not built; answers 404 not_covered
- GET /proof/{id}: Proof for a served value and the raw facts behind it
- POST /v1/verify: Check a number against the filed value
- GET /v1/changes: Standardized facts whose knowledge interval opened since a time
- GET /v1/request-data: How to tell us what data you needed and did not find (the body POST /v1/request-data takes)
- POST /v1/request-data: Tell us what data you needed and did not find; free, keyless, never charged
- GET /v1/request-data/{id}: Status of a data request (new, triaged, planned, done, wontfix), its public note and, once done, where it is served
- GET /v1/requested: Requested and shipped: the reviewed demand items with their status and vote counts, aggregate only
- GET /v1/me: The caller's principal, plan and limits (API key required)

Standardized statements take `period_type=annual|quarterly|ltm|ytd` and `limit` (number of periods, most recent first). `data.rows[].cells` is aligned with `data.periods` (a value object or null per period; with history=true `{ versions }` oldest first). The concept ids come from GET /v1/company/metrics (with display order and formulas for subtotals). List routes return `data = { items, next_cursor }`. GET /v1/me tells a keyed caller its remaining limits.

## Verify a number

POST /v1/verify with `{ "company": "ticker:AAPL", "concept": "income_statement_total_revenues", "period": "FY2024", "value": 391035000000 }`. The answer has `verdict` (matches, differs or unknown), the filed value object with proof, `delta`, the `tolerance` derived from the filer's decimals, and a `scale_hint` when your number is off by a power of ten.

## Limits

- Keyless on api.financial.md: 25 metered calls a day per IP; metadata and the filing layer (standardized, as_reported, filings) 1000 a day per IP.
- API keys with higher limits are not issued yet. There are no paid plans.
- Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy; a 429 carries Retry-After.
- Per-call payment on agent.financial.md is not switched on yet. The x-price field in the OpenAPI document is the planned price per call, not a charge.

## Prices

Planned prices; nothing is charged until per-call payment on agent.financial.md is switched on: every per-call x402 price is at least $0.005, and answers stay within the $1 default cap of x402 v2 clients.

- fields (served): free. The filing layer and metadata (companies, profile, as_reported, filings, filing facts, ownership, funds, prices, dividends, events, identifiers, changes, proof): free, rate limited.
- standardized (served): $0.005 per call over x402; $0.002 from a funded key's credits.
- ratios (served): $0.005 per call over x402; $0.002 from a funded key's credits.
- as_filed (planned): $0.02 per call over x402.
- verify (served): $0.02 per call over x402.
- value (planned): $0.02 per call over x402.
- kpis (served): $0.05 per call over x402. Company-reported metrics with exact citations.
- segments (served): $0.05 per call over x402.
- screen (served): $0.05 per call over x402.
- peers (planned): $0.05 per call over x402.
- filing_diff (planned): $0.05 per call over x402.
- brief (planned): $0.25 per call over x402. One free a day per caller. Above the v1 x402-fetch default cap of $0.10; within the v2 cap of $1.
- research_cached (planned): $0.25 per call over x402. The latest written briefing. Above the v1 x402-fetch default cap of $0.10; within the v2 cap of $1.
- research_fresh (planned): not sold per call over x402; $2.00 from a funded key's credits. A new multi-analyst run, asynchronous with a webhook, bought with credits; not sold per call over x402 until the upto scheme is widely supported, because $2 is above every default client cap.

## What is not here

GET /v1/coverage lists every dataset with its status. Licensed data FinancialMD does not carry (Street consensus estimates, analyst ratings and price targets, earnings call transcripts and audio, real-time and intraday prices, CUSIP and ISIN, Morningstar research, wire news) is conceded, and datasets not built yet or waiting on a decision (fund letters, model estimates, politician trades, logos) are named too. Their paths (/v1/company/estimates, /v1/company/analyst_ratings, /v1/company/transcripts, /v1/company/stock_prices/intraday, /v1/company/logo, /v1/politician_trades, /v1/fund_letters) answer 404 `not_covered` at once with `error.details` { dataset, status, reason, licence, alternatives }: do not retry them; use an alternative.

## Errors

`{ "error": { "code", "message", "docs", "request_id", "remedies": [...] } }` with codes invalid_request, unknown_company, unknown_concept, not_covered (with available_datasets), rate_limited, payment_required, unauthorized, upstream_unavailable, not_found. Errors are never charged.

## Missing something?

If a dataset, field, company or analysis you need is missing, POST https://api.financial.md/v1/request-data with `{ "kind": "dataset", "want": "what you needed", "why": "the task it blocks" }` (MCP tool request_data). Free, no key, takes seconds; we review requests weekly. Unmet answers carry a remedy of kind request_data.

Similar requests merge into one demand item and count as votes. The answer carries `request_id`, `item_id`, the status and the vote counts. Follow it with GET https://api.financial.md/v1/request-data/{request_id} (MCP tool request_status): new, triaged, planned, done (with the endpoint or tool that serves it) or wontfix (with a note; licensed or terms-restricted data is not redistributed). What was requested and what shipped: https://financial.md/requested, as JSON at https://api.financial.md/v1/requested.

## Files

- OpenAPI 3.1: https://api.financial.md/openapi.json
- Skill: https://api.financial.md/skill.md
- Everything in one file: https://api.financial.md/llms-full.txt
- Interactive reference: https://api.financial.md/docs
- Changelog: https://api.financial.md/changelog
- Prices as JSON: https://api.financial.md/pricing.json
- Guide for AI agents: https://financial.md/docs/agents
- Docs: https://financial.md/docs
- Terms: https://financial.md/terms (information only, not investment advice)
- Privacy: https://financial.md/privacy
- Proof pages: https://financial.md/proof/{id}