---
name: financial-md
description: Pull standardized or as-reported financial statements with proof back to the filing, check a number against what was filed, and read statements as they were known on a past date. Use when a task needs audited financial statement figures for a public company, a citation for a number, or point-in-time data for a backtest.
---

# FinancialMD skill

## When to use
- You need revenue, net income, assets, cash flow or any statement line for a public company, with a source you can cite.
- You have a number from somewhere else and want to know whether it matches the filing.
- You need what was known on a date (no look-ahead), or want to see restatements.

## Hosts
- https://api.financial.md: no key needed; daily limits per IP address. API keys are not issued publicly yet.
- 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.

## Recipe 1: standardized statement
1. GET https://api.financial.md/v1/company/financials/income_statement/standardized?company=ticker:AAPL&period_type=annual&limit=5
2. Read `data.periods` (most recent first) and `data.rows[]` (one per concept, in display order); `row.cells[i]` is the value object for `periods[i]`, or null.
3. Cite `value.proof.accession`, `value.proof.form`, `value.proof.filed` and the link https://financial.md/proof/{proof.id}.
Statements: income_statement, balance_sheet, cash_flow. Period types: annual, quarterly, ltm, ytd.

## Recipe 2: verify a number
POST https://api.financial.md/v1/verify with JSON `{"company":"ticker:AAPL","concept":"income_statement_total_revenues","period":"FY2024","value":391035000000,"source":"analyst note"}`.
- `verdict` is matches, differs or unknown. `delta` is `{ absolute, percent }`; `tolerance` is half a unit at the filer's precision (decimals -6 means millions).
- `scale_hint` of 6 means your number was in millions.
- Concept ids come from GET /v1/company/metrics?company=...; `metric_alias` ids are accepted too.

## Recipe 3: point in time
- Add `as_of=2024-06-30` to any read route: the answer is what was known then.
- `original=true`: first-reported values. `history=true`: every version per period, oldest first; look at `restated` and `restatement_kind`.
- GET /v1/changes?since=2026-11-01T00:00:00Z: what was learned since (pull twin of the webhook).

## Recipe 4: the filer's own line items
GET https://api.financial.md/v1/company/financials/income_statement/as_reported?company=cik:320193&period_type=annual&limit=2 returns the same grid with one row per filed line (`taxonomy`, `tag`, `dims`); annual and quarterly only.

## Recipe 5: screen every company
GET https://api.financial.md/v1/screen?filter=net_margin:0.2:,revenue_growth_yoy:0.1:&sort=roe:desc&limit=20 returns the companies whose latest annual period passes every range filter, sorted on the server, each with one value object (with proof) per metric. Bounds are raw values (0.2 is 20 percent). `total` is the whole match; `next_cursor` pages it.

## Recipe 6: one filing, every statement
GET https://api.financial.md/v1/filing/0000320193-24-000123/facts returns every mapped fact the filing tagged, grouped by statement. Share counts and per-share figures: GET https://api.financial.md/v1/company/financials/supplemental/standardized?company=ticker:AAPL.

## Rules
- Never present a value without its proof; the envelope gives you everything for a citation.
- Numbers are value objects; read `.value` and keep `.unit`, `.currency` and `.decimals`.
- Respect RateLimit-* headers; on 429 wait Retry-After seconds. On 402 read remedies.
- Company resolution: `ticker:SYM`, `ticker:SYM.MIC`, `cik:N`, `fmd_<id>`; check `meta.company.matched_by`.
- Missing a dataset, field, company or analysis? POST https://api.financial.md/v1/request-data with `{"kind":"dataset","want":"..."}`: free, no key, reviewed weekly.
- Follow a request with GET https://api.financial.md/v1/request-data/{request_id} (new, triaged, planned, done with `served_by`, or wontfix with a note). Shipped requests: https://api.financial.md/v1/requested.
- This is information, not investment advice (https://financial.md/terms).

## Budget
Each recipe is one call. Keyless: 25 metered calls a day per IP (verify), 1000 filing-layer calls a day (statements, filings). The OpenAPI document at https://api.financial.md/openapi.json has every parameter.