API- und MCP-Dokumentation

Den ersten Aufruf ausführen

Die API liefert JSON über HTTPS. Dieser Aufruf gibt die letzten fünf jährlichen Gewinn- und Verlustrechnungen von Apple zurück. Dafür ist kein Schlüssel erforderlich.

curl "https://api.financial.md/v1/company/financials/income_statement/standardized?company=ticker:AAPL&period_type=annual&limit=5"

Der Abschluss ist einer von income_statement, balance_sheet, cash_flow oder supplemental. Der Periodentyp ist einer von annual, quarterly, ltm oder ytd.

Ein Unternehmen angeben

Jede Unternehmensroute akzeptiert einen company-Parameter.

• ticker:AAPL oder ticker:AAPL.XNAS, um die Börse anzugeben
• cik:320193, die Unternehmensnummer der SEC
• fmd_<id>, die ID, die FinancialMD dem Unternehmen zuweist

Ein alleinstehendes AAPL wird als Tickersymbol interpretiert, alleinstehende Ziffern als CIK. Die Antwort gibt in meta.company.matched_by an, worüber die Zuordnung erfolgte.

Einen Wert auslesen

Eine erfolgreiche Antwort ist { data, meta }. Eine Zahl innerhalb von data steht nie allein. Sie ist ein Wertobjekt:

{
  "value": 391035000000,
  "unit": "USD",
  "currency": "USD",
  "decimals": -6,
  "period": { "start": "2023-10-01", "end": "2024-09-28", "type": "annual", "fiscal_year": 2024, "fiscal_period": "FY" },
  "known": { "from": "YYYY-MM-DDThh:mm:ssZ", "to": null },
  "restated": false,
  "method": "as_filed",
  "calc_type": "as_filed",
  "proof": { "id": "p_...", "accession": "0000320193-24-000123", "form": "10-K", "filed": "2024-11-01", "taxonomy": "us-gaap", "tag": "...", "source_url": "https://www.sec.gov/..." }
}

known ist die Zeitspanne, in der dies die zuletzt eingereichte Zahl war. restated ist nur dann wahr, wenn eine spätere Einreichung bei der SEC (eingereichtes Dokument) die Zahl geändert hat; restatement_kind gibt dann an, wie. proof.id verweist über GET /proof/{id} auf die Einreichung bei der SEC (eingereichtes Dokument) und die Rohdaten hinter dem Wert.

Die Vergangenheit nach damaligem Wissensstand auslesen

• as_of=2024-06-30 gibt auf jeder Leseroute zurück, was zu diesem Zeitpunkt bekannt war.
• original=true gibt die zuerst gemeldete Version jeder Periode zurück.
• history=true gibt jede Version jeder Periode zurück, die älteste zuerst.
• GET /v1/changes?since=<timestamp> listet die seitdem bekannt gewordenen Fakten auf.

Routen

Das OpenAPI-Dokument enthält alle Parameter und Antwortschemas. llms.txt, llms-full.txt und die Skill-Datei enthalten dieselben Angaben für Agenten; https://api.financial.md/docs ist die interaktive Referenz, und https://api.financial.md/changelog listet Änderungen auf.

Eine Zahl prüfen

curl -X POST "https://api.financial.md/v1/verify" -H "content-type: application/json" \
  -d '{"company":"ticker:AAPL","concept":"income_statement_total_revenues","period":"FY2024","value":391035000000}'

Die Antwort enthält ein verdict mit dem Wert matches, differs oder unknown, den eingereichten Wert mit seinem Nachweis, die Differenz sowie einen scale_hint, wenn Ihre Zahl um eine Zehnerpotenz abweicht.

Limits

Aufrufe ohne Schlüssel sind pro IP-Adresse und Tag begrenzt.

• 25 kontingentierte Aufrufe: Kennzahlen, Screening und Verifizierung
• 1,000 Lesezugriffe auf die Einreichungsebene: Finanzberichte, Fakten wie berichtet, Einreichungen bei der SEC (eingereichte Dokumente), Beteiligungen und Kurse
• 1,000 Lesezugriffe auf Metadaten: Verzeichnis, Profile, Kennzahlen, Nachweise und Änderungen

Jede Antwort enthält RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset. Eine 429-Antwort enthält Retry-After.

API-Schlüssel mit höheren Limits werden noch nicht ausgegeben. Siehe API-Schlüssel. Aufrufe auf api.financial.md sind kostenlos. Agenten können auf agent.financial.md pro Aufruf bezahlen. Siehe Preise.

Was abgedeckt wird

Abgedeckt werden Unternehmen, die Dokumente bei der SEC einreichen und derzeit an einer US-Börse notiert sind.

• Standardisierte Finanzberichte sind für Einreicher verfügbar, die nach US GAAP berichten.
• Für Einreicher, die nach IFRS berichten, etwa viele ausländische Unternehmen, die Form 20-F oder 40-F einreichen, liegen Einreichungen bei der SEC (eingereichte Dokumente), aber noch keine standardisierten Finanzberichte vor.
• Unternehmen, deren Börsennotierung eingestellt wurde, sind mit ihren Finanzberichten und Einreichungen bei der SEC (eingereichten Dokumenten) im Verzeichnis enthalten. Suchen Sie sie anhand der CIK: Für sie gibt es weder eine Suche nach Tickersymbol noch Kurse, sodass die Kurshistorie nur derzeit börsennotierte Unternehmen abdeckt.
• Beteiligungsdaten stammen aus Einreichungen bei der SEC (eingereichten Dokumenten) seit July 1, 2026 und werden täglich um 13:00 UTC anhand des EDGAR-Tagesindex aktualisiert: Insidertransaktionen aus Form 3, Form 4 und Form 5 der abgedeckten Unternehmen sowie jede Form 13F-HR. Die 13F-Berichte eines neuen Quartals kommen somit hinzu, sobald die Vermögensverwalter sie einreichen. Eine 13F-Position wird einem Unternehmen nur dann zugeordnet, wenn das Deckblatt eines Schedule 13D oder 13G dessen Wertpapier nennt. Für das am June 30, 2026 beendete Quartal werden so 80 Prozent des berichteten Werts zugeordnet; die übrigen Positionen erscheinen im Portfolio eines Vermögensverwalters unter dem Emittentennamen wie eingereicht.
• Konsensschätzungen und Transkripte von Ergebniskonferenzen werden nicht bereitgestellt: Beides sind lizenzierte Daten. Segmente werden wie berichtet bereitgestellt, und die Nachrichten bestehen aus einem Feed von 8-K-Einreichungen bei der SEC (eingereichten Dokumenten).

Wenn ein Unternehmen bekannt ist, aber ein Datensatz fehlt, antwortet die API mit not_covered und listet die vorhandenen Datensätze auf.

MCP-Server

Der MCP-Server macht dieselbe API über 50 ausschließlich lesende Tools zugänglich. Er unterstützt MCP Streamable HTTP und erfordert kein Konto.

https://mcp.financial.md/mcp

Der MCP-Leitfaden listet die Tools auf. Die Serverkarte ist für Registries bestimmt.

Fehler

Ein Fehler hat die Form { "error": { code, message, docs, request_id, remedies } }. Die Liste remedies gibt an, was als Nächstes zu tun ist. Die Fehlerreferenz erklärt jeden Code.