Dokumentacja API i MCP
FinancialMD udostępnia sprawozdania finansowe zbudowane na podstawie zgłoszeń (dokumentów złożonych w SEC). Każda liczba zawiera odnośnik do zgłoszenia (dokumentu złożonego w SEC), z którego pochodzi, a każdą liczbę można odczytać tak, jak była znana w dowolnym dniu. Konto nie jest wymagane.
Wykonaj pierwsze wywołanie
API to JSON przez HTTPS. To wywołanie zwraca pięć ostatnich rocznych rachunków zysków i strat Apple. Nie wymaga klucza.
curl "https://api.financial.md/v1/company/financials/income_statement/standardized?company=ticker:AAPL&period_type=annual&limit=5"Sprawozdanie to jedno z income_statement, balance_sheet, cash_flow lub supplemental. Typ okresu to jeden z annual, quarterly, ltm lub ytd.
Wskaż spółkę
Każda trasa spółki przyjmuje parametr company.
ticker:AAPLlubticker:AAPL.XNAS, aby wskazać giełdęcik:320193, numer spółki w SECfmd_<id>, identyfikator nadawany spółce przez FinancialMD
Samo AAPL jest odczytywane jako ticker, a same cyfry jako CIK. Odpowiedź wskazuje, co zostało dopasowane, w meta.company.matched_by.
Odczytaj wartość
Pomyślna odpowiedź ma postać { data, meta }. Liczba w data nigdy nie występuje samodzielnie. To obiekt wartości:
{
"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 to przedział czasu, w którym była to ostatnia zgłoszona wartość. restated ma wartość true tylko wtedy, gdy późniejsze zgłoszenie zmieniło tę wartość; restatement_kind określa wtedy, w jaki sposób. proof.id pod adresem GET /proof/{id} prowadzi do zgłoszenia oraz surowych faktów stojących za tą wartością.
Odczytuj przeszłość tak, jak była znana
as_of=2024-06-30na dowolnej trasie odczytu zwraca to, co było znane w danym momencie.original=truezwraca pierwszą zaraportowaną wersję każdego okresu.history=truezwraca wszystkie wersje każdego okresu, najpierw najstarsze.GET /v1/changes?since=<timestamp>wyświetla fakty poznane od tego czasu.
Endpointy
| Endpoint | Co zwraca |
|---|---|
GET /v1/companies | Katalog firm z filtrami i stronicowaniem |
GET /v1/company/profile | Profil, notowania i dostępne zbiory danych |
GET /v1/company/metrics | Wiersze pojęć w szablonie spółki |
GET /v1/company/financials/{statement}/standardized | Standaryzowane sprawozdanie |
GET /v1/company/financials/{statement}/as_reported | Własne pozycje spółki zgłaszającej z tagami |
GET /v1/company/ratios | Wskaźniki obliczone na podstawie sprawozdań, wraz z dowodami ich danych wejściowych |
GET /v1/company/ratios/daily/{ratio_id} | Jeden wskaźnik jako seria w kolejnych okresach |
GET /v1/company/filings | Indeks zgłoszeń (dokumentów złożonych w SEC) spółki |
GET /v1/filing/{accession} | Jedno zgłoszenie (dokument złożony w SEC) |
GET /v1/filing/{accession}/facts | Każdy zmapowany fakt otagowany w zgłoszeniu (dokumencie złożonym w SEC) |
GET /v1/filing/{accession}/document | Linki do stron zgłoszenia (dokumentu złożonego w SEC) w EDGAR lub do jego dokumentu głównego jako HTML, PDF albo obrazy stron |
GET /v1/company/ownership/insiders | Transakcje insiderów z Form 3, Form 4 i Form 5 |
GET /v1/company/ownership/institutional | Posiadacze spółki z Form 13F, według kwartałów |
GET /v1/ownership/institutional/holders | Menedżerowie 13F |
GET /v1/ownership/institutional/holdings | Portfel 13F jednego menedżera na kwartał |
GET /v1/company/splits | Splity akcji według zgłoszeń oraz to, czy ceny je potwierdzają |
GET /v1/company/dividends | Dywidendy na akcję zadeklarowane lub wypłacone w każdym okresie, zgodnie ze zgłoszeniami |
GET /v1/events_calendar | Publikacje wyników (złożone 8-K Item 2.02) oraz daty oczekiwane przez model |
GET /v1/company/events | Pozycje 8-K: kanał zdarzeń oparty na zgłoszeniach (dokumentach złożonych w SEC) |
GET /v1/news | Zgłoszenia 8-K wszystkich objętych spółek, od najnowszych, z typami zdarzeń i poziomem ważności |
GET /v1/news/feed | Własny kanał zdarzeń FinancialMD ze wszystkich formularzy SEC zawierających zdarzenia, z nagłówkami tworzonymi według reguł, ważnością i kluczowymi liczbami. To nie są depesze agencyjne |
GET /v1/news/issuer_releases | Materiały opublikowane przez emitentów o sobie: załączniki do zgłoszeń SEC oraz nagłówek i link z własnego kanału emitenta |
GET /v1/company/call_materials | Materiały dotyczące wyników finansowych, które emitent złożył w SEC: komunikaty, przygotowane wypowiedzi, listy, prezentacje oraz transkrypcja, jeśli ją złożył |
GET /v1/call_material/{id} | Jeden dokument złożony przez emitenta jako fragmenty z sekcjami, wypowiedziami mówców i tagami tematycznymi |
GET /v1/calls_calendar | Telekonferencje wynikowe ogłaszane przez emitentów w zgłoszeniach SEC, z linkiem do własnej strony webcastu emitenta |
GET /v1/search/filings | Wyszukiwanie pełnotekstowe w dokumentach EDGAR od 2001 roku (wyszukiwanie pełnotekstowe SEC EDGAR) |
GET /v1/coverage | Każdy zbiór danych ze swoim statusem: obsługiwany, nieobjęty (licencjonowany) lub niezbudowany, i czego używać zamiast tego |
GET /v1/company/estimates | Własne bazowe szacunki FinancialMD oparte na modelach wraz z przedziałami i historią wyników na określony dzień (point-in-time), wytyczne spółki podane w jej zgłoszeniach (dokumentach złożonych w SEC) oraz sygnały opisowe. To nie jest konsensus ani szacunki analityków. Zobacz metodę |
GET /v1/company/estimates/consensus | Nie objęte: licencjonowane są szacunki konsensusowe. Odpowiedzi 404 not_covered z alternatywami |
GET /v1/company/analyst_ratings | Nieobjęte: rekomendacje analityków są licencjonowane. Odpowiedzi 404 not_covered |
GET /v1/company/transcripts | Nieobjęte: transkrypcje telekonferencji są licencjonowane. Odpowiedzi 404 not_covered |
GET /v1/company/stock_prices/intraday | Poza zakresem: ceny w czasie rzeczywistym i śróddzienne są licencjonowane. Zwraca 404 not_covered |
GET /v1/company/logo | Logo identyfikujące firmę: plik na otwartej licencji z podaniem autorstwa lub wygenerowany kafelek. JSON, SVG lub PNG |
GET /v1/politician_trades | Transakcje członków Izby Reprezentantów USA zgłoszone w okresowych raportach transakcyjnych, zgodnie ze złożonymi dokumentami, wraz z oficjalnym raportem. Nigdy nie wyceniane. Użycie jest ograniczone przez 5 U.S.C. 13107(c)(1): przeczytaj data.notice |
GET /v1/company/segments | Fakty segmentowe zgodne ze złożonymi raportami (działalność, geografia, produkt) |
GET /v1/company/ownership/insider_holders | Co każdy insider posiadał po swoim ostatnim Form 4 lub 5 |
GET /v1/company/ownership/funds | Fundusze posiadające spółkę w swoim najnowszym Form N-PORT |
GET /v1/funds | Fundusze Form N-PORT wraz z ich najnowszym raportem |
GET /v1/fund/holdings | Pozycje funduszu z Form N-PORT |
GET /v1/company/kpis | Skorygowane i operacyjne wskaźniki raportowane przez spółkę, każdy z cytowaniem |
GET /v1/company/dividend_events | Dywidendy gotówkowe z datami zgodnie ze złożonymi dokumentami |
GET /v1/company/ownership/insider_holdings | Pozycje z Forms 3, 4 i 5 |
GET /v1/fund/profile | Typ funduszu z N-CEN oraz opłaty jego klas akcji |
GET /v1/fund/nav | Aktywa netto funduszu według miesiąca raportu, raportowana miesięczna stopa zwrotu każdej klasy z naszym indeksem zwrotu oraz NAV na akcję dla funduszy zamkniętych, ze zgłoszeń SEC. Dzienne NAV nie jest udostępniane |
GET /v1/identifiers/xref | Dla jednego identyfikatora: spółka lub fundusz, który on oznacza, oraz pozostałe otwarte identyfikatory, każdy ze swoim źródłem |
GET /v1/identifiers/master | Otwarte identyfikatory każdej firmy, stronicowane |
GET /v1/company/stock_prices/returns | Zwrot cenowy, całkowity zwrot i maksymalne obsunięcie w standardowych oknach, obliczane na podstawie dziennych barów na koniec dnia oraz splitów i dywidend ze zgłoszeń SEC |
GET /v1/company/identifiers | LEI i FIGI ze swoimi dowodami |
GET /v1/company/stock_prices | Dzienne bary zbudowane wyłącznie na podstawie transakcji na IEX. Nie z taśmy skonsolidowanej. Domyślnie surowe; adjust=splits lub adjust=total_return dodaje skorygowane wartości |
GET /v1/screen | Przesiej każdą objętą spółkę według wskaźników z ostatniego okresu |
POST /v1/verify | Porównaj liczbę z wartością zgłoszoną |
GET /v1/changes | Fakty, które stały się znane od danego momentu |
POST /v1/request-data | Powiedz nam, jakich danych potrzebowałeś i nie znalazłeś. Bez klucza, nigdy płatne, przeglądane co tydzień. Zobacz jak poprosić o dane |
GET /v1/request-data | Ciało POST /v1/request-data przyjmuje |
GET /v1/request-data/{id} | Status zgłoszenia: nowe, wstępnie ocenione, zaplanowane, gotowe lub wontfix |
GET /v1/requested | Zgłoszone i dostarczone: przejrzane zgłoszenia z liczbami, bez danych zgłaszającego |
GET /proof/{id} | Dowód dla udostępnionej wartości |
GET /v1/company/line_items | Jedna raportowana pozycja według etykiety i okresu: szczegółowe pozycje zgodne ze złożonym raportem, dane segmentowe, metryki spółki i prognozy |
GET /v1/screen/nl | Screening w prostym języku: pytanie jest przekształcane w filtry screenera (przez model AI lub według stałych reguł, z oznaczeniem) i uruchamiane jako GET /v1/screen |
GET /v1/ask | Odpowiedź napisana przez AI o jednej spółce na podstawie jej własnych zgłoszonych wartości, z każdą liczbą sprawdzoną względem cytowanych faktów |
GET /v1/news/summary | Podsumowanie wiadomości z jednego dnia napisane przez AI na podstawie zgłoszeń (dokumentów złożonych w SEC) albo ostatnich wydarzeń jednej spółki, pochodzące z własnego strumienia zdarzeń FinancialMD; każdy punkt odwołuje się do swoich zgłoszeń (dokumentów złożonych w SEC), a każda liczba jest z nimi sprawdzona |
GET /v1/company/ratios/forward | Wskaźniki wyceny forward oparte na naszych własnych szacunkach modelowych (oznaczonych jako wynik modelu, nigdy konsensus), wraz z szacunkiem, jego przedziałem i historią trafności |
GET /v1/company/technicals | Wskaźniki techniczne (średnie kroczące, RSI, MACD, pasma Bollingera, ATR, pozycja ceny zamknięcia w zakresie) obliczane na podstawie dziennych barów z jednego rynku i splitów ze zgłoszeń SEC |
GET /v1/pre_ipo | Spółki, które złożyły dokumenty, aby wejść na giełdę: rejestranci z S-1 lub F-1 w aktach przed jakimkolwiek raportem okresowym, wraz ze statusem, proponowanym tickerem i datami |
GET /v1/pre_ipo/{cik} | Jeden rejestrant przed IPO: status i jego reguła, zgłoszenia rejestracyjne, oznaczone przez niego dane finansowe oraz warunki oferty odczytane z prospektu |
GET /v1/fx_rates | Dzienne referencyjne kursy wymiany z publicznych plików Europejskiego Banku Centralnego, każda udostępniana waluta względem każdej innej przez euro; kursy referencyjne, nie kwotowania transakcyjne |
GET /v1/research | Niezależne raporty badawcze na licencji CC BY 4.0, dostępne też bez opłat na stronie wydawcy: wyszukiwanie według spółki, kolekcji, języka, słów i daty, każdy z podsumowaniem własnymi słowami raportu |
GET /v1/research/{id} | Jeden pełny raport badawczy jako uporządkowany Markdown: sekcje, tickery, data, źródła, licencja oraz atrybucja, którą należy zachować przy cytowaniu |
POST /v1/feedback | Powiedz nam, co zadziałało, a co nie: notatka, ocena lub powody. Bez klucza, bez opłat. GET /v1/feedback opisuje treść żądania |
POST /v1/data-errors | Zgłoś liczbę, która Twoim zdaniem jest błędna. Jest ona od razu porównywana z tym, co udostępniamy, oraz codziennie ze zgłoszeniem w SEC. Następnie śledź ją przez GET /v1/data-errors/{id} |
Dokument OpenAPI zawiera każdy parametr i schemat odpowiedzi. llms.txt, llms-full.txt oraz plik skill opisują to samo dla agentów; https://api.financial.md/docs to interaktywna dokumentacja referencyjna, a https://api.financial.md/changelog zawiera listę zmian.
Sprawdź liczbę
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}'Odpowiedź zawiera verdict o wartości matches, differs lub unknown, wartość ze zgłoszenia wraz z jej dowodem, różnicę oraz scale_hint, gdy Twoja liczba różni się o rząd wielkości.
Limity
Wywołania bez klucza są limitowane na adres IP, dziennie.
- 10 wywołań taryfowanych: wskaźniki, screening, weryfikacja i każda płatna ścieżka, np. standaryzowane sprawozdania finansowe, segmenty i KPI
- 1,000 odczytów warstwy zgłoszeń: fakty as-reported, zgłoszenia, dane o akcjonariacie i ceny
- 1,000 odczytów metadanych: katalog, profile, metryki, dowody i zmiany
Każda odpowiedź zawiera RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset. Odpowiedź 429 zawiera Retry-After.
Wywołania na api.financial.md bez klucza nigdy nie są płatne. Klucze API są dostępne w planach Terminal + Agent; zobacz klucze API. Agenci mogą też płacić za wywołanie na agent.financial.md. Zobacz Cennik.
Co jest objęte
Zakres obejmuje spółki, które składają dokumenty w SEC i są dziś notowane na giełdzie w USA.
- Ustandaryzowane sprawozdania są dostępne dla podmiotów raportujących według US GAAP.
- Podmioty raportujące według IFRS, takie jak wiele zagranicznych spółek składających 20-F lub 40-F, mają zgłoszenia, ale jeszcze nie mają ustandaryzowanych sprawozdań.
- Spółki wycofane z giełdy są w katalogu wraz ze swoimi sprawozdaniami i zgłoszeniami. Szukaj ich po CIK: nie mają wyszukiwania po tickerze ani cen, więc historia cen obejmuje tylko spółki notowane dziś.
- Dane o akcjonariacie pochodzą ze zgłoszeń składanych od 1 lipca 2026 roku i są aktualizowane codziennie o 13:00 UTC na podstawie dziennego indeksu EDGAR: transakcje insiderów z Form 3, Form 4 i Form 5 dla objętych spółek oraz każdy Form 13F-HR, więc raporty 13F za nowy kwartał pojawiają się w miarę ich składania przez zarządzających. Pozycja 13F jest powiązana ze spółką tylko wtedy, gdy strona tytułowa Schedule 13D lub 13G podaje nazwę jej papieru wartościowego. Dla kwartału zakończonego 30 czerwca 2026 roku pozwala to powiązać 80 procent zgłoszonej wartości; pozostałe pozycje pojawiają się w portfelu zarządzającego pod nazwą emitenta zgodnie ze zgłoszeniem.
- Nie udostępniamy konsensusowych szacunków ani transkryptów earnings call: oba to dane licencjonowane. Segmenty są podawane zgodnie ze zgłoszeniami, a wiadomości to strumień zgłoszeń 8-K.
Gdy firma jest znana, ale brakuje zbioru danych, API odpowiada not_covered i wymienia posiadane zbiory danych.
Serwer MCP
Serwer MCP udostępnia to samo API w 57 narzędziach tylko do odczytu. Obsługuje MCP Streamable HTTP i nie wymaga konta.
https://mcp.financial.md/mcpPrzewodnik MCP zawiera listę narzędzi. Karta serwera jest przeznaczona dla rejestrów.
Błędy
Błąd ma postać { "error": { code, message, docs, request_id, remedies } }. Lista remedies mówi, co zrobić dalej. Dokumentacja błędów wyjaśnia każdy kod.