Przejdź do treści

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:AAPL lub ticker:AAPL.XNAS, aby wskazać giełdę
  • cik:320193, numer spółki w SEC
  • fmd_<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-30 na dowolnej trasie odczytu zwraca to, co było znane w danym momencie.
  • original=true zwraca pierwszą zaraportowaną wersję każdego okresu.
  • history=true zwraca wszystkie wersje każdego okresu, najpierw najstarsze.
  • GET /v1/changes?since=<timestamp> wyświetla fakty poznane od tego czasu.

Endpointy

EndpointCo zwraca
GET /v1/companiesKatalog firm z filtrami i stronicowaniem
GET /v1/company/profileProfil, notowania i dostępne zbiory danych
GET /v1/company/metricsWiersze pojęć w szablonie spółki
GET /v1/company/financials/{statement}/standardizedStandaryzowane sprawozdanie
GET /v1/company/financials/{statement}/as_reportedWłasne pozycje spółki zgłaszającej z tagami
GET /v1/company/ratiosWskaź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/filingsIndeks 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}/factsKażdy zmapowany fakt otagowany w zgłoszeniu (dokumencie złożonym w SEC)
GET /v1/filing/{accession}/documentLinki 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/insidersTransakcje insiderów z Form 3, Form 4 i Form 5
GET /v1/company/ownership/institutionalPosiadacze spółki z Form 13F, według kwartałów
GET /v1/ownership/institutional/holdersMenedżerowie 13F
GET /v1/ownership/institutional/holdingsPortfel 13F jednego menedżera na kwartał
GET /v1/company/splitsSplity akcji według zgłoszeń oraz to, czy ceny je potwierdzają
GET /v1/company/dividendsDywidendy na akcję zadeklarowane lub wypłacone w każdym okresie, zgodnie ze zgłoszeniami
GET /v1/events_calendarPublikacje wyników (złożone 8-K Item 2.02) oraz daty oczekiwane przez model
GET /v1/company/eventsPozycje 8-K: kanał zdarzeń oparty na zgłoszeniach (dokumentach złożonych w SEC)
GET /v1/newsZgłoszenia 8-K wszystkich objętych spółek, od najnowszych, z typami zdarzeń i poziomem ważności
GET /v1/news/feedWł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_releasesMateriał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_materialsMateriał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_calendarTelekonferencje wynikowe ogłaszane przez emitentów w zgłoszeniach SEC, z linkiem do własnej strony webcastu emitenta
GET /v1/search/filingsWyszukiwanie pełnotekstowe w dokumentach EDGAR od 2001 roku (wyszukiwanie pełnotekstowe SEC EDGAR)
GET /v1/coverageKażdy zbiór danych ze swoim statusem: obsługiwany, nieobjęty (licencjonowany) lub niezbudowany, i czego używać zamiast tego
GET /v1/company/estimatesWł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/consensusNie objęte: licencjonowane są szacunki konsensusowe. Odpowiedzi 404 not_covered z alternatywami
GET /v1/company/analyst_ratingsNieobjęte: rekomendacje analityków są licencjonowane. Odpowiedzi 404 not_covered
GET /v1/company/transcriptsNieobjęte: transkrypcje telekonferencji są licencjonowane. Odpowiedzi 404 not_covered
GET /v1/company/stock_prices/intradayPoza zakresem: ceny w czasie rzeczywistym i śróddzienne są licencjonowane. Zwraca 404 not_covered
GET /v1/company/logoLogo identyfikujące firmę: plik na otwartej licencji z podaniem autorstwa lub wygenerowany kafelek. JSON, SVG lub PNG
GET /v1/politician_tradesTransakcje 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/segmentsFakty segmentowe zgodne ze złożonymi raportami (działalność, geografia, produkt)
GET /v1/company/ownership/insider_holdersCo każdy insider posiadał po swoim ostatnim Form 4 lub 5
GET /v1/company/ownership/fundsFundusze posiadające spółkę w swoim najnowszym Form N-PORT
GET /v1/fundsFundusze Form N-PORT wraz z ich najnowszym raportem
GET /v1/fund/holdingsPozycje funduszu z Form N-PORT
GET /v1/company/kpisSkorygowane i operacyjne wskaźniki raportowane przez spółkę, każdy z cytowaniem
GET /v1/company/dividend_eventsDywidendy gotówkowe z datami zgodnie ze złożonymi dokumentami
GET /v1/company/ownership/insider_holdingsPozycje z Forms 3, 4 i 5
GET /v1/fund/profileTyp funduszu z N-CEN oraz opłaty jego klas akcji
GET /v1/fund/navAktywa 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/xrefDla 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/masterOtwarte identyfikatory każdej firmy, stronicowane
GET /v1/company/stock_prices/returnsZwrot 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/identifiersLEI i FIGI ze swoimi dowodami
GET /v1/company/stock_pricesDzienne 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/screenPrzesiej każdą objętą spółkę według wskaźników z ostatniego okresu
POST /v1/verifyPorównaj liczbę z wartością zgłoszoną
GET /v1/changesFakty, które stały się znane od danego momentu
POST /v1/request-dataPowiedz 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-dataCiało POST /v1/request-data przyjmuje
GET /v1/request-data/{id}Status zgłoszenia: nowe, wstępnie ocenione, zaplanowane, gotowe lub wontfix
GET /v1/requestedZgł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_itemsJedna 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/nlScreening 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/askOdpowiedź 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/summaryPodsumowanie 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/forwardWskaź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/technicalsWskaź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_ipoSpół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_ratesDzienne 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/researchNiezależ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/feedbackPowiedz 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-errorsZgł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/mcp

Przewodnik 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.