Documentación de API y MCP

Realizar una primera llamada

La API utiliza JSON sobre HTTPS. Esta llamada devuelve los últimos cinco estados de resultados anuales de Apple. No requiere una clave.

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

El estado financiero es uno de income_statement, balance_sheet, cash_flow o supplemental. El tipo de período es uno de annual, quarterly, ltm o ytd.

Identificar una empresa

Cada ruta de empresa acepta un parámetro company.

• ticker:AAPL, o ticker:AAPL.XNAS para indicar la bolsa
• cik:320193, el número de empresa asignado por la SEC
• fmd_<id>, el identificador que FinancialMD asigna a la empresa

Un AAPL sin prefijo se interpreta como un símbolo bursátil y los dígitos sin prefijo, como un CIK. La respuesta indica qué coincidió en meta.company.matched_by.

Leer un valor

Una respuesta correcta es { data, meta }. Un número dentro de data nunca aparece solo. Es un 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 es el intervalo de tiempo durante el cual esta era la última cifra presentada. restated es verdadero solo cuando una presentación ante la SEC (documento presentado) posterior modificó la cifra; en ese caso, restatement_kind indica cómo. proof.id permite acceder mediante GET /proof/{id} a la presentación ante la SEC (documento presentado) y a los datos sin procesar que respaldan el valor.

Leer el pasado tal como se conocía

• as_of=2024-06-30 en cualquier ruta de lectura devuelve lo que se conocía en ese instante.
• original=true devuelve la primera versión publicada de cada período.
• history=true devuelve todas las versiones de cada período, de la más antigua a la más reciente.
• GET /v1/changes?since=<timestamp> enumera los datos conocidos desde entonces.

Rutas

El documento OpenAPI contiene todos los parámetros y esquemas de respuesta. Los archivos llms.txt, llms-full.txt y archivo de habilidades indican lo mismo para los agentes; https://api.financial.md/docs es la referencia interactiva y https://api.financial.md/changelog enumera los cambios.

Compruebe una cifra

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

La respuesta incluye un verdict de matches, differs o unknown, el valor presentado con su prueba, la diferencia y un scale_hint cuando su cifra difiere por una potencia de diez.

Límites

Las llamadas sin clave tienen límites diarios por dirección IP.

• 25 llamadas medidas: ratios, screen y verify
• 1,000 lecturas de la capa de presentaciones ante la SEC (documentos presentados): estados financieros, datos tal como se publicaron, presentaciones ante la SEC (documentos presentados), participaciones accionariales y precios
• 1,000 lecturas de metadatos: directorio, perfiles, métricas, pruebas y cambios

Cada respuesta incluye RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Una respuesta 429 incluye Retry-After.

Todavía no se emiten claves API con límites más altos. Consulta Claves API. Las llamadas a api.financial.md son gratuitas. Los agentes pueden pagar por llamada en agent.financial.md. Consulta Precios.

Qué se cubre

La cobertura incluye empresas que presentan documentos ante la SEC y que cotizan actualmente en una bolsa de Estados Unidos.

• Hay estados financieros estandarizados para las entidades que presentan información conforme a US GAAP.
• Las entidades que presentan información conforme a IFRS, como muchas empresas extranjeras que presentan Form 20-F o 40-F, cuentan con presentaciones ante la SEC (documentos presentados), pero todavía no con estados financieros estandarizados.
• Las empresas que dejaron de cotizar figuran en el directorio con sus estados financieros y presentaciones ante la SEC (documentos presentados). Búscalas por CIK: no admiten búsquedas por símbolo bursátil ni tienen precios, por lo que el historial de precios solo cubre empresas que cotizan actualmente.
• Los datos de participaciones accionariales proceden de presentaciones ante la SEC (documentos presentados) realizadas desde July 1, 2026, y se actualizan cada día a las 13:00 UTC a partir del índice diario de EDGAR: operaciones de personas con información privilegiada de Forms 3, 4 and 5 de las empresas cubiertas, y todos los Form 13F-HR, de modo que los informes 13F de un nuevo trimestre llegan a medida que los gestores los presentan. Una posición 13F se vincula a una empresa solo cuando la portada de un Schedule 13D o 13G identifica su valor. Para el trimestre finalizado el June 30, 2026, esto vincula el 80 por ciento del valor declarado; las demás posiciones aparecen en la cartera del gestor con el nombre del emisor tal como se presentó.
• No se ofrecen estimaciones de consenso ni transcripciones de conferencias de resultados: ambos son datos sujetos a licencia. Los segmentos se ofrecen tal como se publicaron, y las noticias son el flujo de presentaciones ante la SEC (documentos presentados) 8-K.

Cuando se conoce una empresa pero falta un conjunto de datos, la API responde not_covered e indica los conjuntos de datos de los que sí dispone.

Servidor MCP

El servidor MCP expone la misma API mediante 50 herramientas de solo lectura. Utiliza MCP Streamable HTTP y no requiere una cuenta.

https://mcp.financial.md/mcp

La guía de MCP enumera las herramientas. La ficha del servidor está destinada a los registros.

Errores

Un error tiene la estructura { "error": { code, message, docs, request_id, remedies } }. La lista remedies indica qué hacer a continuación. La referencia de errores explica cada código.