Перейти к содержанию

Документация API и MCP

FinancialMD предоставляет финансовую отчетность, построенную на основе документов, поданных в SEC. Каждое число связано с документом, поданным в SEC, из которого оно получено, и каждое число можно прочитать таким, каким оно было известно на любую дату. Учетная запись не требуется.

Сделайте первый запрос

API — это JSON поверх HTTPS. Этот запрос возвращает последние пять годовых отчетов о прибылях и убытках Apple. Ключ не нужен.

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

Отчет — это income_statement, balance_sheet, cash_flow или supplemental. Тип периода — один из annual, quarterly, ltm или ytd.

Назовите компанию

Каждый маршрут компании принимает параметр company.

  • ticker:AAPL, или ticker:AAPL.XNAS, чтобы указать биржу
  • cik:320193, номер компании SEC
  • fmd_<id>, идентификатор, который FinancialMD даёт компании

AAPL без префикса читается как тикер, а цифры без префикса — как CIK. В ответе указано, что совпало, в meta.company.matched_by.

Прочитать значение

Успешный ответ — это { data, meta }. Число внутри data никогда не бывает само по себе. Это объект значения:

{
  "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 — это промежуток времени, в течение которого это был последний показатель из документа, поданного в SEC. restated равно true только тогда, когда более поздний документ, поданный в SEC, изменил показатель; restatement_kind в этом случае указывает, как именно. proof.id по адресу GET /proof/{id} ведет к документу, поданному в SEC, и исходным фактам, лежащим в основе значения.

Читайте прошлое таким, каким оно было известно на тот момент

  • as_of=2024-06-30 на любом маршруте чтения возвращает то, что было известно на тот момент.
  • original=true возвращает первую опубликованную версию каждого периода.
  • history=true возвращает все версии каждого периода, начиная с самой ранней.
  • GET /v1/changes?since=<timestamp> перечисляет факты, ставшие известными с этого момента.

Маршруты API

МаршрутЧто возвращает
GET /v1/companiesКаталог компаний с фильтрами и пагинацией
GET /v1/company/profileПрофиль, листинги и доступные наборы данных
GET /v1/company/metricsСтроки концептов в шаблоне компании
GET /v1/company/financials/{statement}/standardizedСтандартизированный отчет
GET /v1/company/financials/{statement}/as_reportedСобственные статьи компании с тегами
GET /v1/company/ratiosКоэффициенты, рассчитанные по отчетности, с подтверждением входных данных
GET /v1/company/ratios/daily/{ratio_id}Один коэффициент как ряд по периодам
GET /v1/company/filingsИндекс документов, поданных в SEC, компании
GET /v1/filing/{accession}Один документ, поданный в SEC
GET /v1/filing/{accession}/factsВсе сопоставленные факты, размеченные в документе, поданном в SEC
GET /v1/filing/{accession}/documentСсылки на страницы документа, поданного в SEC, на EDGAR или на его основной документ в виде HTML, PDF или изображений страниц
GET /v1/company/ownership/insidersИнсайдерские транзакции из форм 3, 4 и 5
GET /v1/company/ownership/institutionalДержатели Form 13F компании по кварталам
GET /v1/ownership/institutional/holdersМенеджеры Form 13F
GET /v1/ownership/institutional/holdingsПортфель 13F одного менеджера за квартал
GET /v1/company/splitsСплиты акций по поданным документам и подтверждают ли их цены
GET /v1/company/dividendsДивиденды на акцию, объявленные или выплаченные в каждом периоде, по поданным документам
GET /v1/events_calendarПубликации отчетности (подан 8-K Item 2.02) и ожидаемые моделью даты
GET /v1/company/eventsПункты 8-K: лента событий на основе документов, поданных в SEC
GET /v1/newsДокументы 8-K всех покрываемых компаний, сначала новые, с типами событий и уровнем важности
GET /v1/news/feedСобственная лента событий FinancialMD из всех форм SEC с событиями, с автоматически составленными заголовками, важностью и ключевыми цифрами. Не новостная лента информагентств
GET /v1/news/issuer_releasesПубликации эмитентов о себе: приложения к документам SEC, а также заголовок и ссылка из собственной ленты эмитента
GET /v1/company/call_materialsМатериалы звонков по отчетности, которые эмитент подал в SEC: релизы, подготовленные выступления, письма, презентации и расшифровка, если она была подана
GET /v1/call_material/{id}Один документ, поданный эмитентом, в виде фрагментов с разделами, репликами спикеров и тегами тем
GET /v1/calls_calendarЗвонки по отчетности, как эмитенты объявляют их в документах SEC, со ссылкой на собственную страницу вебкаста эмитента
GET /v1/search/filingsПолнотекстовый поиск по документам EDGAR с 2001 года (полнотекстовый поиск SEC EDGAR)
GET /v1/coverageКаждый набор данных с его статусом: доступен, не покрывается (лицензируется) или не создан, и что использовать вместо него
GET /v1/company/estimatesСобственные базовые оценки FinancialMD на основе моделей с интервалами и историей результатов на определенную дату (point-in-time), прогноз компании, как он указан в ее документах, поданных в SEC, и описательные сигналы. Не консенсус и не оценки аналитиков. См. методику
GET /v1/company/estimates/consensusНе покрывается: консенсусные оценки лицензируются. Возвращает 404 not_covered с альтернативами
GET /v1/company/analyst_ratingsНе покрывается: рейтинги аналитиков лицензируются. Возвращает 404 not_covered
GET /v1/company/transcriptsНе покрывается: расшифровки звонков лицензируются. Возвращает 404 not_covered
GET /v1/company/stock_prices/intradayНе покрывается: цены в реальном времени и внутридневные цены лицензируются. Возвращает 404 not_covered
GET /v1/company/logoЛоготип для идентификации компании: открыто лицензированный файл с его атрибуцией или сгенерированная плитка. JSON, SVG или PNG
GET /v1/politician_tradesСделки членов Палаты представителей США, раскрытые в периодических отчетах о сделках, как подано, вместе с официальным отчетом. Цена никогда не указывается. Использование ограничено 5 U.S.C. 13107(c)(1): читайте data.notice
GET /v1/company/segmentsФакты по сегментам в исходном виде (бизнес, география, продукт)
GET /v1/company/ownership/insider_holdersЧем владел каждый инсайдер после своего последнего Form 4 или 5
GET /v1/company/ownership/fundsФонды, владевшие компанией в своем последнем Form N-PORT
GET /v1/fundsФонды Form N-PORT с их последним отчетом
GET /v1/fund/holdingsПозиции одного фонда из Form N-PORT
GET /v1/company/kpisСкорректированные и операционные показатели, раскрытые компаниями, каждый со своей ссылкой на источник
GET /v1/company/dividend_eventsДенежные дивиденды с их датами, как подано
GET /v1/company/ownership/insider_holdingsСтроки владения из Forms 3, 4 и 5
GET /v1/fund/profileТип фонда из N-CEN и комиссии по классам его акций
GET /v1/fund/navЧистые активы фонда по месяцу отчета, заявленная месячная доходность каждого класса с нашим индексом доходности и NAV на акцию для закрытых фондов из документов, поданных в SEC. Ежедневный NAV не предоставляется
GET /v1/identifiers/xrefПо одному идентификатору — компания или фонд, к которым он относится, и другие открытые идентификаторы, каждый со своим источником
GET /v1/identifiers/masterОткрытые идентификаторы всех компаний, постранично
GET /v1/company/stock_prices/returnsЦеновая доходность, полная доходность и максимальная просадка за стандартные периоды, рассчитанные по барам на конец дня и сплитам и дивидендам из документов, поданных в SEC
GET /v1/company/identifiersLEI и FIGI с их подтверждением
GET /v1/company/stock_pricesЕжедневные бары, построенные только по сделкам на IEX. Не консолидированная лента. По умолчанию сырые; adjust=splits или adjust=total_return добавляют скорректированные значения
GET /v1/screenОтберите все покрываемые компании по показателям последнего периода
POST /v1/verifyПроверьте число по значению из документа, поданного в SEC
GET /v1/changesФакты, которые стали известны с определенного момента времени
POST /v1/request-dataРасскажите, какие данные вам были нужны и не нашлись. Ключ не нужен, никогда не тарифицируется, проверяется еженедельно. Смотрите как запросить
GET /v1/request-dataТело POST /v1/request-data принимает
GET /v1/request-data/{id}Статус запроса: новый, рассмотрен, запланирован, выполнен или wontfix
GET /v1/requestedЗапрошено и выпущено: рассмотренные запросы с количеством, без данных о заявителе
GET /proof/{id}Подтверждение для возвращаемого значения
GET /v1/company/line_itemsОдна отчетная строка по метке и периоду: детальные строки в исходном виде, показатели по сегментам, метрики компании и прогнозы
GET /v1/screen/nlСкринер на простом языке: вопрос разбирается в фильтры скринера (AI моделью или по фиксированным правилам с пометкой) и выполняется как GET /v1/screen
GET /v1/askОтвет, написанный AI, об одной компании на основе ее собственных значений из документов, поданных в SEC, при этом каждое число сверяется с указанными фактами
GET /v1/news/summaryСводка, написанная AI, о новостях за один день на основе документов, поданных в SEC, или о недавних событиях одной компании из собственной ленты событий FinancialMD; каждый пункт содержит ссылки на соответствующие документы, поданные в SEC, и каждая цифра сверена с ними
GET /v1/company/ratios/forwardКоэффициенты прогнозной оценки на основе наших собственных модельных оценок (с пометкой, что это результат модели, никогда не консенсус), с оценкой, ее интервалом и историей точности
GET /v1/company/technicalsТехнические индикаторы (скользящие средние, RSI, MACD, полосы Боллинджера, ATR, положение закрытия в диапазоне), рассчитанные по ежедневным барам с одной площадки и сплитам из документов, поданных в SEC
GET /v1/pre_ipoКомпании, подавшие документы для выхода на биржу: регистранты с S-1 или F-1 в базе до любого периодического отчета, со статусом, предлагаемым тикером и датами
GET /v1/pre_ipo/{cik}Один pre-IPO регистрант: статус и применимое правило, регистрационные документы, отмеченные им финансовые показатели и условия размещения, прочитанные из проспекта
GET /v1/fx_ratesЕжедневные справочные обменные курсы из публичных файлов Европейского центрального банка: любая доступная валюта к любой другой через евро; справочные курсы, не торгуемые котировки
GET /v1/researchНезависимые исследовательские отчёты по лицензии CC BY 4.0, также доступные без оплаты на сайте издателя: поиск по компании, коллекции, языку, словам и дате; у каждого есть резюме словами самого отчёта
GET /v1/research/{id}Один исследовательский отчёт целиком в виде структурированного Markdown: разделы, тикеры, дата, источники, лицензия и указание авторства, которое нужно сохранять при цитировании
POST /v1/feedbackРасскажите, что сработало, а что нет: заметка, оценка или причины. Ключ не нужен, плата не взимается. GET /v1/feedback описывает тело запроса
POST /v1/data-errorsСообщите о числе, которое, по вашему мнению, неверно. Оно сразу сравнивается с тем, что мы выдаем, и ежедневно — с документом, поданным в SEC. Затем отслеживайте через GET /v1/data-errors/{id}

Документ OpenAPI содержит все параметры и схемы ответов. llms.txt, llms-full.txt и файл навыка описывают то же самое для агентов; https://api.financial.md/docs — это интерактивный справочник, а https://api.financial.md/changelog перечисляет изменения.

Проверьте число

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}'

Ответ содержит verdict со значением matches, differs или unknown, значение из документа, поданного в SEC, с его подтверждением, разницу и scale_hint, если ваше число отличается на порядок.

Лимиты

Вызовы без ключа ограничены по IP-адресу в день.

  • 10 тарифицируемых вызовов: коэффициенты, скринер, проверка и любой платный маршрут, например стандартизированная отчетность, сегменты и KPI
  • 1,000 обращений к слою документов, поданных в SEC: факты как поданы, документы, поданные в SEC, данные о владении и цены
  • 1,000 обращений к метаданным: каталог, профили, метрики, подтверждения и изменения

Каждый ответ содержит RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset. Ответ 429 содержит Retry-After.

Вызовы на api.financial.md без ключа не оплачиваются. API keys входят в планы Terminal + Agent; см. API keys. Агенты также могут платить за вызов на agent.financial.md. См. Pricing.

Что покрывается

Покрытие включает компании, которые подают документы в SEC и сейчас котируются на бирже в US.

  • Стандартизированная отчетность доступна для подателей, которые отчитываются по US GAAP.
  • У подателей, которые отчитываются по IFRS, например у многих иностранных компаний, подающих Form 20-F или 40-F, есть документы, поданные в SEC, но стандартизированной отчетности пока нет.
  • Компании, которые были исключены из листинга, есть в каталоге со своей отчетностью и документами, поданными в SEC. Ищите их по CIK: поиск по тикеру и цены для них недоступны, поэтому история цен охватывает только компании, которые котируются сегодня.
  • Данные о владении берутся из документов, поданных с 1 июля 2026 года, и обновляются каждый день в 13:00 UTC по ежедневному индексу EDGAR: инсайдерские сделки из Form 3, Form 4 и Form 5 по покрываемым компаниям, а также все Form 13F-HR, поэтому отчёты 13F за новый квартал появляются по мере их подачи управляющими. Позиция 13F привязывается к компании только тогда, когда в титульной части Schedule 13D или 13G названа её ценная бумага. За квартал, закончившийся 30 июня 2026 года, так привязано 80 процентов заявленной стоимости; остальные позиции отображаются в портфеле менеджера под именем эмитента, как подано.
  • Консенсусные оценки и расшифровки earnings call не предоставляются: это лицензированные данные. Сегменты подаются как отчитано, а новости — это лента документов 8-K.

Когда компания известна, но какой-то набор данных отсутствует, API отвечает not_covered и перечисляет наборы данных, которые доступны.

Сервер MCP

Сервер MCP предоставляет тот же API в виде 57 инструментов только для чтения. Он поддерживает MCP Streamable HTTP и не требует учетной записи.

https://mcp.financial.md/mcp

Руководство по MCP перечисляет инструменты. Карта сервера предназначена для реестров.

Ошибки

Ошибка имеет вид { "error": { code, message, docs, request_id, remedies } }. Список remedies подсказывает, что делать дальше. В справочнике по ошибкам объясняется каждый код.