Documentação da API e do MCP

Faça a primeira chamada

A API usa JSON sobre HTTPS. Esta chamada retorna as últimas cinco demonstrações do resultado anuais da Apple. Não é necessária uma chave.

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

A demonstração é uma entre income_statement, balance_sheet, cash_flow ou supplemental. O tipo de período é um entre annual, quarterly, ltm ou ytd.

Identifique uma empresa

Toda rota de empresa recebe um parâmetro company.

• ticker:AAPL, ou ticker:AAPL.XNAS para identificar a bolsa
• cik:320193, o número da empresa na SEC
• fmd_<id>, o identificador que o FinancialMD atribui à empresa

Um AAPL sem prefixo é interpretado como um ticker, e dígitos sem prefixo, como um CIK. A resposta informa o critério de correspondência em meta.company.matched_by.

Leia um valor

Uma resposta bem-sucedida é { data, meta }. Um número dentro de data nunca aparece isolado. Ele é um objeto de valor:

{
  "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 é o intervalo de tempo em que este era o valor mais recente arquivado na SEC. restated é verdadeiro apenas quando um documento arquivado na SEC posterior alterou o valor; nesse caso, restatement_kind informa como. proof.id remete, em GET /proof/{id}, ao documento arquivado na SEC e aos fatos brutos que fundamentam o valor.

Leia o passado conforme era conhecido

• as_of=2024-06-30 em qualquer rota de leitura retorna o que era conhecido naquele instante.
• original=true retorna a primeira versão divulgada de cada período.
• history=true retorna todas as versões de cada período, da mais antiga para a mais recente.
• GET /v1/changes?since=<timestamp> lista os fatos conhecidos desde então.

Rotas

O documento OpenAPI contém todos os parâmetros e esquemas de resposta. Os arquivos llms.txt, llms-full.txt e o arquivo de habilidade apresentam as mesmas informações para agentes; https://api.financial.md/docs é a referência interativa e https://api.financial.md/changelog lista as alterações.

Confira um número

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

A resposta contém um verdict de matches, differs ou unknown, o valor informado no documento arquivado na SEC com sua prova, a diferença e um scale_hint quando seu número diverge por uma potência de dez.

Limites

Chamadas sem chave são limitadas por endereço IP, por dia.

• 25 chamadas contabilizadas: índices, filtragem e verificação
• 1,000 leituras da camada de documentos arquivados na SEC: demonstrações financeiras, dados conforme reportados, documentos arquivados na SEC, participações acionárias e preços
• 1,000 leituras de metadados: diretório, perfis, métricas, provas e alterações

Toda resposta inclui RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Uma resposta 429 inclui Retry-After.

Chaves de API com limites maiores ainda não são emitidas. Veja Chaves de API. As chamadas em api.financial.md são gratuitas. Agentes podem pagar por chamada em agent.financial.md. Veja Preços.

O que está coberto

A cobertura abrange empresas que arquivam documentos na SEC e estão atualmente listadas em uma bolsa dos EUA.

• Há demonstrações financeiras padronizadas para entidades que arquivam documentos na SEC e reportam segundo US GAAP.
• Entidades que reportam segundo IFRS, como muitas empresas estrangeiras que arquivam Form 20-F ou 40-F, têm documentos arquivados na SEC, mas ainda não têm demonstrações financeiras padronizadas.
• Empresas que deixaram de ser listadas estão no diretório com suas demonstrações financeiras e documentos arquivados na SEC. Consulte-as pelo CIK: elas não têm consulta por ticker nem preços, portanto o histórico de preços cobre apenas empresas listadas atualmente.
• Os dados de participações acionárias vêm de documentos arquivados na SEC desde July 1, 2026 e são atualizados todos os dias às 13:00 UTC a partir do índice diário do EDGAR: transações de pessoas com acesso a informações privilegiadas dos formulários Form 3, Form 4 e Form 5 das empresas cobertas, e todos os Form 13F-HR, de modo que os relatórios 13F de um novo trimestre chegam à medida que os gestores os arquivam. Uma posição 13F é vinculada a uma empresa somente quando a capa de um Schedule 13D ou 13G identifica seu valor mobiliário. Para o trimestre encerrado em June 30, 2026, isso vincula 80 por cento do valor reportado; as demais posições aparecem na carteira de um gestor sob o nome do emissor conforme informado no documento arquivado na SEC.
• Estimativas de consenso e transcrições de teleconferências de resultados não são disponibilizadas: ambas são dados licenciados. Os segmentos são disponibilizados conforme reportados, e as notícias são o feed de documentos arquivados na SEC do tipo 8-K.

Quando uma empresa é conhecida, mas um conjunto de dados está ausente, a API responde not_covered e lista os conjuntos de dados que possui.

Servidor MCP

O servidor MCP disponibiliza a mesma API por meio de 50 ferramentas somente de leitura. Ele usa MCP Streamable HTTP e não exige conta.

https://mcp.financial.md/mcp

O guia MCP lista as ferramentas. O cartão do servidor é destinado a registros.

Erros

Um erro é { "error": { code, message, docs, request_id, remedies } }. A lista remedies informa o que fazer em seguida. A referência de erros explica cada código.